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

datafusion_common/
lib.rs
