json_binary.h File Reference

This file specifies the interface for serializing JSON values into binary representation, and for reading values back from the binary representation. More...

#include <stddef.h>
#include <cassert>
#include <cstdint>
#include <string>
#include <string_view>
#include "field_types.h"
#include "sql-common/json_error_handler.h"

Go to the source code of this file.

Classes
class	json_binary::Value
	Class used for reading JSON values that are stored in the binary format. More...

Namespaces
namespace	json_binary

Macros
#define	EXPORT_JSON_FUNCTION

Functions
void	json_binary::write_offset_or_size (char *dest, size_t offset_or_size, bool large)
	Write an offset or a size to a char array. More...
bool	json_binary::append_offset_or_size (String *dest, size_t offset_or_size, bool large)
	Append an offset or a size to a String. More...
bool	json_binary::append_int16 (String *dest, int16_t value)
	Encode a 16-bit int at the end of the destination string. More...
bool	json_binary::attempt_inline_value (const Json_dom *value, String *dest, size_t pos, bool large)
	Attempt to inline a value in its value entry at the beginning of an object or an array. More...
uint32_t	json_binary::read_offset_or_size (const char *data, bool large)
	Read an offset or size field from a buffer. More...
bool	json_binary::inlined_type (uint8_t type, bool large)
	Will a value of the specified type be inlined? More...
uint8_t	json_binary::offset_size (bool large)
	Get the size of an offset value. More...
uint8_t	json_binary::key_entry_size (bool large)
	Get the size of a key entry. More...
uint8_t	json_binary::value_entry_size (bool large)
	Get the size of a value entry. More...
bool	json_binary::serialize (const Json_dom *dom, const JsonSerializationErrorHandler &error_handler, String *dest)
	Serialize the JSON document represented by dom to binary format in the destination string, replacing any content already in the destination string. More...
Value	json_binary::parse_binary (const char *data, size_t len)
	Parse a JSON binary document. More...
bool	json_binary::space_needed (const Json_wrapper *value, bool large, size_t *needed)
	How much space is needed for a JSON value when it is stored in the binary format. More...
template<typename Func >
bool	json_binary::for_each_node (const Value &value, const Func &func)
	Apply a function to every value in a JSON document. More...

Variables
constexpr char	json_binary::JSONB_TYPE_SMALL_OBJECT = 0x0
constexpr char	json_binary::JSONB_TYPE_LARGE_OBJECT = 0x1
constexpr char	json_binary::JSONB_TYPE_SMALL_ARRAY = 0x2
constexpr char	json_binary::JSONB_TYPE_LARGE_ARRAY = 0x3
constexpr char	json_binary::JSONB_TYPE_LITERAL = 0x4
constexpr char	json_binary::JSONB_TYPE_INT16 = 0x5
constexpr char	json_binary::JSONB_TYPE_UINT16 = 0x6
constexpr char	json_binary::JSONB_TYPE_INT32 = 0x7
constexpr char	json_binary::JSONB_TYPE_UINT32 = 0x8
constexpr char	json_binary::JSONB_TYPE_INT64 = 0x9
constexpr char	json_binary::JSONB_TYPE_UINT64 = 0xA
constexpr char	json_binary::JSONB_TYPE_DOUBLE = 0xB
constexpr char	json_binary::JSONB_TYPE_STRING = 0xC
constexpr char	json_binary::JSONB_TYPE_OPAQUE = 0xF
constexpr char	json_binary::JSONB_NULL_LITERAL = 0x0
constexpr char	json_binary::JSONB_TRUE_LITERAL = 0x1
constexpr char	json_binary::JSONB_FALSE_LITERAL = 0x2

Detailed Description

This file specifies the interface for serializing JSON values into binary representation, and for reading values back from the binary representation.

The binary format is as follows:

Each JSON value (scalar, object or array) has a one byte type identifier followed by the actual value.

If the value is a JSON object, its binary representation will have a header that contains:

• the member count
• the size of the binary value in bytes
• a list of pointers to each key
• a list of pointers to each value

The actual keys and values will come after the header, in the same order as in the header.

Similarly, if the value is a JSON array, the binary representation will have a header with

• the element count
• the size of the binary value in bytes
• a list of pointers to each value

followed by the actual values, in the same order as in the header.

doc ::= type value

type ::=
    0x00 |       // small JSON object
    0x01 |       // large JSON object
    0x02 |       // small JSON array
    0x03 |       // large JSON array
    0x04 |       // literal (true/false/null)
    0x05 |       // int16
    0x06 |       // uint16
    0x07 |       // int32
    0x08 |       // uint32
    0x09 |       // int64
    0x0a |       // uint64
    0x0b |       // double
    0x0c |       // utf8mb4 string
    0x0f         // custom data (any MySQL data type)

value ::=
    object  |
    array   |
    literal |
    number  |
    string  |
    custom-data

object ::= element-count size key-entry* value-entry* key* value*

array ::= element-count size value-entry* value*

// number of members in object or number of elements in array
element-count ::=
    uint16 |  // if used in small JSON object/array
    uint32    // if used in large JSON object/array

// number of bytes in the binary representation of the object or array
size ::=
    uint16 |  // if used in small JSON object/array
    uint32    // if used in large JSON object/array

key-entry ::= key-offset key-length

key-offset ::=
    uint16 |  // if used in small JSON object
    uint32    // if used in large JSON object

key-length ::= uint16    // key length must be less than 64KB

value-entry ::= type offset-or-inlined-value

// This field holds either the offset to where the value is stored,
// or the value itself if it is small enough to be inlined (that is,
// if it is a JSON literal or a small enough [u]int).
offset-or-inlined-value ::=
    uint16 |   // if used in small JSON object/array
    uint32     // if used in large JSON object/array

key ::= utf8mb4-data

literal ::=
    0x00 |   // JSON null literal
    0x01 |   // JSON true literal
    0x02 |   // JSON false literal

number ::=  ....  // little-endian format for [u]int(16|32|64), whereas
                  // double is stored in a platform-independent, eight-byte
                  // format using float8store()

string ::= data-length utf8mb4-data

custom-data ::= custom-type data-length binary-data

custom-type ::= uint8   // type identifier that matches the
                        // internal enum_field_types enum

data-length ::= uint8*  // If the high bit of a byte is 1, the length
                        // field is continued in the next byte,
                        // otherwise it is the last byte of the length
                        // field. So we need 1 byte to represent
                        // lengths up to 127, 2 bytes to represent
                        // lengths up to 16383, and so on...

Macro Definition Documentation

EXPORT_JSON_FUNCTION

#define EXPORT_JSON_FUNCTION