Apache DataFusion SQL Query Engine
Feat: add dictionaries as a supported group column type (#23187)
RIchard Baahc1b39bd503ce
diff --git a/datafusion/physical-plan/src/aggregates/group_values/multi_group_by/dictionary.rs b/datafusion/physical-plan/src/aggregates/group_values/multi_group_by/dictionary.rsnew file mode 100644index 0000000000..501b13d0cd--- /dev/null+++ b/datafusion/physical-plan/src/aggregates/group_values/multi_group_by/dictionary.rs@@ -0,0 +1,841 @@+// Licensed to the Apache Software Foundation (ASF) under one+// or more contributor license agreements. See the NOTICE file+// distributed with this work for additional information+// regarding copyright ownership. The ASF licenses this file+// to you under the Apache License, Version 2.0 (the+// "License"); you may not use this file except in compliance+// with the License. You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing,+// software distributed under the License is distributed on an+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY+// KIND, either express or implied. See the License for the+// specific language governing permissions and limitations+// under the License.++use crate::aggregates::group_values::multi_group_by::GroupColumn;+use arrow::array::{+ Array, ArrayRef, AsArray, BooleanBufferBuilder, DictionaryArray, Int64Array,+ PrimitiveArray,+};+use arrow::compute::take;+use arrow::datatypes::{ArrowDictionaryKeyType, ArrowNativeType, DataType, Field};+use arrow::error::ArrowError;+use datafusion_common::hash_utils::{RandomState, create_hashes};+use datafusion_common::{DataFusionError, Result, exec_err};+use datafusion_execution::memory_pool::proxy::HashTableAllocExt;+use hashbrown::hash_table::HashTable;+use std::marker::PhantomData;+use std::mem::size_of;+use std::sync::Arc;++use crate::aggregates::AGGREGATION_HASH_SEED;++/// [`GroupColumn`] for dictionary-encoded columns with key type `K`.+///+/// `inner` holds one slot per distinct value seen across all batches.+/// `group_to_inner[group_idx]` maps each group to its slot in `inner`,+/// so groups with the same value share a slot rather than duplicating data.+pub struct DictionaryGroupValuesColumn<K: ArrowDictionaryKeyType + Send + Sync> {+ /// Deduplicated store of distinct values.+ inner: Box<dyn GroupColumn>,+ /// Unary null array (length 1) reused for every null appended to `inner`.+ null_array: ArrayRef,+ /// Maps each group index to its slot in `inner`.+ group_to_inner: Vec<usize>,+ /// Lookup table mapping `(value_hash, inner_slot)` for each non-null distinct value.+ value_dedup: HashTable<(u64, usize)>,+ /// Tracked allocation size of `value_dedup` for memory accounting via `size()`.+ value_dedup_size: usize,+ /// Slot in `inner` for the null group; `None` until the first null is seen.+ null_inner_slot: Option<usize>,+ /// Hash seed — must match `create_hashes` so hashes are consistent across calls.+ random_state: RandomState,+ /// Reusable scratch buffer mapping `val_idx → inner_slot` across batches.+ val_to_inner: Vec<usize>,+ /// Reusable hash buffer for the dictionary values array.+ val_hashes: Vec<u64>,+ _phantom: PhantomData<K>,+}++impl<K: ArrowDictionaryKeyType + Send + Sync> DictionaryGroupValuesColumn<K> {+ pub fn new(inner: Box<dyn GroupColumn>, field: &Field) -> Self {+ let null_array = arrow::array::new_null_array(field.data_type(), 1);+ Self {+ inner,+ null_array,+ group_to_inner: Vec::new(),+ value_dedup: HashTable::new(),+ value_dedup_size: 0,+ null_inner_slot: None,+ random_state: AGGREGATION_HASH_SEED,+ val_to_inner: Vec::default(),+ val_hashes: Vec::default(),+ _phantom: PhantomData,+ }+ }++ /// Build a `DictionaryArray` from `values` (all inner slots) and the+ /// per-group slot mapping. The null inner slot, if any, is excluded from+ /// the values array and its groups emit a null key — so it never consumes+ /// a key index regardless of where it sits in `inner`.+ fn into_dict(+ values: ArrayRef,+ group_to_inner: &[usize],+ null_inner_slot: Option<usize>,+ ) -> ArrayRef {+ let Some(null_slot) = null_inner_slot else {+ // Fast path: no null group — raw slot indices are valid keys.+ let keys: PrimitiveArray<K> = group_to_inner+ .iter()+ .map(|&slot| Some(K::Native::usize_as(slot)))+ .collect();+ return Arc::new(DictionaryArray::<K>::new(keys, values));+ };++ // Build a compact remap: each non-null slot gets a contiguous key+ // starting from 0; the null slot is skipped entirely.+ let n = values.len();+ let mut remap = vec![0usize; n];+ let mut next = 0usize;+ for (i, mapped) in remap.iter_mut().enumerate() {+ if i != null_slot {+ *mapped = next;+ next += 1;+ }+ }++ let keys: PrimitiveArray<K> = group_to_inner+ .iter()+ .map(|&slot| {+ if slot == null_slot {+ None+ } else {+ Some(K::Native::usize_as(remap[slot]))+ }+ })+ .collect();++ // Compact values array: drop the null slot so key indices stay tight.+ let compact_indices: Int64Array = (0..n)+ .filter(|&i| i != null_slot)+ .map(|i| i as i64)+ .collect();+ let compact =+ take(&*values, &compact_indices, None).expect("compact values in into_dict");+ Arc::new(DictionaryArray::<K>::new(keys, compact))+ }++ // https://github.com/apache/datafusion/issues/23127+ // Null groups emit a null key (None), not a slot index, so the null inner+ // slot never consumes a key index regardless of its position in inner.+ fn check_key_overflow(&self) -> Result<()> {+ let non_null_count = self.inner.len() - self.null_inner_slot.is_some() as usize;+ if !Self::key_type_fits(non_null_count) {+ return exec_err!(+ "Dictionary key type {:?} cannot represent {} distinct values",+ K::DATA_TYPE,+ non_null_count+ );+ }+ Ok(())+ }++ fn key_type_fits(num_values: usize) -> bool {+ let max: usize = match K::DATA_TYPE {+ DataType::Int8 => i8::MAX as usize,+ DataType::Int16 => i16::MAX as usize,+ DataType::Int32 => i32::MAX as usize,+ DataType::Int64 => i64::MAX as usize,+ DataType::UInt8 => u8::MAX as usize,+ DataType::UInt16 => u16::MAX as usize,+ DataType::UInt32 => u32::MAX as usize,+ DataType::UInt64 => usize::MAX,+ _ => return false,+ };+ num_values == 0 || num_values - 1 <= max+ }++ fn hash_values(&mut self, values: &ArrayRef) {+ self.val_hashes.clear();+ self.val_hashes.resize(values.len(), 0);+ create_hashes(+ std::slice::from_ref(values),+ &self.random_state,+ &mut self.val_hashes,+ )+ .unwrap();+ }++ fn find_or_insert_value(+ &mut self,+ dict_values: &ArrayRef,+ val_idx: usize,+ hash: u64,+ ) -> Result<usize> {+ let inner = &*self.inner;+ let existing = self+ .value_dedup+ .find(hash, |&(entry_hash, slot)| {+ entry_hash == hash && inner.equal_to(slot, dict_values, val_idx)+ })+ .map(|&(_, slot)| slot);++ match existing {+ Some(slot) => Ok(slot),+ None => {+ let slot = self.inner.len();+ self.inner.append_val(dict_values, val_idx)?;+ self.value_dedup.insert_accounted(+ (hash, slot),+ |&(entry_hash, _)| entry_hash,+ &mut self.value_dedup_size,+ );+ Ok(slot)+ }+ }+ }++ fn find_or_insert_null(&mut self) -> Result<usize> {+ if let Some(slot) = self.null_inner_slot {+ return Ok(slot);+ }+ let slot = self.inner.len();+ self.inner.append_val(&self.null_array, 0)?;+ self.null_inner_slot = Some(slot);+ Ok(slot)+ }++ fn build_lookup_table(+ &self,+ dict_values: &ArrayRef,+ val_hashes: &[u64],+ ) -> Vec<usize> {+ let num_distinct = dict_values.len();+ let mut table = vec![usize::MAX; num_distinct + 1];+ let inner = &*self.inner;+ for val_idx in 0..num_distinct {+ if dict_values.is_null(val_idx) {+ table[val_idx] = self.null_inner_slot.unwrap_or(usize::MAX);+ } else {+ let hash = val_hashes[val_idx];+ if let Some(&(_, slot)) =+ self.value_dedup.find(hash, |&(entry_hash, slot)| {+ entry_hash == hash && inner.equal_to(slot, dict_values, val_idx)+ })+ {+ table[val_idx] = slot;+ }+ }+ }+ table[num_distinct] = self.null_inner_slot.unwrap_or(usize::MAX);+ table+ }++ /// Per-row fallback for `vectorized_equal_to` used when the number of rows+ /// to check is smaller than the dictionary cardinality, making the O(D)+ /// lookup-table build more expensive than direct value comparison.+ ///+ /// `#[cold]` + `#[inline(never)]` keeps this code out of the hot+ /// lookup-table loops in `vectorized_equal_to` so LLVM can pipeline them.+ #[cold]+ #[inline(never)]+ fn equal_to_per_row(+ &self,+ lhs_rows: &[usize],+ dict_values: &ArrayRef,+ dict: &DictionaryArray<K>,+ rhs_rows: &[usize],+ equal_to_results: &mut BooleanBufferBuilder,+ ) {+ let group_to_inner = self.group_to_inner.as_slice();+ for (idx, (&lhs_row, &rhs_row)) in+ lhs_rows.iter().zip(rhs_rows.iter()).enumerate()+ {+ if !equal_to_results.get_bit(idx) {+ continue;+ }+ let lhs_slot = group_to_inner[lhs_row];+ let equal = match dict.key(rhs_row) {+ None => self.inner.equal_to(lhs_slot, &self.null_array, 0),+ Some(val_idx) if dict_values.is_null(val_idx) => {+ self.inner.equal_to(lhs_slot, &self.null_array, 0)+ }+ Some(val_idx) => self.inner.equal_to(lhs_slot, dict_values, val_idx),+ };+ if !equal {+ equal_to_results.set_bit(idx, false);+ }+ }+ }+}++impl<K: ArrowDictionaryKeyType + Send + Sync> GroupColumn+ for DictionaryGroupValuesColumn<K>+{+ fn equal_to(&self, lhs_row: usize, array: &ArrayRef, rhs_row: usize) -> bool {+ let lhs_slot = self.group_to_inner[lhs_row];+ let dict = array.as_dictionary::<K>();+ match dict.key(rhs_row) {+ None => self.inner.equal_to(lhs_slot, &self.null_array, 0),+ Some(val_idx) if dict.values().is_null(val_idx) => {+ self.inner.equal_to(lhs_slot, &self.null_array, 0)+ }+ Some(val_idx) => self.inner.equal_to(lhs_slot, dict.values(), val_idx),+ }+ }++ fn append_val(&mut self, array: &ArrayRef, row: usize) -> Result<()> {+ let dict = array.as_dictionary::<K>();+ let inner_slot = match dict.key(row) {+ None => self.find_or_insert_null()?,+ Some(val_idx) if dict.values().is_null(val_idx) => {+ self.find_or_insert_null()?+ }+ Some(val_idx) => {+ let dict_values = dict.values();+ let single = dict_values.slice(val_idx, 1);+ self.hash_values(&single);+ self.find_or_insert_value(dict_values, val_idx, self.val_hashes[0])?+ }+ };+ self.group_to_inner.push(inner_slot);+ self.check_key_overflow()+ }++ fn vectorized_equal_to(+ &self,+ lhs_rows: &[usize],+ array: &ArrayRef,+ rhs_rows: &[usize],+ equal_to_results: &mut BooleanBufferBuilder,+ ) {+ let dict = array.as_dictionary::<K>();+ let dict_keys = dict.keys();+ let dict_values = dict.values();+ let num_distinct = dict_values.len();++ // The fallback is in a separate #[cold] function so its code does not+ // appear inline here and cannot prevent LLVM from pipelining / unrolling+ // the hot lookup-table loops below.+ if rhs_rows.len() < num_distinct {+ self.equal_to_per_row(+ lhs_rows,+ dict_values,+ dict,+ rhs_rows,+ equal_to_results,+ );+ return;+ }++ let mut val_hashes = vec![0u64; dict_values.len()];+ create_hashes(+ std::slice::from_ref(dict_values),+ &self.random_state,+ &mut val_hashes,+ )+ .unwrap();+ let lookup = self.build_lookup_table(dict_values, &val_hashes);++ let group_to_inner = self.group_to_inner.as_slice();++ if dict_keys.null_count() == 0 {+ // No null keys : skip the get_bit guard: we only ever write false,+ // so overwriting an already-false bit is a no-op.+ let raw_keys = dict_keys.values();+ for (idx, (&lhs_row, &rhs_row)) in+ lhs_rows.iter().zip(rhs_rows.iter()).enumerate()+ {+ let rhs_slot = lookup[raw_keys[rhs_row].as_usize()];+ if rhs_slot == usize::MAX || group_to_inner[lhs_row] != rhs_slot {+ equal_to_results.set_bit(idx, false);+ }+ }+ } else {+ let null_buf = dict_keys.nulls().unwrap();+ let raw_keys = dict_keys.values();+ for (idx, (&lhs_row, &rhs_row)) in+ lhs_rows.iter().zip(rhs_rows.iter()).enumerate()+ {+ if equal_to_results.get_bit(idx) {+ let val_idx = if null_buf.is_null(rhs_row) {+ num_distinct+ } else {+ raw_keys[rhs_row].as_usize()+ };+ let rhs_slot = lookup[val_idx];+ if rhs_slot == usize::MAX || group_to_inner[lhs_row] != rhs_slot {+ equal_to_results.set_bit(idx, false);+ }+ }+ }+ }+ }++ fn vectorized_append(&mut self, array: &ArrayRef, rows: &[usize]) -> Result<()> {+ let dict = array.as_dictionary::<K>();+ let dict_keys = dict.keys();+ let dict_values = dict.values();+ let num_distinct = dict_values.len();++ self.hash_values(dict_values);+ self.val_to_inner.clear();+ self.val_to_inner.resize(num_distinct, usize::MAX);++ self.group_to_inner.try_reserve(rows.len()).map_err(|e| {+ DataFusionError::ArrowError(+ Box::new(ArrowError::MemoryError(e.to_string())),+ None,+ )+ })?;++ if dict_keys.null_count() == 0 {+ let raw_keys = dict_keys.values();+ for &row in rows {+ let val_idx = raw_keys[row].as_usize();+ if self.val_to_inner[val_idx] == usize::MAX {+ // A non-null key can still point to a null value in the values array.+ self.val_to_inner[val_idx] = if dict_values.is_null(val_idx) {+ self.find_or_insert_null()?+ } else {+ self.find_or_insert_value(+ dict_values,+ val_idx,+ self.val_hashes[val_idx],+ )?+ };+ }+ self.group_to_inner.push(self.val_to_inner[val_idx]);+ }+ } else {+ let raw_keys = dict_keys.values();+ let null_buf = dict_keys.nulls().unwrap();+ for &row in rows {+ let slot = if null_buf.is_null(row) {+ self.find_or_insert_null()?+ } else {+ let val_idx = raw_keys[row].as_usize();+ if self.val_to_inner[val_idx] == usize::MAX {+ self.val_to_inner[val_idx] = if dict_values.is_null(val_idx) {+ self.find_or_insert_null()?+ } else {+ self.find_or_insert_value(+ dict_values,+ val_idx,+ self.val_hashes[val_idx],+ )?+ };+ }+ self.val_to_inner[val_idx]+ };+ self.group_to_inner.push(slot);+ }+ }++ self.check_key_overflow()+ }++ fn len(&self) -> usize {+ self.group_to_inner.len()+ }++ fn size(&self) -> usize {+ self.inner.size()+ + self.value_dedup_size+ + self.group_to_inner.capacity() * size_of::<usize>()+ + self.val_to_inner.capacity() * size_of::<usize>()+ + self.val_hashes.capacity() * size_of::<u64>()+ + self.null_array.get_array_memory_size()+ + size_of::<Self>()+ }++ fn build(self: Box<Self>) -> ArrayRef {+ let null_inner_slot = self.null_inner_slot;+ let values = self.inner.build();+ Self::into_dict(values, &self.group_to_inner, null_inner_slot)+ }++ fn take_n(&mut self, n: usize) -> ArrayRef {+ let old_inner_len = self.inner.len();+ let all_inner_values = self.inner.take_n(old_inner_len);++ let mut emit_old_to_new = vec![usize::MAX; old_inner_len];+ let mut emit_new_to_old: Vec<usize> = Vec::new();+ for &old in &self.group_to_inner[..n] {+ // Null groups emit a null key (None) and need no slot in the+ // values array, so excluding them keeps key indices tight and+ // prevents overflow at key-type capacity.+ if all_inner_values.is_null(old) {+ continue;+ }+ if emit_old_to_new[old] == usize::MAX {+ emit_old_to_new[old] = emit_new_to_old.len();+ emit_new_to_old.push(old);+ }+ }+ let emit_indices =+ Int64Array::from_iter(emit_new_to_old.iter().map(|&i| i as i64));+ let compact_emit_values =+ take(&*all_inner_values, &emit_indices, None).expect("take emit values");+ let emitted_keys: PrimitiveArray<K> = self.group_to_inner[..n]+ .iter()+ .map(|&old| {+ if all_inner_values.is_null(old) {+ None+ } else {+ Some(K::Native::usize_as(emit_old_to_new[old]))+ }+ })+ .collect();+ let emitted: ArrayRef =+ Arc::new(DictionaryArray::<K>::new(emitted_keys, compact_emit_values));++ // Null deferred to last so null_inner_slot is always the highest index+ // and check_key_overflow can subtract it without a false overflow.+ let remaining = self.group_to_inner[n..].to_vec();+ let mut old_to_new = vec![usize::MAX; old_inner_len];+ let mut new_to_old: Vec<usize> = Vec::new();+ let mut null_old_slot: Option<usize> = None;+ for &old in &remaining {+ if all_inner_values.is_null(old) {+ if null_old_slot.is_none() {+ null_old_slot = Some(old);+ }+ continue;+ }+ if old_to_new[old] == usize::MAX {+ old_to_new[old] = new_to_old.len();+ new_to_old.push(old);+ }+ }+ if let Some(old) = null_old_slot {+ old_to_new[old] = new_to_old.len();+ new_to_old.push(old);+ }++ self.value_dedup = HashTable::new();+ self.value_dedup_size = 0;+ self.null_inner_slot = None;++ self.hash_values(&all_inner_values);++ for (new_slot, &old_slot) in new_to_old.iter().enumerate() {+ if all_inner_values.is_null(old_slot) {+ self.inner+ .append_val(&self.null_array, 0)+ .expect("append null failed in take_n");+ self.null_inner_slot = Some(new_slot);+ } else {+ self.inner+ .append_val(&all_inner_values, old_slot)+ .expect("append value failed in take_n");+ self.value_dedup.insert_accounted(+ (self.val_hashes[old_slot], new_slot),+ |&(entry_hash, _)| entry_hash,+ &mut self.value_dedup_size,+ );+ }+ }++ self.group_to_inner = remaining.iter().map(|&old| old_to_new[old]).collect();+ self.check_key_overflow().expect("key overflow in take_n");++ emitted+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::aggregates::group_values::multi_group_by::bytes::ByteGroupValueBuilder;+ use arrow::array::{+ Array, ArrayRef, BooleanBufferBuilder, DictionaryArray, Int32Array, StringArray,+ UInt8Array,+ };+ use arrow::compute::cast;+ use arrow::datatypes::{DataType, Int8Type, Int32Type, UInt8Type};+ use datafusion_physical_expr::binary_map::OutputType;+ use std::sync::Arc;++ fn utf8_col() -> DictionaryGroupValuesColumn<Int32Type> {+ let f = Field::new("", DataType::Utf8, true);+ DictionaryGroupValuesColumn::new(+ Box::new(ByteGroupValueBuilder::<i32>::new(OutputType::Utf8)),+ &f,+ )+ }++ fn int8_col() -> DictionaryGroupValuesColumn<Int8Type> {+ let f = Field::new("", DataType::Utf8, true);+ DictionaryGroupValuesColumn::new(+ Box::new(ByteGroupValueBuilder::<i32>::new(OutputType::Utf8)),+ &f,+ )+ }++ fn uint8_col() -> DictionaryGroupValuesColumn<UInt8Type> {+ let f = Field::new("", DataType::Utf8, true);+ DictionaryGroupValuesColumn::new(+ Box::new(ByteGroupValueBuilder::<i32>::new(OutputType::Utf8)),+ &f,+ )+ }++ fn i32_dict(keys: &[Option<i32>], values: &[Option<&str>]) -> ArrayRef {+ Arc::new(DictionaryArray::<Int32Type>::new(+ Int32Array::from(keys.to_vec()),+ Arc::new(StringArray::from(values.to_vec())),+ ))+ }++ fn i8_dict(keys: &[Option<i8>], values: &[Option<&str>]) -> ArrayRef {+ use arrow::array::Int8Array;+ Arc::new(DictionaryArray::<Int8Type>::new(+ Int8Array::from(keys.to_vec()),+ Arc::new(StringArray::from(values.to_vec())),+ ))+ }++ fn u8_dict(keys: &[Option<u8>], values: &[Option<&str>]) -> ArrayRef {+ Arc::new(DictionaryArray::<UInt8Type>::new(+ UInt8Array::from(keys.to_vec()),+ Arc::new(StringArray::from(values.to_vec())),+ ))+ }++ fn str_values(arr: &ArrayRef) -> Vec<Option<String>> {+ let plain = cast(arr.as_ref(), &DataType::Utf8).unwrap();+ plain+ .as_any()+ .downcast_ref::<StringArray>()+ .unwrap()+ .iter()+ .map(|v| v.map(|s| s.to_owned()))+ .collect()+ }++ fn bool_vec(buf: &BooleanBufferBuilder) -> Vec<bool> {+ (0..buf.len()).map(|i| buf.get_bit(i)).collect()+ }++ fn all_true(len: usize) -> BooleanBufferBuilder {+ let mut buf = BooleanBufferBuilder::new(len);+ buf.append_n(len, true);+ buf+ }++ // Builds an Int8-keyed dict of `end-start` distinct strings "v{start}".."v{end-1}".+ fn distinct_i8_dict(start: usize, end: usize) -> ArrayRef {+ let strs: Vec<String> = (start..end).map(|i| format!("v{i}")).collect();+ let refs: Vec<Option<&str>> = strs.iter().map(|s| Some(s.as_str())).collect();+ i8_dict(+ &(0..strs.len()).map(|i| Some(i as i8)).collect::<Vec<_>>(),+ &refs,+ )+ }++ // Builds a UInt8-keyed dict of `count` distinct strings "u0".."u{count-1}".+ fn distinct_u8_dict(count: usize) -> ArrayRef {+ let strs: Vec<String> = (0..count).map(|i| format!("u{i}")).collect();+ let refs: Vec<Option<&str>> = strs.iter().map(|s| Some(s.as_str())).collect();+ u8_dict(+ &(0..count).map(|i| Some(i as u8)).collect::<Vec<_>>(),+ &refs,+ )+ }++ #[test]+ fn repeated_values_are_deduplicated_in_inner_store() {+ let mut col = utf8_col();+ let arr = i32_dict(+ &[Some(0), Some(1), Some(0), Some(1), Some(0)],+ &[Some("a"), Some("b")],+ );+ col.vectorized_append(&arr, &[0, 1, 2, 3, 4]).unwrap();+ let out = Box::new(col).build();+ assert_eq!(out.as_dictionary::<Int32Type>().values().len(), 2);+ assert_eq!(+ str_values(&out),+ vec![+ Some("a".into()),+ Some("b".into()),+ Some("a".into()),+ Some("b".into()),+ Some("a".into()),+ ]+ );+ }++ #[test]+ fn null_key_and_null_valued_entry_both_map_to_null_group() {+ let mut col = utf8_col();+ let input = i32_dict(&[None, Some(0), Some(1)], &[None, Some("b")]);+ for row in 0..3 {+ col.append_val(&input, row).unwrap();+ }+ assert!(col.equal_to(0, &input, 1));+ assert!(!col.equal_to(0, &input, 2));+ let out = Box::new(col).build();+ assert_eq!(out.as_dictionary::<Int32Type>().values().len(), 1);+ assert_eq!(str_values(&out), vec![None, None, Some("b".into())]);+ }++ #[test]+ fn take_n_compacts_emitted_values_and_remaps_remaining_slots() {+ let mut col = utf8_col();+ let b1 = i32_dict(+ &[Some(0), Some(1), None, Some(2)],+ &[Some("a"), Some("b"), Some("c")],+ );+ col.vectorized_append(&b1, &[0, 1, 2, 3]).unwrap();++ let emitted = col.take_n(2);+ assert_eq!(emitted.as_dictionary::<Int32Type>().values().len(), 2);+ assert_eq!(+ str_values(&emitted),+ vec![Some("a".into()), Some("b".into())]+ );++ let b2 = i32_dict(&[None, Some(0)], &[Some("z")]);+ col.vectorized_append(&b2, &[0, 1]).unwrap();++ let mut buf = all_true(2);+ col.vectorized_equal_to(&[0, 1], &b2, &[0, 1], &mut buf);+ assert_eq!(bool_vec(&buf), vec![true, false]);++ let out = Box::new(col).build();+ assert_eq!(+ str_values(&out),+ vec![None, Some("c".into()), None, Some("z".into())]+ );+ }++ #[test]+ fn vectorized_equal_to_does_not_use_stale_hashes_from_prior_append() {+ let mut col = utf8_col();+ col.vectorized_append(&i32_dict(&[Some(0)], &[Some("a"), Some("b")]), &[0])+ .unwrap();+ let batch2 = i32_dict(&[Some(1)], &[Some("z"), Some("a")]);+ let mut buf = all_true(1);+ col.vectorized_equal_to(&[0], &batch2, &[0], &mut buf);+ assert_eq!(bool_vec(&buf), vec![true]);+ }++ #[test]+ fn null_does_not_consume_a_key_slot_int8_null_first_mid_and_last() {+ let rows128 = (0..128).collect::<Vec<_>>();++ let mut col = int8_col(); // null-last: 128 non-null + null — ok+ col.vectorized_append(&distinct_i8_dict(0, 128), &rows128)+ .unwrap();+ col.append_val(&i8_dict(&[None], &[Some("x")]), 0).unwrap();++ let mut col = int8_col(); // null-first: null + 128 non-null — ok; 129th — error+ col.append_val(&i8_dict(&[None], &[Some("x")]), 0).unwrap();+ col.vectorized_append(&distinct_i8_dict(0, 128), &rows128)+ .unwrap();+ assert!(+ col.append_val(&i8_dict(&[Some(0)], &[Some("overflow")]), 0)+ .is_err()+ );++ let mut col = int8_col(); // null-mid: 100 + null + 28 = 128 total — ok; 129th — error+ col.vectorized_append(&distinct_i8_dict(0, 100), &(0..100).collect::<Vec<_>>())+ .unwrap();+ col.append_val(&i8_dict(&[None], &[Some("x")]), 0).unwrap();+ col.vectorized_append(&distinct_i8_dict(100, 128), &(0..28).collect::<Vec<_>>())+ .unwrap();+ assert!(+ col.append_val(&i8_dict(&[Some(0)], &[Some("v128")]), 0)+ .is_err()+ );++ let mut col = int8_col(); // build() null-first: 128 values (null excluded), null → None+ col.append_val(&i8_dict(&[None], &[Some("x")]), 0).unwrap();+ col.vectorized_append(&distinct_i8_dict(0, 128), &rows128)+ .unwrap();+ let out = Box::new(col).build();+ assert_eq!(out.as_dictionary::<Int8Type>().values().len(), 128);+ assert_eq!(str_values(&out)[0], None);+ assert_eq!(str_values(&out)[1], Some("v0".into()));+ }++ #[test]+ fn null_does_not_consume_a_key_slot_uint8_null_first_and_last() {+ let rows256 = (0..256).collect::<Vec<_>>();++ let mut col = uint8_col(); // null-first: null + 256 non-null — ok; 257th — error+ col.append_val(&u8_dict(&[None], &[Some("x")]), 0).unwrap();+ col.vectorized_append(&distinct_u8_dict(256), &rows256)+ .unwrap();+ assert!(+ col.append_val(&u8_dict(&[Some(0)], &[Some("overflow")]), 0)+ .is_err()+ );++ let mut col = uint8_col(); // build() null-first: 256 values (null excluded), last correct+ col.append_val(&u8_dict(&[None], &[Some("x")]), 0).unwrap();+ col.vectorized_append(&distinct_u8_dict(256), &rows256)+ .unwrap();+ let out = Box::new(col).build();+ assert_eq!(out.as_dictionary::<UInt8Type>().values().len(), 256);+ assert_eq!(str_values(&out)[0], None);+ assert_eq!(str_values(&out)[256], Some("u255".into()));+ }++ #[test]+ fn take_n_null_does_not_steal_key_slot_at_capacity() {+ let rows128 = (0..128).collect::<Vec<_>>();++ // Int8 null-first + 128 non-null; emit all 129 — no panic, null → None+ let mut col = int8_col();+ col.append_val(&i8_dict(&[None], &[Some("x")]), 0).unwrap();+ col.vectorized_append(&distinct_i8_dict(0, 128), &rows128)+ .unwrap();+ let emitted = col.take_n(129);+ assert!(emitted.as_dictionary::<Int8Type>().key(0).is_none());+ assert_eq!(str_values(&emitted)[1], Some("v0".into()));+ assert_eq!(str_values(&emitted)[128], Some("v127".into()));++ // UInt8 null-first + 256 non-null; emit all 257 — last must be "u255" not "u0" (wrap guard)+ let mut col = uint8_col();+ col.append_val(&u8_dict(&[None], &[Some("x")]), 0).unwrap();+ col.vectorized_append(&distinct_u8_dict(256), &(0..256).collect::<Vec<_>>())+ .unwrap();+ let emitted = col.take_n(257);+ assert!(emitted.as_dictionary::<UInt8Type>().key(0).is_none());+ assert_eq!(str_values(&emitted)[1], Some("u0".into()));+ assert_eq!(str_values(&emitted)[256], Some("u255".into()));+ }++ #[test]+ fn take_n_repeated_emissions_null_at_int8_capacity() {+ let rows128 = (0..128).collect::<Vec<_>>();+ let mut col = int8_col();+ col.vectorized_append(&distinct_i8_dict(0, 128), &rows128)+ .unwrap();+ col.append_val(&i8_dict(&[None], &[Some("x")]), 0).unwrap();+ col.vectorized_append(&distinct_i8_dict(0, 128), &rows128)+ .unwrap();++ let first_half = col.take_n(64);+ assert_eq!(str_values(&first_half)[0], Some("v0".into()));+ assert_eq!(str_values(&first_half)[63], Some("v63".into()));+ assert_eq!(first_half.as_dictionary::<Int8Type>().values().len(), 64);++ let second_half = col.take_n(64);+ assert_eq!(str_values(&second_half)[0], Some("v64".into()));+ assert_eq!(str_values(&second_half)[63], Some("v127".into()));++ let null_group = col.take_n(1);+ assert!(null_group.as_dictionary::<Int8Type>().key(0).is_none());++ let out = Box::new(col).build();+ assert_eq!(str_values(&out)[0], Some("v0".into()));+ assert_eq!(str_values(&out)[127], Some("v127".into()));+ assert_eq!(out.as_dictionary::<Int8Type>().values().len(), 128);+ }+}diff --git a/datafusion/physical-plan/src/aggregates/group_values/multi_group_by/mod.rs b/datafusion/physical-plan/src/aggregates/group_values/multi_group_by/mod.rsindex 5b474f3bae..409e159216 100644--- a/datafusion/physical-plan/src/aggregates/group_values/multi_group_by/mod.rs+++ b/datafusion/physical-plan/src/aggregates/group_values/multi_group_by/mod.rs@@ -20,6 +20,7 @@mod boolean;mod bytes;pub mod bytes_view;+mod dictionary;mod fixed_size_binary;pub mod primitive;pub mod row_backed;@@ -34,7 +35,6 @@ use crate::aggregates::group_values::multi_group_by::{primitive::PrimitiveGroupValueBuilder, row_backed::RowsGroupColumn,};use arrow::array::{Array, ArrayRef, BooleanBufferBuilder};-use arrow::compute::cast;use arrow::datatypes::{BinaryViewType, DataType, Date32Type, Date64Type, Decimal128Type, Decimal256Type,DurationMicrosecondType, DurationMillisecondType, DurationNanosecondType,@@ -48,7 +48,7 @@ use arrow::datatypes::{};use datafusion_common::hash_utils::RandomState;use datafusion_common::hash_utils::create_hashes;-use datafusion_common::{Result, internal_datafusion_err, not_impl_err};+use datafusion_common::{Result, not_impl_err};use datafusion_execution::memory_pool::proxy::{HashTableAllocExt, VecAllocExt};use datafusion_expr::EmitTo;use datafusion_physical_expr::binary_map::OutputType;@@ -980,7 +980,7 @@ fn group_column_supported_type(data_type: &DataType) -> bool {| DataType::Utf8View| DataType::BinaryView| DataType::Boolean- )+ ) || matches!(data_type, DataType::Dictionary(_,v ) if group_column_supported_type(v))}/// Build a [`GroupColumn`] for a single schema field.@@ -1130,6 +1130,33 @@ fn make_group_column(field: &Field) -> Result<Box<dyn GroupColumn>> {v.push(Box::new(BooleanGroupValueBuilder::<false>::new()));}}+ DataType::Dictionary(ref key_dt, ref value_dt) => {+ let new_field = Field::new("", *value_dt.clone(), true);+ let inner = make_group_column(&new_field)?;+ macro_rules! dict_col {+ ($T:ty) => {+ Box::new(dictionary::DictionaryGroupValuesColumn::<$T>::new(+ inner, &new_field,+ ))+ };+ }+ let col: Box<dyn GroupColumn> = match key_dt.as_ref() {+ DataType::Int8 => dict_col!(Int8Type),+ DataType::Int16 => dict_col!(Int16Type),+ DataType::Int32 => dict_col!(Int32Type),+ DataType::Int64 => dict_col!(Int64Type),+ DataType::UInt8 => dict_col!(UInt8Type),+ DataType::UInt16 => dict_col!(UInt16Type),+ DataType::UInt32 => dict_col!(UInt32Type),+ DataType::UInt64 => dict_col!(UInt64Type),+ _ => {+ return not_impl_err!(+ "Dictionary key type {key_dt} not supported in GroupValuesColumn"+ );+ }+ };+ v.push(col)+ }// Generic fallback for nested types (Struct / List / LargeList /// FixedSizeList, recursively) that lack a type-specialized builder but// can be encoded by arrow's row format. This is what lets a mixed@@ -1178,7 +1205,7 @@ impl<const STREAMING: bool> GroupValues for GroupValuesColumn<STREAMING> {}fn emit(&mut self, emit_to: EmitTo) -> Result<Vec<ArrayRef>> {- let mut output = match emit_to {+ let output = match emit_to {EmitTo::All => {// Replace the column builders with a fresh set so the// aggregator is immediately reusable after the drain.@@ -1268,20 +1295,6 @@ impl<const STREAMING: bool> GroupValues for GroupValuesColumn<STREAMING> {}};- // TODO: Materialize dictionaries in group keys (#7647)- for (field, array) in self.schema.fields.iter().zip(&mut output) {- let expected = field.data_type();- if let DataType::Dictionary(_, v) = expected {- let actual = array.data_type();- if v.as_ref() != actual {- return Err(internal_datafusion_err!(- "Converted group rows expected dictionary of {v} got {actual}"- ));- }- *array = cast(array.as_ref(), expected)?;- }- }-Ok(output)}@@ -1645,6 +1658,20 @@ mod tests {DataType::Interval(arrow::datatypes::IntervalUnit::YearMonth),DataType::Interval(arrow::datatypes::IntervalUnit::DayTime),DataType::Interval(arrow::datatypes::IntervalUnit::MonthDayNano),+ DataType::Dictionary(Box::new(DataType::Int32), Box::new(DataType::Utf8)),+ DataType::Dictionary(Box::new(DataType::Int8), Box::new(DataType::Int64)),+ DataType::Dictionary(+ Box::new(DataType::UInt16),+ Box::new(DataType::LargeUtf8),+ ),+ DataType::Dictionary(+ Box::new(DataType::Int32),+ Box::new(DataType::Timestamp(+ arrow::datatypes::TimeUnit::Nanosecond,+ None,+ )),+ ),+ DataType::Dictionary(Box::new(DataType::Int32), Box::new(DataType::Float16)),];for dt in &supported_cases {@@ -1905,6 +1932,56 @@ mod tests {}}+ // https://github.com/apache/datafusion/issues/23127+ // validate DictionaryGroupColumn deduplicates values — only k distinct keys appear+ // in the values array even when there are more than 128 groups total.+ #[test]+ fn multi_col_groupby_dict_many_groups_two_values() {+ use arrow::array::{AsArray, DictionaryArray, Int8Array};+ use arrow::datatypes::Int8Type;++ let n_groups = 129_usize;+ let dict_vocab: ArrayRef = Arc::new(StringArray::from(vec!["cat", "dog"]));++ // Each row has a unique label (forcing a new group) and alternates+ // between the two dictionary values. Int8 keys are used; only 2+ // distinct values exist so the key type never overflows.+ let labels: ArrayRef = Arc::new(StringArray::from(+ (0..n_groups).map(|i| format!("g{i}")).collect::<Vec<_>>(),+ ));+ let dict_keys = Int8Array::from(+ (0..n_groups)+ .map(|i| Some((i % 2) as i8))+ .collect::<Vec<_>>(),+ );+ let categories: ArrayRef = Arc::new(DictionaryArray::<Int8Type>::new(+ dict_keys,+ Arc::clone(&dict_vocab),+ ));++ let schema = Arc::new(Schema::new(vec![+ Field::new("label", DataType::Utf8, false),+ Field::new(+ "category",+ DataType::Dictionary(Box::new(DataType::Int8), Box::new(DataType::Utf8)),+ false,+ ),+ ]));++ let mut gv = GroupValuesColumn::<false>::try_new(Arc::clone(&schema)).unwrap();+ gv.intern(&[labels, categories], &mut vec![]).unwrap();+ let out = gv.emit(EmitTo::All).unwrap();++ assert_eq!(out[0].len(), n_groups);+ assert!(matches!(+ out[1].data_type(),+ DataType::Dictionary(k, v)+ if k.as_ref() == &DataType::Int8 && v.as_ref() == &DataType::Utf8+ ));+ // Both vectorized and streaming paths now deduplicate dict values.+ assert_eq!(out[1].as_dictionary::<Int8Type>().values().len(), 2);+ }+#[test]fn test_intern_for_vectorized_group_values() {let data_set = VectorizedTestDataSet::new();