Crate jsonb

jsonb is a binary format JSON representation inspired by PostgreSQL and CockroachDB. It provides a fast, lightweight and easy-to-use API for working with JSON data.

Features

• Good compatibility: jsonb fully supports the JSON standard and can be used to store complex data structures.
• Fast performance: jsonb is designed for high performance, allowing you to work with large JSON data sets with ease.
• Easy to use: jsonb provides a number of built-in functions to support various operations, and also supports the JSONPath syntax for selecting and extracting subset elements.
• Safe and secure: jsonb is written in Rust, which provides memory and thread safety guarantees, making it a safe choice for handling sensitive data.

Encoding format

The jsonb encoding format is a tree-like structure. Each node contains a container header, a number of JEntry headers, and nested encoding values.

• 32-bit container header. 3 bits identify the type of value, including scalar, object and array, and 29 bits identify the number of JEntries in the array or object. The root node of the jsonb value is always a container header.
  • scalar container header: 0x20000000
  • object container header: 0x40000000
  • array container header: 0x80000000
• 32-bit JEntry header. 1 bit identifies whether the JEntry stores a length or an offset, 3 bits identify the type of value, including null, string, number, false, true and container, and the remaining 28 bits identify the length or offset of the encoding value.
  • null JEntry header: 0x00000000
  • string JEntry header: 0x10000000
  • number JEntry header: 0x20000000
  • false JEntry header: 0x30000000
  • true JEntry header: 0x40000000
  • container JEntry header 0x50000000
• Encoding value. Different types of JEntry header have different encoding values.
  • null, true, false: no encoding value, identified by the JEntry header.
  • string: a normal UTF-8 string.
  • number: an encoded number to represent uint64s, int64s and float64s.
  • container: a nested json value with a recursive structure.

An encoding example

// JSON value
[false, 10, {"k":"v"}]

// JSONB encoding
0x80000003    array container header (3 JEntries)
0x30000000    false JEntry header (no encoding value)
0x20000002    number JEntry header (encoding value length 2)
0x5000000e    container JEntry header (encoding value length 14)
0x500a        number encoding value (10)
0x40000001    object container header (1 JEntry)
0x10000001    string key JEntry header (encoding value length 1)
0x10000001    string value JEntry header (encoding value length 1)
0x6b          string encoding value ("k")
0x76          string encoding value ("v")

Modules

• jsonpath

Enums

• Error
• Number
• Value

Functions

• array_length
  Get the length of JSONB array.
• array_values
  Convert the values of a JSONB array to vector.
• as_bool
  If the JSONB is a Boolean, returns the associated bool. Returns None otherwise.
• as_f64
  If the JSONB is a Number, represent it as f64 if possible. Returns None otherwise.
• as_i64
  If the JSONB is a Number, represent it as i64 if possible. Returns None otherwise.
• as_null
  If the JSONB is a Null, returns (). Returns None otherwise.
• as_number
  If the JSONB is a Number, returns the Number. Returns None otherwise.
• as_str
  If the JSONB is a String, returns the String. Returns None otherwise.
• as_u64
  If the JSONB is a Number, represent it as u64 if possible. Returns None otherwise.
• build_array
  Build JSONB array from items. Assuming that the input values is valid JSONB data.
• build_object
  Build JSONB object from items. Assuming that the input values is valid JSONB data.
• compare
  JSONB values supports partial decode for comparison, if the values are found to be unequal, the result will be returned immediately. In first level header, values compare as the following order: Scalar Null > Array > Object > Other Scalars(String > Number > Boolean).
• convert_to_comparable
  Convert JSONB value to comparable vector. The compare rules are the same as the compare function. Scalar Null > Array > Object > Other Scalars(String > Number > Boolean).
• from_slice
  The binary JSONB contains three parts, Header, JEntry and RawData. This structure can be nested. Each group of structures starts with a Header. The upper-level Value will store the Header length or offset of the lower-level Value. Header stores the type of the Value, include Array, Object and Scalar, Scalar has only one Value, and a corresponding JEntry. Array and Object are nested type, they have multiple lower-level Values. So the Header also stores the number of lower-level Values. JEntry stores the types of Scalar Value, including Null, True, False, Number, String and Container. They have three different decode methods.
• get_by_index
  Get the inner element of JSONB Array by index.
• get_by_name
  Get the inner element of JSONB Object by key name, if ignore_case is true, enables case-insensitive matching.
• get_by_path
  Get the inner elements of JSONB value by JSON path. The return value may contains multiple matching elements.
• get_by_path_array
  Get the inner elements of JSONB value by JSON path. If there are multiple matching elements, return an JSONB Array.
• get_by_path_first
  Get the inner element of JSONB value by JSON path. If there are multiple matching elements, only the first one is returned
• is_array
  Returns true if the JSONB is An Array. Returns false otherwise.
• is_boolean
  Returns true if the JSONB is a Boolean. Returns false otherwise.
• is_f64
  Returns true if the JSONB is a f64 Number. Returns false otherwise.
• is_i64
  Returns true if the JSONB is a i64 Number. Returns false otherwise.
• is_null
  Returns true if the JSONB is a Null.
• is_number
  Returns true if the JSONB is a Number. Returns false otherwise.
• is_object
  Returns true if the JSONB is An Object. Returns false otherwise.
• is_string
  Returns true if the JSONB is a String. Returns false otherwise.
• is_u64
  Returns true if the JSONB is a u64 Number. Returns false otherwise.
• object_each
  Convert the values of a JSONB object to vector of key-value pairs.
• object_keys
  Get the keys of a JSONB object.
• parse_value
• path_exists
  Checks whether the JSON path returns any item for the JSONB value.
• rand_value
  generate random JSONB value
• strip_nulls
  Deletes all object fields that have null values from the given JSON value, recursively. Null values that are not object fields are untouched.
• to_bool
  Cast JSONB value to Boolean
• to_f64
  Cast JSONB value to f64
• to_i64
  Cast JSONB value to i64
• to_pretty_string
  Convert JSONB value to pretty String
• to_str
  Cast JSONB value to String
• to_string
  Convert JSONB value to String
• to_u64
  Cast JSONB value to u64
• traverse_check_string
  Traverse all the string fields in a jsonb value and check whether the conditions are met.
• type_of
  Returns the type of the top-level JSON value as a text string. Possible types are object, array, string, number, boolean, and null.

Type Aliases

• Object