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 theJSON
standard and can be used to store complex data structures. - Fast performance:
jsonb
is designed for high performance, allowing you to work with largeJSON
data sets with ease. - Easy to use:
jsonb
provides a number of built-in functions to support various operations, and also supports theJSONPath
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
andarray
, and 29 bits identify the number of JEntries in thearray
orobject
. The root node of thejsonb
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
andcontainer
, 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 header0x50000000
- 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 nestedjson
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 thecompare
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
andRawData
. This structure can be nested. Each group of structures starts with aHeader
. The upper-levelValue
will store theHeader
length or offset of the lower-levelValue
.Header
stores the type of theValue
, includeArray
,Object
andScalar
,Scalar
has only oneValue
, and a correspondingJEntry
.Array
andObject
are nested type, they have multiple lower-levelValues
. So theHeader
also stores the number of lower-levelValues
.JEntry
stores the types ofScalar Value
, includingNull
,True
,False
,Number
,String
andContainer
. 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, ifignore_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 anJSONB
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 toserde_json
Value - Convert
JSONB
value toserde_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.