Coverage Report

Created: 2024-10-13 08:39

/Users/andrewlamb/Software/datafusion/datafusion/expr/src/table_source.rs
Line
Count
Source (jump to first uncovered line)
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
//! Table source
19
20
use crate::{Expr, LogicalPlan};
21
22
use arrow::datatypes::SchemaRef;
23
use datafusion_common::{Constraints, Result};
24
25
use std::{any::Any, borrow::Cow};
26
27
/// Indicates how a filter expression is handled by
28
/// [`TableProvider::scan`].
29
///
30
/// Filter expressions are boolean expressions used to reduce the number of
31
/// rows that are read from a table. Only rows that evaluate to `true` ("pass
32
/// the filter") are returned. Rows that evaluate to `false` or `NULL` are
33
/// omitted.
34
///
35
/// [`TableProvider::scan`]: https://docs.rs/datafusion/latest/datafusion/datasource/provider/trait.TableProvider.html#tymethod.scan
36
#[derive(Debug, Clone, PartialEq, Eq)]
37
pub enum TableProviderFilterPushDown {
38
    /// The filter cannot be used by the provider and will not be pushed down.
39
    Unsupported,
40
    /// The filter can be used, but the provider might still return some tuples
41
    /// that do not pass the filter.
42
    ///
43
    /// In this case, DataFusion applies an additional `Filter` operation
44
    /// after the scan to ensure all rows are filtered correctly.
45
    Inexact,
46
    /// The provider **guarantees** that it will omit **only** tuples which
47
    /// pass the filter.
48
    ///
49
    /// In this case, DataFusion will not apply additional filtering.
50
    Exact,
51
}
52
53
/// Indicates the type of this table for metadata/catalog purposes.
54
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
55
pub enum TableType {
56
    /// An ordinary physical table.
57
    Base,
58
    /// A non-materialised table that itself uses a query internally to provide data.
59
    View,
60
    /// A transient table.
61
    Temporary,
62
}
63
64
impl std::fmt::Display for TableType {
65
0
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
66
0
        match self {
67
0
            TableType::Base => write!(f, "Base"),
68
0
            TableType::View => write!(f, "View"),
69
0
            TableType::Temporary => write!(f, "Temporary"),
70
        }
71
0
    }
72
}
73
74
/// Access schema information and filter push-down capabilities.
75
///
76
/// The TableSource trait is used during logical query planning and
77
/// optimizations and provides a subset of the functionality of the
78
/// `TableProvider` trait in the (core) `datafusion` crate. The `TableProvider`
79
/// trait provides additional capabilities needed for physical query execution
80
/// (such as the ability to perform a scan).
81
///
82
/// The reason for having two separate traits is to avoid having the logical
83
/// plan code be dependent on the DataFusion execution engine. Some projects use
84
/// DataFusion's logical plans and have their own execution engine.
85
pub trait TableSource: Sync + Send {
86
    fn as_any(&self) -> &dyn Any;
87
88
    /// Get a reference to the schema for this table
89
    fn schema(&self) -> SchemaRef;
90
91
    /// Get primary key indices, if one exists.
92
0
    fn constraints(&self) -> Option<&Constraints> {
93
0
        None
94
0
    }
95
96
    /// Get the type of this table for metadata/catalog purposes.
97
0
    fn table_type(&self) -> TableType {
98
0
        TableType::Base
99
0
    }
100
101
    /// Tests whether the table provider can make use of any or all filter expressions
102
    /// to optimise data retrieval.
103
0
    fn supports_filters_pushdown(
104
0
        &self,
105
0
        filters: &[&Expr],
106
0
    ) -> Result<Vec<TableProviderFilterPushDown>> {
107
0
        Ok((0..filters.len())
108
0
            .map(|_| TableProviderFilterPushDown::Unsupported)
109
0
            .collect())
110
0
    }
111
112
    /// Get the Logical plan of this table provider, if available.
113
0
    fn get_logical_plan(&self) -> Option<Cow<LogicalPlan>> {
114
0
        None
115
0
    }
116
117
    /// Get the default value for a column, if available.
118
0
    fn get_column_default(&self, _column: &str) -> Option<&Expr> {
119
0
        None
120
0
    }
121
}