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

datafusion_common/
lib.rs
