datafusion_common/
lib.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#![doc(
19    html_logo_url = "https://raw.githubusercontent.com/apache/datafusion/19fe44cf2f30cbdd63d4a4f52c74055163c6cc38/docs/logos/standalone_logo/logo_original.svg",
20    html_favicon_url = "https://raw.githubusercontent.com/apache/datafusion/19fe44cf2f30cbdd63d4a4f52c74055163c6cc38/docs/logos/standalone_logo/logo_original.svg"
21)]
22#![cfg_attr(docsrs, feature(doc_auto_cfg))]
23// Make sure fast / cheap clones on Arc are explicit:
24// https://github.com/apache/datafusion/issues/11143
25#![deny(clippy::clone_on_ref_ptr)]
26
27mod column;
28mod dfschema;
29mod functional_dependencies;
30mod join_type;
31mod param_value;
32#[cfg(feature = "pyarrow")]
33mod pyarrow;
34mod schema_reference;
35mod table_reference;
36mod unnest;
37
38pub mod alias;
39pub mod cast;
40pub mod config;
41pub mod cse;
42pub mod diagnostic;
43pub mod display;
44pub mod error;
45pub mod file_options;
46pub mod format;
47pub mod hash_utils;
48pub mod instant;
49pub mod parsers;
50pub mod pruning;
51pub mod rounding;
52pub mod scalar;
53pub mod spans;
54pub mod stats;
55pub mod test_util;
56pub mod tree_node;
57pub mod types;
58pub mod utils;
59
60/// Reexport arrow crate
61pub use arrow;
62pub use column::Column;
63pub use dfschema::{
64    qualified_name, DFSchema, DFSchemaRef, ExprSchema, SchemaExt, ToDFSchema,
65};
66pub use diagnostic::Diagnostic;
67pub use error::{
68    field_not_found, unqualified_field_not_found, DataFusionError, Result, SchemaError,
69    SharedResult,
70};
71pub use file_options::file_type::{
72    GetExt, DEFAULT_ARROW_EXTENSION, DEFAULT_AVRO_EXTENSION, DEFAULT_CSV_EXTENSION,
73    DEFAULT_JSON_EXTENSION, DEFAULT_PARQUET_EXTENSION,
74};
75pub use functional_dependencies::{
76    aggregate_functional_dependencies, get_required_group_by_exprs_indices,
77    get_target_functional_dependencies, Constraint, Constraints, Dependency,
78    FunctionalDependence, FunctionalDependencies,
79};
80use hashbrown::hash_map::DefaultHashBuilder;
81pub use join_type::{JoinConstraint, JoinSide, JoinType};
82pub use param_value::ParamValues;
83pub use scalar::{ScalarType, ScalarValue};
84pub use schema_reference::SchemaReference;
85pub use spans::{Location, Span, Spans};
86pub use stats::{ColumnStatistics, Statistics};
87pub use table_reference::{ResolvedTableReference, TableReference};
88pub use unnest::{RecursionUnnestOption, UnnestOptions};
89pub use utils::project_schema;
90
91// These are hidden from docs purely to avoid polluting the public view of what this crate exports.
92// These are just re-exports of macros by the same name, which gets around the 'cannot refer to
93// macro-expanded macro_export macros by their full path' error.
94// The design to get around this comes from this comment:
95// https://github.com/rust-lang/rust/pull/52234#issuecomment-976702997
96#[doc(hidden)]
97pub use error::{
98    _config_datafusion_err, _exec_datafusion_err, _internal_datafusion_err,
99    _not_impl_datafusion_err, _plan_datafusion_err, _resources_datafusion_err,
100    _substrait_datafusion_err,
101};
102
103// The HashMap and HashSet implementations that should be used as the uniform defaults
104pub type HashMap<K, V, S = DefaultHashBuilder> = hashbrown::HashMap<K, V, S>;
105pub type HashSet<T, S = DefaultHashBuilder> = hashbrown::HashSet<T, S>;
106
107/// Downcast an Arrow Array to a concrete type, return an `DataFusionError::Internal` if the cast is
108/// not possible. In normal usage of DataFusion the downcast should always succeed.
109///
110/// Example: `let array = downcast_value!(values, Int32Array)`
111#[macro_export]
112macro_rules! downcast_value {
113    ($Value: expr, $Type: ident) => {{
114        use $crate::__private::DowncastArrayHelper;
115        $Value.downcast_array_helper::<$Type>()?
116    }};
117    ($Value: expr, $Type: ident, $T: tt) => {{
118        use $crate::__private::DowncastArrayHelper;
119        $Value.downcast_array_helper::<$Type<$T>>()?
120    }};
121}
122
123// Not public API.
124#[doc(hidden)]
125pub mod __private {
126    use crate::error::_internal_datafusion_err;
127    use crate::Result;
128    use arrow::array::Array;
129    use std::any::{type_name, Any};
130
131    #[doc(hidden)]
132    pub trait DowncastArrayHelper {
133        fn downcast_array_helper<U: Any>(&self) -> Result<&U>;
134    }
135
136    impl<T: Array + ?Sized> DowncastArrayHelper for T {
137        fn downcast_array_helper<U: Any>(&self) -> Result<&U> {
138            self.as_any().downcast_ref().ok_or_else(|| {
139                _internal_datafusion_err!(
140                    "could not cast array of type {} to {}",
141                    self.data_type(),
142                    type_name::<U>()
143                )
144            })
145        }
146    }
147}
148
149#[cfg(test)]
150mod tests {
151    use arrow::array::{ArrayRef, Int32Array, UInt64Array};
152    use std::any::{type_name, type_name_of_val};
153    use std::sync::Arc;
154
155    #[test]
156    fn test_downcast_value() -> crate::Result<()> {
157        let boxed: ArrayRef = Arc::new(Int32Array::from(vec![1, 2, 3]));
158        let array = downcast_value!(&boxed, Int32Array);
159        assert_eq!(type_name_of_val(&array), type_name::<&Int32Array>());
160
161        let expected: Int32Array = vec![1, 2, 3].into_iter().map(Some).collect();
162        assert_eq!(array, &expected);
163        Ok(())
164    }
165
166    #[test]
167    fn test_downcast_value_err_message() {
168        let boxed: ArrayRef = Arc::new(Int32Array::from(vec![1, 2, 3]));
169        let error: crate::DataFusionError = (|| {
170            downcast_value!(&boxed, UInt64Array);
171            Ok(())
172        })()
173        .err()
174        .unwrap();
175
176        assert_starts_with(
177            error.to_string(),
178            "Internal error: could not cast array of type Int32 to arrow_array::array::primitive_array::PrimitiveArray<arrow_array::types::UInt64Type>"
179        );
180    }
181
182    // `err.to_string()` depends on backtrace being present (may have backtrace appended)
183    // `err.strip_backtrace()` also depends on backtrace being present (may have "This was likely caused by ..." stripped)
184    fn assert_starts_with(actual: impl AsRef<str>, expected_prefix: impl AsRef<str>) {
185        let actual = actual.as_ref();
186        let expected_prefix = expected_prefix.as_ref();
187        assert!(
188            actual.starts_with(expected_prefix),
189            "Expected '{actual}' to start with '{expected_prefix}'"
190        );
191    }
192}
datafusion_common/lib.rs

datafusion_common/
lib.rs
