This is an automated email from the ASF dual-hosted git repository. fresh-borzoni pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fluss-rust.git
commit b090e50e2b2b93e828f0274acba912193231ab13 Author: Jared Yu <[email protected]> AuthorDate: Mon May 18 20:02:55 2026 -0700 docs: add documentation for MAP dtype (#556) --- website/docs/user-guide/rust/api-reference.md | 14 ++++++++++++++ website/docs/user-guide/rust/data-types.md | 23 +++++++++++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/website/docs/user-guide/rust/api-reference.md b/website/docs/user-guide/rust/api-reference.md index 5d3068b5..7ef34ef3 100644 --- a/website/docs/user-guide/rust/api-reference.md +++ b/website/docs/user-guide/rust/api-reference.md @@ -466,6 +466,7 @@ Implements the `InternalRow` trait (see below). | `fn get_binary(&self, idx: usize, length: usize) -> Result<&[u8]>` | Get fixed-length binary value | | `fn get_char(&self, idx: usize, length: usize) -> Result<&str>` | Get fixed-length char value | | `fn get_array(&self, idx: usize) -> Result<FlussArray>` | Get array value | +| `fn get_map(&self, idx: usize, key_type: &DataType, value_type: &DataType) -> Result<FlussMap>` | Get map value | ## `FlussArray` @@ -479,6 +480,19 @@ Implements the `InternalRow` trait (see below). Element getters mirror `InternalRow` typed getters and return `Result<T>`. For example, use `get_int()`, `get_long()`, and `get_double()` for primitive elements, and `get_string()`, `get_binary()`, `get_decimal()`, `get_timestamp_ntz()`, `get_timestamp_ltz()`, and `get_array()` for variable-length or nested elements. +## `FlussMap` + +`FlussMap` is the Rust row representation for `MAP` values. You usually obtain it from `InternalRow::get_map()`. + +| Method | Description | +|--------|-------------| +| `fn size(&self) -> usize` | Number of entries in the map | +| `fn as_bytes(&self) -> &[u8]` | Get encoded bytes of the map | +| `fn key_array(&self) -> &FlussArray` | Get the key array | +| `fn value_array(&self) -> &FlussArray` | Get the value array | + +Key and value arrays are returned as `&FlussArray`, allowing you to read entries by retrieving keys and values at the same index positions. + ## `ChangeType` | Value | Short String | Description | diff --git a/website/docs/user-guide/rust/data-types.md b/website/docs/user-guide/rust/data-types.md index 63b7fa62..ad14028b 100644 --- a/website/docs/user-guide/rust/data-types.md +++ b/website/docs/user-guide/rust/data-types.md @@ -22,6 +22,7 @@ sidebar_position: 3 | `BYTES` | `&[u8]` | `get_bytes()` | `set_field(idx, &[u8])` | | `BINARY(n)` | `&[u8]` | `get_binary(idx, length)` | `set_field(idx, &[u8])` | | `ARRAY<T>` | `FlussArray` | `get_array()` | `set_field(idx, FlussArray)` | +| `MAP<K, V>` | `FlussMap` | `get_map(idx, key_type, value_type)` | `set_field(idx, FlussMap)` | ## Constructing Special Types @@ -83,6 +84,28 @@ row.set_field(0, Datum::Array(arr)); `ARRAY` is supported for row values and nested row fields. For key encoding, Rust follows Java parity: `ARRAY` can be encoded by the compacted key encoder, while table-level key constraints are validated by the server (which may reject unsupported key types). +## Maps + +Use `DataTypes::map(key_type, value_type)` in schema definitions. At runtime, read maps with `row.get_map(idx, &key_type, &value_type)?`. + +To construct map values for writes, build a `FlussMap` using `FlussMapWriter` and wrap it with `Datum::Map`: + +```rust +use fluss::metadata::DataTypes; +use fluss::row::binary_map::FlussMapWriter; +use fluss::row::{Datum, GenericRow}; + +let mut writer = FlussMapWriter::new(2, &DataTypes::string(), &DataTypes::int()); +writer.write_entry("key1".into(), 100.into())?; +writer.write_entry("key2".into(), Datum::Null)?; +let map = writer.complete()?; + +let mut row = GenericRow::new(1); +row.set_field(0, Datum::Map(map)); +``` + +`MAP` keys cannot be null. `MAP` is supported for row values and nested row fields. Like arrays, `MAP` follows Java parity for key encoding and can be encoded by the compacted key encoder, while table-level key constraints are validated by the server. + ## Reading Row Data ```rust
