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::{exec_err, DataFusionError};
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: 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    /// Returns this `SchemaProvider` as [`Any`] so that it can be downcast to a
45    /// specific implementation.
46    fn as_any(&self) -> &dyn Any;
47
48    /// Retrieves the list of available table names in this schema.
49    fn table_names(&self) -> Vec<String>;
50
51    /// Retrieves a specific table from the schema by name, if it exists,
52    /// otherwise returns `None`.
53    async fn table(
54        &self,
55        name: &str,
56    ) -> Result<Option<Arc<dyn TableProvider>>, DataFusionError>;
57
58    /// Retrieves the type of a specific table from the schema by name, if it exists, otherwise
59    /// returns `None`.  Implementations for which this operation is cheap but [Self::table] is
60    /// expensive can override this to improve operations that only need the type, e.g.
61    /// `SELECT * FROM information_schema.tables`.
62    async fn table_type(&self, name: &str) -> Result<Option<TableType>> {
63        self.table(name).await.map(|o| o.map(|t| t.table_type()))
64    }
65
66    /// If supported by the implementation, adds a new table named `name` to
67    /// this schema.
68    ///
69    /// If a table of the same name was already registered, returns "Table
70    /// already exists" error.
71    #[allow(unused_variables)]
72    fn register_table(
73        &self,
74        name: String,
75        table: Arc<dyn TableProvider>,
76    ) -> Result<Option<Arc<dyn TableProvider>>> {
77        exec_err!("schema provider does not support registering tables")
78    }
79
80    /// If supported by the implementation, removes the `name` table from this
81    /// schema and returns the previously registered [`TableProvider`], if any.
82    ///
83    /// If no `name` table exists, returns Ok(None).
84    #[allow(unused_variables)]
85    fn deregister_table(&self, name: &str) -> Result<Option<Arc<dyn TableProvider>>> {
86        exec_err!("schema provider does not support deregistering tables")
87    }
88
89    /// Returns true if table exist in the schema provider, false otherwise.
90    fn table_exist(&self, name: &str) -> bool;
91}
datafusion_catalog/schema.rs

datafusion_catalog/
schema.rs
