This is an automated email from the ASF dual-hosted git repository.
Jefffrey pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new 002cc1c078 doc: Describe potential footgun in `MapArray::keys` and
`values` (#11145)
002cc1c078 is described below
commit 002cc1c078342cd4b7f2d4dfd59870e3bef7fb51
Author: Neil Conway <[email protected]>
AuthorDate: Tue Sep 22 21:49:04 2026 -0400
doc: Describe potential footgun in `MapArray::keys` and `values` (#11145)
# Which issue does this PR close?
- N/A
# Rationale for this change
The behavior of the `keys` and `values` methods of a `MapArray` can be a
bit surprising. This PR documents that behavior; consistent with the
documentation for `ListArray::values`, which behaves similarly.
# What changes are included in this PR?
* Doc additions only
# Are these changes tested?
Existing tests pass.
# Are there any user-facing changes?
No.
---
arrow-array/src/array/map_array.rs | 44 ++++++++++++++++++++++++++++++++++++--
1 file changed, 42 insertions(+), 2 deletions(-)
diff --git a/arrow-array/src/array/map_array.rs
b/arrow-array/src/array/map_array.rs
index 919619aed3..938b248977 100644
--- a/arrow-array/src/array/map_array.rs
+++ b/arrow-array/src/array/map_array.rs
@@ -32,6 +32,26 @@ use std::sync::Arc;
/// [`MapArray`] is physically a [`ListArray`] of key values pairs stored as
an `entries`
/// [`StructArray`] with 2 child fields.
///
+/// # Slicing
+///
+/// Slicing a `MapArray` via [`Self::slice`] creates a new `MapArray` without
+/// copying any data. The sliced array shares the same `entries` child array
and
+/// only narrows its offsets and validity, which means:
+///
+/// 1. [`Self::entries`], [`Self::keys`] and [`Self::values`] are unchanged and
+/// may contain entries both before and after the slice.
+/// 2. [`Self::offsets`] do not necessarily start at `0`, nor cover all
entries.
+///
+/// For example, given a `MapArray` holding the three maps `{a: 1, b: 2}`,
+/// `{c: 3}` and `{d: 4, e: 5}`, the `entries` array holds five key-value pairs
+/// and the offsets are `[0, 2, 3, 5]`. Calling `slice(1, 1)` yields a
`MapArray`
+/// holding the single map `{c: 3}`, but [`Self::keys`] still returns all five
+/// keys `a, b, c, d, e` and [`Self::offsets`] is `[2, 3]`. Use the offsets, or
+/// [`Self::value`], to find the entries belonging to each map.
+///
+/// The same applies to any `MapArray` constructed with offsets that do not
start
+/// at `0` or do not extend to the end of `entries`.
+///
/// # See also
/// * [`MapBuilder`](crate::builder::MapBuilder) for how to construct a
[`MapArray`]
/// * [`Self::from_vec_of_maps`] for ergonomically creating maps for testing
@@ -210,22 +230,40 @@ impl MapArray {
///
/// Unlike [`Self::value_offsets`] this returns the [`OffsetBuffer`]
/// allowing for zero-copy cloning
+ ///
+ /// Note: The offsets may not start at `0` and may not cover all entries in
+ /// [`Self::entries`]. This can happen when the map array was sliced via
+ /// [`Self::slice`]. See documentation for [`Self`] for more details.
#[inline]
pub fn offsets(&self) -> &OffsetBuffer<i32> {
&self.value_offsets
}
- /// Returns a reference to the keys of this map
+ /// Returns a reference to all keys in the entries backing this map
+ ///
+ /// Note: The map array may not refer to all keys in the returned array,
for
+ /// example after slicing via [`Self::slice`]. Use [`Self::offsets`] to
find
+ /// the keys for each map; those offsets index into the returned array and
+ /// may not start at `0`. See documentation for [`Self`] for more details.
pub fn keys(&self) -> &ArrayRef {
self.entries.column(0)
}
- /// Returns a reference to the values of this map
+ /// Returns a reference to all values in the entries backing this map
+ ///
+ /// Note: The map array may not refer to all values in the returned array,
for
+ /// example after slicing via [`Self::slice`]. Use [`Self::offsets`] to
find
+ /// the values for each map; those offsets index into the returned array
and
+ /// may not start at `0`. See documentation for [`Self`] for more details.
pub fn values(&self) -> &ArrayRef {
self.entries.column(1)
}
/// Returns a reference to the [`StructArray`] entries of this map
+ ///
+ /// Note: The map array may not refer to all entries in the returned array,
+ /// for example after slicing via [`Self::slice`]. See documentation for
+ /// [`Self`] for more details.
pub fn entries(&self) -> &StructArray {
&self.entries
}
@@ -278,6 +316,8 @@ impl MapArray {
}
/// Returns the offset values in the offsets buffer
+ ///
+ /// See [`Self::offsets`] for more details.
#[inline]
pub fn value_offsets(&self) -> &[i32] {
&self.value_offsets
