Crate jsonb

source ·
Expand description

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§

Enums§

Functions§

  • Get the length of JSONB array.
  • Convert the values of a JSONB array to vector.
  • If the JSONB is a Boolean, returns the associated bool. Returns None otherwise.
  • If the JSONB is a Number, represent it as f64 if possible. Returns None otherwise.
  • If the JSONB is a Number, represent it as i64 if possible. Returns None otherwise.
  • If the JSONB is a Null, returns (). Returns None otherwise.
  • If the JSONB is a Number, returns the Number. Returns None otherwise.
  • If the JSONB is a String, returns the String. Returns None otherwise.
  • If the JSONB is a Number, represent it as u64 if possible. Returns None otherwise.
  • Build JSONB array from items. Assuming that the input values is valid JSONB data.
  • Build JSONB object from items. Assuming that the input values is valid JSONB data.
  • 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).
  • Concatenates two jsonb values. Concatenating two arrays generates an array containing all the elements of each input. Concatenating two objects generates an object containing the union of their keys, taking the second object’s value when there are duplicate keys. All other cases are treated by converting a non-array input into a single-element array, and then proceeding as for two arrays.
  • Checks whether the right value contains in the left value.
  • 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).
  • Deletes the array element with specified index (negative integers count from the end).
  • Deletes a value from a JSON object by the specified path, where path elements can be either field keys or array indexes.
  • Deletes a key (and its value) from a JSON object, or matching string value(s) from a JSON array.
  • Checks whether all of the strings exist as top-level keys or array elements.
  • Checks whether any of the strings exist as top-level keys or array elements.
  • 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 the inner element of JSONB Array by index.
  • Extracts JSON sub-object at the specified path, where path elements can be either field keys or array indexes.
  • Get the inner element of JSONB Object by key name, if ignore_case is true, enables case-insensitive matching.
  • Get the inner elements of JSONB value by JSON path. The return value may contains multiple matching elements.
  • Get the inner elements of JSONB value by JSON path. If there are multiple matching elements, return an JSONB Array.
  • Get the inner element of JSONB value by JSON path. If there are multiple matching elements, only the first one is returned
  • Returns true if the JSONB is An Array. Returns false otherwise.
  • Returns true if the JSONB is a Boolean. Returns false otherwise.
  • Returns true if the JSONB is a f64 Number. Returns false otherwise.
  • Returns true if the JSONB is a i64 Number. Returns false otherwise.
  • Returns true if the JSONB is a Null.
  • Returns true if the JSONB is a Number. Returns false otherwise.
  • Returns true if the JSONB is An Object. Returns false otherwise.
  • Returns true if the JSONB is a String. Returns false otherwise.
  • Returns true if the JSONB is a u64 Number. Returns false otherwise.
  • Convert the values of a JSONB object to vector of key-value pairs.
  • Get the keys of a JSONB object.
  • Checks whether the JSON path returns any item for the JSONB value.
  • Returns the result of a JSON path predicate check for the specified JSONB value.
  • generate random JSONB value
  • Deletes all object fields that have null values from the given JSON value, recursively. Null values that are not object fields are untouched.
  • Cast JSONB value to Boolean
  • Cast JSONB value to f64
  • Cast JSONB value to i64
  • Convert JSONB value to pretty String
  • Convert JSONB value to serde_json Value
  • Convert JSONB value to serde_json Object Value
  • Cast JSONB value to String
  • Convert JSONB value to String
  • Cast JSONB value to u64
  • Traverse all the string fields in a jsonb value and check whether the conditions are met.
  • 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§