datafusion_catalog/
schema.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! Describes the interface and built-in implementations of schemas,
19//! representing collections of named tables.
20
21use async_trait::async_trait;
22use datafusion_common::{DataFusionError, exec_err};
23use std::any::Any;
24use std::fmt::Debug;
25use std::sync::Arc;
26
27use crate::table::TableProvider;
28use datafusion_common::Result;
29use datafusion_expr::TableType;
30
31/// Represents a schema, comprising a number of named tables.
32///
33/// Please see [`CatalogProvider`] for details of implementing a custom catalog.
34///
35/// [`CatalogProvider`]: super::CatalogProvider
36#[async_trait]
37pub trait SchemaProvider: Any + Debug + Sync + Send {
38    /// Returns the owner of the Schema, default is None. This value is reported
39    /// as part of `information_tables.schemata
40    fn owner_name(&self) -> Option<&str> {
41        None
42    }
43
44    /// Retrieves the list of available table names in this schema.
45    fn table_names(&self) -> Vec<String>;
46
47    /// Retrieves a specific table from the schema by name, if it exists,
48    /// otherwise returns `None`.
49    async fn table(
50        &self,
51        name: &str,
52    ) -> Result<Option<Arc<dyn TableProvider>>, DataFusionError>;
53
54    /// Retrieves the type of a specific table from the schema by name, if it exists, otherwise
55    /// returns `None`.  Implementations for which this operation is cheap but [Self::table] is
56    /// expensive can override this to improve operations that only need the type, e.g.
57    /// `SELECT * FROM information_schema.tables`.
58    async fn table_type(&self, name: &str) -> Result<Option<TableType>> {
59        self.table(name).await.map(|o| o.map(|t| t.table_type()))
60    }
61
62    /// If supported by the implementation, adds a new table named `name` to
63    /// this schema.
64    ///
65    /// If a table of the same name was already registered, returns "Table
66    /// already exists" error.
67    #[expect(unused_variables)]
68    fn register_table(
69        &self,
70        name: String,
71        table: Arc<dyn TableProvider>,
72    ) -> Result<Option<Arc<dyn TableProvider>>> {
73        exec_err!("schema provider does not support registering tables")
74    }
75
76    /// If supported by the implementation, removes the `name` table from this
77    /// schema and returns the previously registered [`TableProvider`], if any.
78    ///
79    /// If no `name` table exists, returns Ok(None).
80    #[expect(unused_variables)]
81    fn deregister_table(&self, name: &str) -> Result<Option<Arc<dyn TableProvider>>> {
82        exec_err!("schema provider does not support deregistering tables")
83    }
84
85    /// Returns true if table exist in the schema provider, false otherwise.
86    fn table_exist(&self, name: &str) -> bool;
87}
88
89impl dyn SchemaProvider {
90    /// Returns `true` if the schema provider is of type `T`.
91    ///
92    /// Prefer this over `downcast_ref::<T>().is_some()`. Works correctly when
93    /// called on `Arc<dyn SchemaProvider>` via auto-deref.
94    pub fn is<T: SchemaProvider>(&self) -> bool {
95        (self as &dyn Any).is::<T>()
96    }
97
98    /// Attempts to downcast this schema provider to a concrete type `T`,
99    /// returning `None` if the provider is not of that type.
100    ///
101    /// Works correctly when called on `Arc<dyn SchemaProvider>` via auto-deref,
102    /// unlike `(&arc as &dyn Any).downcast_ref::<T>()` which would attempt to
103    /// downcast the `Arc` itself.
104    pub fn downcast_ref<T: SchemaProvider>(&self) -> Option<&T> {
105        (self as &dyn Any).downcast_ref()
106    }
107}
datafusion_catalog/schema.rs

datafusion_catalog/
schema.rs
