Module mz_repr::adt::jsonb

source ·
Expand description

JSON representation.

This module provides a serde_json-like API that is backed by the native Materialize data format, i.e., Row and Datum. It supports efficiently parsing and serializing JSON strings and byte slices with minimal allocations. It also provides seamless interop with APIs that require serde_json::Value, though at a small performance cost.

There are two core types in the module:

  • Jsonb represents owned JSON data. This type houses the deserialization functions.

  • JsonbRef is a borrowed view of JSON data. This type houses the serialization functions.

The name “jsonb” is based on the PostgreSQL data type of the same name. Various sources claim this stands for “JSON better”, as compared to the less-efficient json data type in PostgreSQL.

§Constructing JSON objects

To parse JSON from a string, use the FromStr implementation. Once parsed, the underlying Row can be extracted with Jsonb::into_row.

let jsonb: Jsonb = r#"{"a": 1, "b": 2}"#.parse()?;
let row = jsonb.into_row();

If the source JSON is in bytes, use Jsonb::from_slice instead:

let jsonb = Jsonb::from_slice(br#"{"a": 1, "b": 2}"#);

§Serializing JSON objects

To write a JSON object to a string, use the fmt::Display implementation. The alternate format produces pretty output.

format!("compressed: {}", jsonb);
format!("pretty: {:#}", jsonb);

§Direct JSON deserialization

You can skip Jsonb entirely and deserialize JSON directly into an existing Row with JsonbPacker. This saves an allocation and a copy.

let mut row = Row::default();
let mut packer = row.packer();
JsonbPacker::new(&mut packer).pack_str("[1, 2]")?;