Apache DataFusion SQL Query Engine
perf: index DFSchema field names to avoid quadratic lookups on wide schemas (#26630)
Peter L5ec177a930e5
diff --git a/clippy.toml b/clippy.tomlindex 7b781d9b66..0957d177a3 100644--- a/clippy.toml+++ b/clippy.toml@@ -21,3 +21,8 @@ future-size-threshold = 10000# - https://github.com/apache/datafusion/issues/16652# - https://rust-lang.github.io/rust-clippy/master/index.html#result_large_errlarge-error-threshold = 70++# `DFSchema` caches a name index in a `OnceLock`, which is excluded from its+# `Hash` and `Eq`, so plans and expressions containing it are safe hash keys.+# See: https://rust-lang.github.io/rust-clippy/master/index.html#mutable_key_type+ignore-interior-mutability = ["bytes::Bytes", "datafusion_common::DFSchema"]diff --git a/datafusion/common/src/dfschema.rs b/datafusion/common/src/dfschema.rsindex 24f77f2e00..2bcd5edfd3 100644--- a/datafusion/common/src/dfschema.rs+++ b/datafusion/common/src/dfschema.rs@@ -8,10 +8,11 @@use std::collections::{BTreeSet, HashSet};use std::fmt::Write as _;use std::fmt::{Display, Formatter};-use std::hash::Hash;-use std::sync::{Arc, LazyLock};+use std::hash::{BuildHasher, Hash};+use std::sync::{Arc, LazyLock, OnceLock};use crate::error::{_plan_err, _schema_err, DataFusionError, Result};+use crate::hash_utils::RandomState;use crate::{Column, FunctionalDependencies, SchemaError, TableReference, field_not_found,unqualified_field_not_found,@@ -21,6 +22,7 @@ use arrow::compute::can_cast_types;use arrow::datatypes::{DataType, Field, FieldRef, Fields, Metadata, Schema, SchemaBuilder, SchemaRef,};+use hashbrown::hash_table::{Entry, HashTable};/// A reference-counted reference to a [DFSchema].pub type DFSchemaRef = Arc<DFSchema>;@@ -96,7 +98,7 @@ pub type DFSchemaRef = Arc<DFSchema>;/// let schema: &Schema = df_schema.as_arrow();/// assert_eq!(schema.fields().len(), 1);/// ```-#[derive(Debug, Clone, PartialEq, Eq)]+#[derive(Clone)]pub struct DFSchema {/// Inner Arrow schema reference.inner: SchemaRef,@@ -105,6 +107,13 @@ pub struct DFSchema {field_qualifiers: Vec<Option<TableReference>>,/// Stores functional dependencies in the schema.functional_dependencies: FunctionalDependencies,+ /// Lazily built lookup from field name to positions in `inner`, only used+ /// for schemas with more than [`LINEAR_NAME_SCAN_MAX`] fields.+ ///+ /// Derived from the field names alone, so it is shared by clones and must+ /// be reset whenever `inner` changes. It takes no part in equality,+ /// hashing or `Debug` output.+ name_index: OnceLock<Arc<NameIndex>>,}impl DFSchema {@@ -114,6 +123,7 @@ impl DFSchema {inner: Arc::new(Schema::new([])),field_qualifiers: vec![],functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),}}@@ -152,6 +162,7 @@ impl DFSchema {inner: schema,field_qualifiers: qualifiers,functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),};dfschema.check_names()?;Ok(dfschema)@@ -168,6 +179,7 @@ impl DFSchema {inner: schema,field_qualifiers: vec![None; field_count],functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),};dfschema.check_names()?;Ok(dfschema)@@ -186,6 +198,7 @@ impl DFSchema {inner: schema.clone().into(),field_qualifiers: vec![Some(qualifier); schema.fields.len()],functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),};schema.check_names()?;Ok(schema)@@ -200,6 +213,7 @@ impl DFSchema {inner: Arc::clone(schema),field_qualifiers: qualifiers,functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),};dfschema.check_names()?;Ok(dfschema)@@ -221,6 +235,7 @@ impl DFSchema {inner: Arc::clone(&self.inner),field_qualifiers: qualifiers,functional_dependencies: self.functional_dependencies.clone(),+ name_index: OnceLock::new(),})}@@ -291,6 +306,7 @@ impl DFSchema {inner: Arc::new(new_schema_with_metadata),field_qualifiers: new_qualifiers,functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),};new_self.check_names()?;Ok(new_self)@@ -347,6 +363,7 @@ impl DFSchema {let finished_with_metadata = finished.with_metadata(metadata);self.inner = finished_with_metadata.into();self.field_qualifiers.extend(qualifiers);+ self.name_index = OnceLock::new();}/// Get a list of fields for this schema@@ -368,26 +385,53 @@ impl DFSchema {(self.field_qualifiers[i].as_ref(), self.field(i))}+ /// Returns the indices of the fields named `name`, in ascending order.+ ///+ /// Narrow schemas are scanned; wider ones consult [`Self::name_index`].+ fn indices_of_name<'a>(&'a self, name: &'a str) -> NameIndices<'a> {+ let fields = self.fields();+ match self.name_index() {+ Some(index) => NameIndices::Indexed {+ next: index.first_index_of(fields, name),+ index,+ },+ None => NameIndices::Scan {+ fields: fields.iter().enumerate(),+ name,+ },+ }+ }++ /// Returns the name index, building it on first use, or `None` if the+ /// schema is too narrow for an index to beat a scan.+ fn name_index(&self) -> Option<&NameIndex> {+ let fields = self.fields();+ if fields.len() <= LINEAR_NAME_SCAN_MAX {+ return None;+ }+ Some(+ self.name_index+ .get_or_init(|| Arc::new(NameIndex::new(fields))),+ )+ }+pub fn index_of_column_by_name(&self,qualifier: Option<&TableReference>,name: &str,) -> Option<usize> {- let mut matches = self- .iter()- .enumerate()- .filter(|(_, (q, f))| match (qualifier, q) {+ self.indices_of_name(name).find(|&idx| {+ match (qualifier, &self.field_qualifiers[idx]) {// field to lookup is qualified.// current field is qualified and not shared between relations, compare both// qualifier and name.- (Some(q), Some(field_q)) => q.resolved_eq(field_q) && f.name() == name,+ (Some(q), Some(field_q)) => q.resolved_eq(field_q),// field to lookup is qualified but current field is unqualified.(Some(_), None) => false,// field to lookup is unqualified, no need to compare qualifier- (None, Some(_)) | (None, None) => f.name() == name,- })- .map(|(idx, _)| idx);- matches.next()+ (None, Some(_)) | (None, None) => true,+ }+ })}/// Find the index of the column with the given qualifier and name,@@ -465,9 +509,8 @@ impl DFSchema {/// Find all fields that match the given namepub fn fields_with_unqualified_name(&self, name: &str) -> Vec<&FieldRef> {- self.fields()- .iter()- .filter(|field| field.name() == name)+ self.indices_of_name(name)+ .map(|idx| self.field(idx)).collect()}@@ -476,16 +519,18 @@ impl DFSchema {&self,name: &str,) -> Vec<(Option<&TableReference>, &FieldRef)> {- self.iter()- .filter(|(_, field)| field.name() == name)+ self.indices_of_name(name)+ .map(|idx| self.qualified_field(idx)).collect()}/// Find all fields that match the given name and convert to columnpub fn columns_with_unqualified_name(&self, name: &str) -> Vec<Column> {- self.iter()- .filter(|(_, field)| field.name() == name)- .map(|(qualifier, field)| Column::new(qualifier.cloned(), field.name()))+ self.indices_of_name(name)+ .map(|idx| {+ let (qualifier, field) = self.qualified_field(idx);+ Column::new(qualifier.cloned(), field.name())+ }).collect()}@@ -559,7 +604,7 @@ impl DFSchema {/// Find if the field exists with the given namepub fn has_column_with_unqualified_name(&self, name: &str) -> bool {- self.fields().iter().any(|field| field.name() == name)+ self.indices_of_name(name).next().is_some()}/// Find if the field exists with the given qualified name@@ -568,8 +613,11 @@ impl DFSchema {qualifier: &TableReference,name: &str,) -> bool {- self.iter()- .any(|(q, f)| q.map(|q| q.eq(qualifier)).unwrap_or(false) && f.name() == name)+ self.indices_of_name(name).any(|idx| {+ self.field_qualifiers[idx]+ .as_ref()+ .is_some_and(|q| q.eq(qualifier))+ })}/// Find if the field exists with the given qualified column@@ -833,6 +881,7 @@ impl DFSchema {field_qualifiers: vec![None; self.inner.fields.len()],inner: self.inner,functional_dependencies: self.functional_dependencies,+ name_index: OnceLock::new(),}}@@ -843,6 +892,7 @@ impl DFSchema {field_qualifiers: vec![Some(qualifier); self.inner.fields.len()],inner: self.inner,functional_dependencies: self.functional_dependencies,+ name_index: OnceLock::new(),}}@@ -1126,6 +1176,7 @@ impl TryFrom<SchemaRef> for DFSchema {inner: schema,field_qualifiers: vec![None; field_count],functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),};dfschema.check_names()?;Ok(dfschema)@@ -1146,6 +1197,116 @@ impl Hash for DFSchema {}}+// `name_index` is derived state, so it is left out of equality and `Debug`.+impl PartialEq for DFSchema {+ fn eq(&self, other: &Self) -> bool {+ self.inner == other.inner+ && self.field_qualifiers == other.field_qualifiers+ && self.functional_dependencies == other.functional_dependencies+ }+}++impl Eq for DFSchema {}++impl std::fmt::Debug for DFSchema {+ fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {+ f.debug_struct("DFSchema")+ .field("inner", &self.inner)+ .field("field_qualifiers", &self.field_qualifiers)+ .field("functional_dependencies", &self.functional_dependencies)+ .finish()+ }+}++/// Schemas with up to this many fields resolve names by comparing against every+/// field; wider ones use a lazily built [`NameIndex`]. Below it, the scan is+/// cheaper than building the index (the same trade-off as+/// `LINEAR_FIELD_SCAN_MAX` in `datafusion-datasource-parquet`).+const LINEAR_NAME_SCAN_MAX: usize = 8;++/// Marks the last field with a given name in [`NameIndex::next`].+const NO_NEXT: usize = usize::MAX;++/// Field positions by name, so resolving a name in a wide schema does not+/// compare it against every field.+///+/// Stores indices rather than copies of the names: `first` holds the lowest+/// index for each distinct name, and `next` links each index to the next one+/// with the same name. Following the links visits duplicate names in ascending+/// order, the same order as a scan.+struct NameIndex {+ first: HashTable<usize>,+ next: Vec<usize>,+}++impl NameIndex {+ fn new(fields: &Fields) -> Self {+ let mut first = HashTable::with_capacity(fields.len());+ let mut next = vec![NO_NEXT; fields.len()];+ // Visit fields in reverse so each index becomes the new head of its+ // name's list, keeping the list in ascending order.+ for (idx, field) in fields.iter().enumerate().rev() {+ let name = field.name().as_str();+ match first.entry(+ hash_name(name),+ |&other: &usize| fields[other].name() == name,+ |&other: &usize| hash_name(fields[other].name()),+ ) {+ Entry::Occupied(mut entry) => {+ next[idx] = *entry.get();+ *entry.get_mut() = idx;+ }+ Entry::Vacant(entry) => {+ entry.insert(idx);+ }+ }+ }+ Self { first, next }+ }++ /// Returns the lowest index of a field named `name`, if any. `fields` must+ /// be the fields this index was built from.+ fn first_index_of(&self, fields: &Fields, name: &str) -> Option<usize> {+ self.first+ .find(hash_name(name), |&idx| fields[idx].name() == name)+ .copied()+ }+}++/// Indices of the fields with a given name, in ascending order; see+/// [`DFSchema::indices_of_name`].+enum NameIndices<'a> {+ Scan {+ fields: std::iter::Enumerate<std::slice::Iter<'a, FieldRef>>,+ name: &'a str,+ },+ Indexed {+ index: &'a NameIndex,+ next: Option<usize>,+ },+}++impl Iterator for NameIndices<'_> {+ type Item = usize;++ fn next(&mut self) -> Option<usize> {+ match self {+ Self::Scan { fields, name } => fields+ .find(|(_, field)| field.name() == *name)+ .map(|(idx, _)| idx),+ Self::Indexed { index, next } => {+ let idx = (*next)?;+ *next = Some(index.next[idx]).filter(|&next| next != NO_NEXT);+ Some(idx)+ }+ }+ }+}++fn hash_name(name: &str) -> u64 {+ RandomState::default().hash_one(name)+}+/// Convenience trait to convert Schema like things to DFSchema and DFSchemaRef with fewer keystrokespub trait ToDFSchemawhere@@ -1183,6 +1344,7 @@ impl ToDFSchema for Vec<Field> {inner: schema.into(),field_qualifiers: vec![None; field_count],functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),};Ok(dfschema)}@@ -1669,6 +1831,7 @@ mod tests {inner: Arc::clone(&arrow_schema_ref),field_qualifiers: vec![None; arrow_schema_ref.fields.len()],functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),};let df_schema_ref = Arc::new(df_schema.clone());@@ -1715,6 +1878,7 @@ mod tests {inner: Arc::clone(&schema),field_qualifiers: vec![None; schema.fields.len()],functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),};assert_eq!(df_schema.inner.metadata(), schema.metadata())@@ -1753,6 +1917,152 @@ mod tests {Ok(())}+ /// Builds a schema of `fields` padded with uniquely named fields to `width`.+ /// Bypasses `check_names`, since `merge` can produce the same name both+ /// qualified and unqualified.+ fn name_lookup_schema(+ fields: &[(Option<TableReference>, &str)],+ width: usize,+ ) -> DFSchema {+ let mut qualifiers = vec![];+ let mut arrow_fields = vec![];+ for (qualifier, name) in fields {+ qualifiers.push(qualifier.clone());+ arrow_fields.push(Field::new(*name, DataType::Int32, true));+ }+ for i in fields.len()..width {+ qualifiers.push(Some(TableReference::bare("pad")));+ arrow_fields.push(Field::new(format!("pad_{i}"), DataType::Int32, true));+ }+ DFSchema {+ inner: Arc::new(Schema::new(arrow_fields)),+ field_qualifiers: qualifiers,+ functional_dependencies: FunctionalDependencies::empty(),+ name_index: OnceLock::new(),+ }+ }++ /// The name lookups as they were before the name index, kept as a reference.+ fn scan_index_of_column_by_name(+ schema: &DFSchema,+ qualifier: Option<&TableReference>,+ name: &str,+ ) -> Option<usize> {+ schema.iter().position(|(q, f)| match (qualifier, q) {+ (Some(q), Some(field_q)) => q.resolved_eq(field_q) && f.name() == name,+ (Some(_), None) => false,+ (None, _) => f.name() == name,+ })+ }++ #[test]+ fn name_index_matches_scan() {+ let t1 = TableReference::bare("t1");+ let t2 = TableReference::bare("t2");+ let public_t1 = TableReference::partial("public", "t1");+ let fields = [+ (Some(t2.clone()), "a"),+ (Some(t1.clone()), "a"),+ (None, "a"),+ (Some(public_t1.clone()), "a"),+ (Some(t2.clone()), "b"),+ (None, "c"),+ (None, "c"),+ (Some(t1.clone()), "ü"),+ ];+ let qualifiers = [+ None,+ Some(t1.clone()),+ Some(t2.clone()),+ Some(public_t1.clone()),+ Some(TableReference::bare("missing")),+ ];+ let names = ["a", "b", "c", "ü", "u", "missing", "pad_40"];++ for width in [LINEAR_NAME_SCAN_MAX, LINEAR_NAME_SCAN_MAX + 1, 100] {+ // Narrow widths keep a prefix of `fields`, so the scan path is covered.+ let schema = name_lookup_schema(&fields[..fields.len().min(width)], width);+ for name in names {+ let scanned: Vec<_> =+ schema.iter().filter(|(_, f)| f.name() == name).collect();+ assert_eq!(+ schema.qualified_fields_with_unqualified_name(name),+ scanned,+ "width {width}, name {name}"+ );+ assert_eq!(+ schema.fields_with_unqualified_name(name),+ scanned.iter().map(|(_, f)| *f).collect::<Vec<_>>(),+ "width {width}, name {name}"+ );+ assert_eq!(+ schema.columns_with_unqualified_name(name),+ scanned+ .iter()+ .map(|(q, f)| Column::new(q.cloned(), f.name()))+ .collect::<Vec<_>>(),+ "width {width}, name {name}"+ );+ assert_eq!(+ schema.has_column_with_unqualified_name(name),+ !scanned.is_empty()+ );+ for qualifier in &qualifiers {+ assert_eq!(+ schema.index_of_column_by_name(qualifier.as_ref(), name),+ scan_index_of_column_by_name(&schema, qualifier.as_ref(), name),+ "width {width}, qualifier {qualifier:?}, name {name}"+ );+ if let Some(qualifier) = qualifier {+ assert_eq!(+ schema.has_column_with_qualified_name(qualifier, name),+ scanned.iter().any(|(q, _)| *q == Some(qualifier)),+ "width {width}, qualifier {qualifier}, name {name}"+ );+ }+ }+ }+ assert_eq!(+ schema.name_index.get().is_some(),+ width > LINEAR_NAME_SCAN_MAX,+ "width {width}"+ );+ }+ }++ #[test]+ fn name_index_follows_schema_changes() {+ let mut schema = name_lookup_schema(&[(None, "a")], LINEAR_NAME_SCAN_MAX + 1);+ assert_eq!(schema.index_of_column_by_name(None, "a"), Some(0));+ let index = Arc::clone(schema.name_index.get().unwrap());++ // The index is derived state, so it must not show in equality or `Debug`.+ let unprobed = name_lookup_schema(&[(None, "a")], LINEAR_NAME_SCAN_MAX + 1);+ assert!(unprobed.name_index.get().is_none());+ assert_eq!(schema, unprobed);+ assert_eq!(format!("{schema:?}"), format!("{unprobed:?}"));++ // Clones keep the fields, so they share the index.+ assert!(Arc::ptr_eq(+ schema.clone().name_index.get().unwrap(),+ &index+ ));+ let replaced = schema.clone().replace_qualifier("t");+ assert_eq!(+ replaced.index_of_column_by_name(Some(&TableReference::bare("t")), "a"),+ Some(0)+ );++ // Merging appends fields, so the index must not answer for the old ones.+ let other = name_lookup_schema(&[(None, "b")], 1);+ schema.merge(&other);+ assert_eq!(+ schema.index_of_column_by_name(None, "b"),+ Some(LINEAR_NAME_SCAN_MAX + 1)+ );+ assert!(!Arc::ptr_eq(schema.name_index.get().unwrap(), &index));+ }+#[test]fn test_datatype_is_logically_equal() {assert!(DFSchema::datatype_is_logically_equal(