Documentation Source Text

SQLite is that it is smaller and faster than text JSON - potentially several
times faster. There is space in the
on-disk JSONB format to add enhancements and future versions of SQLite might
include options to provide O(1) lookup of elements in JSONB, but no such
capability is currently available.

<p>
The core idea behind SQLite's JSONB is that each element begins with a header
that includes the size and type of that element.  This makes reading
faster.  For example, when reading
a string literal, it is no longer necessary to search forward looking
for the closing double-quote, reading byte by byte and taking care
to avoid escaped double-quotes.  The size of
the literal is right there in the header, and so the process can jump
ahead to the next element without having to scrutinize each
intervening byte.  Since the size and type of each element is
identified in the header, punctuation characters such as string, object,
and array delimiters and comma and colon separators can all be omitted.
The payload for JSONB is the same as the corresponding text JSON.
The only difference is that JSONB omits punctuation and replaces it with
a header on each element.

<p>
The SQLite JSONB format is intended to be private to
SQLite and is for use by the built-in SQLite functions only.  The
JSONB format is not intended as an interchange format.  Nevertheless,
JSONB is stored in database files which are intended to
be readable and writable for many decades into the fugure.
To that end, the JSONB format is well-defined and stable. The separate
[SQLite JSONB format] document provides details of the JSONB format
for the curious reader.

<tcl>hd_fragment jsonpath {JSON paths} {JSON function path arguments}</tcl>
<h2>PATH arguments</h2>

<p>

<p>
The "JSONB" name is inspired by [https://postgresql.org|PostgreSQL], but the
on-disk format for SQLite's JSONB is not the same as PostgreSQL's.
The two formats have the same name, but they have wildly different internal
representations and are not in any way binary compatible.

<p>
The central idea behind this JSONB specification is that each element
begins with a header that includes the size and type of that element.
The header takes the place of punctuation such as double-quotes,
curly-brackes, square-brackets, commas, and colons.  Since the size
and type of each element is contained in its header, the element can
be read faster since it is no longer necessary to carefully scan forward
looking for the closing delimiter.  The payload of JSONB is the same
as for corresponding text JSON.  The same payload bytes occur in the
same order.  The only real difference between JSONB and ordinary text
JSON is that JSONB includes a binary header on
each element and omits delimiter and separator punctuation.

<h1>The Purpose Of This Document</h1>

<p>
JSONB is not intended as an external format to be used by
applications.  JSONB is designed for internal use by SQLite only.
Programmers do not need to understand the JSONB format in order to
use it effectively.