Struct MapArray

pub struct MapArray {
    pub(super) inner: ListArray,
}

MapArray is physically just a List<Struct<key: K, value: V>> array, but with some additional restrictions.

Type:

• key’s datatype can only be string & integral types. (See MapType::check_key_type_valid.)
• value can be any type.

Value (for each map value in the array):

• keys are non-null and unique.

• keys and values must be of the same length. For a MapArray, it’s sliced by the ListArray’s offsets, so it essentially means the key and value children arrays have the same length.

• The lists are NOT sorted by key.

• Eq / Hash / Ord for map:

  It’s controversial due to the physicial representation is just an unordered list. In many systems (e.g., DuckDB and ClickHouse), {"k1":"v1","k2":"v2"} != {"k2":"v2","k1":"v1"}. But the reverse definition might be more intuitive, especially when ingesting Avro/Protobuf data.

  To avoid controversy, we wanted to ban all usages and make the implementation unreachable!(), but it’s hard since these implementations can be used in different places:

  • Explicit in User-facing functions (e.g., comparison operators). These could be avoided completely.
  • Implicit in Keys (group by / order by / primary key). These could also be banned, but it’s harder.
  • Some internal usages. One example is _row_id. See https://github.com/risingwavelabs/risingwave/issues/7981#issuecomment-2257661749. It might be solvable, but we are not sure whether it’s depended somewhere else.

  Considering these, it might be better to still choose a well-defined behavior instead of using unreachable. We should try to have a consistent definition for these operations to minimize possible surprises. And we could still try our best to ban it to prevent misuse.

  Currently we choose the second behavior. i.e., first sort the map by key, then compare/hash. Note that Eq is intuitive, but Ord still looks strange. We assume no users really care about which map is larger, but just provide a implementation to prevent undefined behavior.

  See more discussion in https://github.com/risingwavelabs/risingwave/issues/7981.

Note that decisions above are not definitive. Just be conservative at the beginning.

Fields

inner: ListArray

Implementations

impl MapArray

pub fn from_protobuf(array: &PbArray) -> ArrayResult<ArrayImpl>

pub fn as_struct(&self) -> &StructArray

Return the inner struct array of the list array.

pub fn offsets(&self) -> &[u32]

Returns the offsets of this map.

Trait Implementations

impl Array for MapArray

type Builder = MapArrayBuilder

Corresponding builder of this array, which is reciprocal to Array.

type OwnedItem = MapValue

Owned type of item in array, which is reciprocal to Self::RefItem.

type RefItem<'a> = MapRef<'a>

A reference to item in array, as well as return type of value_at, which is reciprocal to Self::OwnedItem.

unsafe fn raw_value_at_unchecked(&self, idx: usize) -> Self::RefItem<'_>

Retrieve a reference to value regardless of whether it is null without checking the index boundary.

fn len(&self) -> usize

Number of items of array.

fn to_protobuf(&self) -> PbArray

Serialize to protobuf

fn null_bitmap(&self) -> &Bitmap

Get the null Bitmap from Array.

fn into_null_bitmap(self) -> Bitmap

Get the owned null Bitmap from Array.

fn set_bitmap(&mut self, bitmap: Bitmap)

fn data_type(&self) -> DataType

fn value_at(&self, idx: usize) -> Option<Self::RefItem<'_>>

Retrieve a reference to value.

unsafe fn value_at_unchecked(&self, idx: usize) -> Option<Self::RefItem<'_>>

Safety

fn iter(&self) -> ArrayIterator<'_, Self>

Get iterator of current array.

fn raw_iter(&self) -> impl ExactSizeIterator<Item = Self::RefItem<'_>>

Get raw iterator of current array.

fn is_null(&self, idx: usize) -> bool

Check if an element is null or not.

unsafe fn is_null_unchecked(&self, idx: usize) -> bool

Safety

fn hash_at<H: Hasher>(&self, idx: usize, state: &mut H)

Feed the value at idx into the given Hasher.

fn hash_vec<H: Hasher>(&self, hashers: &mut [H], vis: &Bitmap)

fn is_empty(&self) -> bool

fn create_builder(&self, capacity: usize) -> Self::Builder

fn into_ref(self) -> ArrayRef

Converts the array into an ArrayRef.

impl Clone for MapArray

fn clone(&self) -> MapArray

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MapArray

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl EstimateSize for MapArray

fn estimated_heap_size(&self) -> usize

The estimated heap size of the current struct in bytes.

fn estimated_size(&self) -> usize

where Self: Sized,

The estimated total size of the current struct in bytes, including the estimated_heap_size and the size of Self.

impl<'a> From<&'a ArrayImpl> for &'a MapArray

fn from(array: &'a ArrayImpl) -> Self

Converts to this type from the input type.

impl From<ArrayImpl> for MapArray

fn from(array: ArrayImpl) -> Self

Converts to this type from the input type.

impl From<MapArray> for ArrayImpl

fn from(arr: MapArray) -> Self

Converts to this type from the input type.

impl PartialEq for MapArray

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for MapArray