1/*-------------------------------------------------------------------------
4 * Declarations for jsonb data type support.
6 * Copyright (c) 1996-2025, PostgreSQL Global Development Group
8 * src/include/utils/jsonb.h
10 *-------------------------------------------------------------------------
19/* Tokens used when sequentially processing a jsonb value */
32/* Strategy numbers for GIN index opclasses */
33 #define JsonbContainsStrategyNumber 7
34 #define JsonbExistsStrategyNumber 9
35 #define JsonbExistsAnyStrategyNumber 10
36 #define JsonbExistsAllStrategyNumber 11
37 #define JsonbJsonpathExistsStrategyNumber 15
38 #define JsonbJsonpathPredicateStrategyNumber 16
42 * In the standard jsonb_ops GIN opclass for jsonb, we choose to index both
43 * keys and values. The storage format is text. The first byte of the text
44 * string distinguishes whether this is a key (always a string), null value,
45 * boolean value, numeric value, or string value. However, array elements
46 * that are strings are marked as though they were keys; this imprecision
47 * supports the definition of the "exists" operator, which treats array
48 * elements like keys. The remainder of the text string is empty for a null
49 * value, "t" or "f" for a boolean value, a normalized print representation of
50 * a numeric value, or the text of a string value. However, if the length of
51 * this text representation would exceed JGIN_MAXLENGTH bytes, we instead hash
52 * the text representation and store an 8-hex-digit representation of the
53 * uint32 hash value, marking the prefix byte with an additional bit to
54 * distinguish that this has happened. Hashing long strings saves space and
55 * ensures that we won't overrun the maximum entry length for a GIN index.
56 * (But JGIN_MAXLENGTH is quite a bit shorter than GIN's limit. It's chosen
57 * to ensure that the on-disk text datum will have a short varlena header.)
58 * Note that when any hashed item appears in a query, we must recheck index
59 * matches against the heap tuple; currently, this costs nothing because we
60 * must always recheck for other reasons.
62 #define JGINFLAG_KEY 0x01 /* key (or string array element) */
63 #define JGINFLAG_NULL 0x02 /* null value */
64 #define JGINFLAG_BOOL 0x03 /* boolean value */
65 #define JGINFLAG_NUM 0x04 /* numeric value */
66 #define JGINFLAG_STR 0x05 /* string value (if not an array element) */
67 #define JGINFLAG_HASHED 0x10 /* OR'd into flag if value was hashed */
68 #define JGIN_MAXLENGTH 125 /* max length of text part before hashing */
74 * Jsonbs are varlena objects, so must meet the varlena convention that the
75 * first int32 of the object contains the total object size in bytes. Be sure
76 * to use VARSIZE() and SET_VARSIZE() to access it, though!
78 * Jsonb is the on-disk representation, in contrast to the in-memory JsonbValue
79 * representation. Often, JsonbValues are just shims through which a Jsonb
80 * buffer is accessed, but they can also be deep copied and passed around.
82 * Jsonb is a tree structure. Each node in the tree consists of a JEntry
83 * header and a variable-length content (possibly of zero size). The JEntry
84 * header indicates what kind of a node it is, e.g. a string or an array,
85 * and provides the length of its variable-length portion.
87 * The JEntry and the content of a node are not stored physically together.
88 * Instead, the container array or object has an array that holds the JEntrys
89 * of all the child nodes, followed by their variable-length portions.
91 * The root node is an exception; it has no parent array or object that could
92 * hold its JEntry. Hence, no JEntry header is stored for the root node. It
93 * is implicitly known that the root node must be an array or an object,
94 * so we can get away without the type indicator as long as we can distinguish
95 * the two. For that purpose, both an array and an object begin with a uint32
96 * header field, which contains an JB_FOBJECT or JB_FARRAY flag. When a naked
97 * scalar value needs to be stored as a Jsonb value, what we actually store is
98 * an array with one element, with the flags in the array's header field set
99 * to JB_FSCALAR | JB_FARRAY.
101 * Overall, the Jsonb struct requires 4-bytes alignment. Within the struct,
102 * the variable-length portion of some node types is aligned to a 4-byte
103 * boundary, while others are not. When alignment is needed, the padding is
104 * in the beginning of the node that requires it. For example, if a numeric
105 * node is stored after a string node, so that the numeric node begins at
106 * offset 3, the variable-length portion of the numeric node will begin with
107 * one padding byte so that the actual numeric data is 4-byte aligned.
113 * The least significant 28 bits store either the data length of the entry,
114 * or its end+1 offset from the start of the variable-length portion of the
115 * containing object. The next three bits store the type of the entry, and
116 * the high-order bit tells whether the least significant bits store a length
119 * The reason for the offset-or-length complication is to compromise between
120 * access speed and data compressibility. In the initial design each JEntry
121 * always stored an offset, but this resulted in JEntry arrays with horrible
122 * compressibility properties, so that TOAST compression of a JSONB did not
123 * work well. Storing only lengths would greatly improve compressibility,
124 * but it makes random access into large arrays expensive (O(N) not O(1)).
125 * So what we do is store an offset in every JB_OFFSET_STRIDE'th JEntry and
126 * a length in the rest. This results in reasonably compressible data (as
127 * long as the stride isn't too small). We may have to examine as many as
128 * JB_OFFSET_STRIDE JEntrys in order to find out the offset or length of any
129 * given item, but that's still O(1) no matter how large the container is.
131 * We could avoid eating a flag bit for this purpose if we were to store
132 * the stride in the container header, or if we were willing to treat the
133 * stride as an unchangeable constant. Neither of those options is very
138 #define JENTRY_OFFLENMASK 0x0FFFFFFF
139 #define JENTRY_TYPEMASK 0x70000000
140 #define JENTRY_HAS_OFF 0x80000000
142/* values stored in the type bits */
143 #define JENTRY_ISSTRING 0x00000000
144 #define JENTRY_ISNUMERIC 0x10000000
145 #define JENTRY_ISBOOL_FALSE 0x20000000
146 #define JENTRY_ISBOOL_TRUE 0x30000000
147 #define JENTRY_ISNULL 0x40000000
148 #define JENTRY_ISCONTAINER 0x50000000 /* array or object */
150/* Access macros. Note possible multiple evaluations */
151 #define JBE_OFFLENFLD(je_) ((je_) & JENTRY_OFFLENMASK)
152 #define JBE_HAS_OFF(je_) (((je_) & JENTRY_HAS_OFF) != 0)
153 #define JBE_ISSTRING(je_) (((je_) & JENTRY_TYPEMASK) == JENTRY_ISSTRING)
154 #define JBE_ISNUMERIC(je_) (((je_) & JENTRY_TYPEMASK) == JENTRY_ISNUMERIC)
155 #define JBE_ISCONTAINER(je_) (((je_) & JENTRY_TYPEMASK) == JENTRY_ISCONTAINER)
156 #define JBE_ISNULL(je_) (((je_) & JENTRY_TYPEMASK) == JENTRY_ISNULL)
157 #define JBE_ISBOOL_TRUE(je_) (((je_) & JENTRY_TYPEMASK) == JENTRY_ISBOOL_TRUE)
158 #define JBE_ISBOOL_FALSE(je_) (((je_) & JENTRY_TYPEMASK) == JENTRY_ISBOOL_FALSE)
159 #define JBE_ISBOOL(je_) (JBE_ISBOOL_TRUE(je_) || JBE_ISBOOL_FALSE(je_))
161/* Macro for advancing an offset variable to the next JEntry */
162 #define JBE_ADVANCE_OFFSET(offset, je) \
165 if (JBE_HAS_OFF(je_)) \
166 (offset) = JBE_OFFLENFLD(je_); \
168 (offset) += JBE_OFFLENFLD(je_); \
172 * We store an offset, not a length, every JB_OFFSET_STRIDE children.
173 * Caution: this macro should only be referenced when creating a JSONB
174 * value. When examining an existing value, pay attention to the HAS_OFF
175 * bits instead. This allows changes in the offset-placement heuristic
176 * without breaking on-disk compatibility.
178 #define JB_OFFSET_STRIDE 32
181 * A jsonb array or object node, within a Jsonb Datum.
183 * An array has one child for each element, stored in array order.
185 * An object has two children for each key/value pair. The keys all appear
186 * first, in key sort order; then the values appear, in an order matching the
187 * key order. This arrangement keeps the keys compact in memory, making a
188 * search for a particular key more cache-friendly.
196 /* the data for each child node follows. */
199/* flags for the header-field in JsonbContainer */
200 #define JB_CMASK 0x0FFFFFFF /* mask for count field */
201 #define JB_FSCALAR 0x10000000 /* flag bits */
202 #define JB_FOBJECT 0x20000000
203 #define JB_FARRAY 0x40000000
205/* convenience macros for accessing a JsonbContainer struct */
206 #define JsonContainerSize(jc) ((jc)->header & JB_CMASK)
207 #define JsonContainerIsScalar(jc) (((jc)->header & JB_FSCALAR) != 0)
208 #define JsonContainerIsObject(jc) (((jc)->header & JB_FOBJECT) != 0)
209 #define JsonContainerIsArray(jc) (((jc)->header & JB_FARRAY) != 0)
211/* The top-level on-disk format for a jsonb datum. */
218/* convenience macros for accessing the root container in a Jsonb datum */
219 #define JB_ROOT_COUNT(jbp_) (*(uint32 *) VARDATA(jbp_) & JB_CMASK)
220 #define JB_ROOT_IS_SCALAR(jbp_) ((*(uint32 *) VARDATA(jbp_) & JB_FSCALAR) != 0)
221 #define JB_ROOT_IS_OBJECT(jbp_) ((*(uint32 *) VARDATA(jbp_) & JB_FOBJECT) != 0)
222 #define JB_ROOT_IS_ARRAY(jbp_) ((*(uint32 *) VARDATA(jbp_) & JB_FARRAY) != 0)
232 /* Composite types */
235 /* Binary (i.e. struct Jsonb) jbvArray/jbvObject */
241 * These types are used only for in-memory JSON processing and serialized
242 * into JSON strings when outputted to json/jsonb.
248 * JsonbValue: In-memory representation of Jsonb. This is a convenient
249 * deserialized representation, that can easily support using the "val"
250 * union across underlying types during manipulation. The Jsonb on-disk
251 * representation has various alignment considerations.
264 char *
val;
/* Not necessarily null-terminated */
278 }
object;
/* Associative container type */
284 }
binary;
/* Array or object, in on-disk format */
291 int tz;
/* Numeric time zone, in seconds, for
292 * TimestampTz data type */
297 #define IsAJsonbScalar(jsonbval) (((jsonbval)->type >= jbvNull && \
298 (jsonbval)->type <= jbvBool) || \
299 (jsonbval)->type == jbvDatetime)
302 * Key/value pair within an Object.
304 * This struct type is only used briefly while constructing a Jsonb; it is
305 * *not* the on-disk representation.
307 * Pairs with duplicate keys are de-duplicated. We store the originally
308 * observed pair ordering for the purpose of removing duplicates in a
309 * well-defined way (which is "last observed wins").
318/* Conversion state used when parsing Jsonb from text, or for type coercion */
329 * JsonbIterator holds details of the type for each iteration. It also stores a
330 * Jsonb varlena buffer, which can be directly accessed in some contexts.
343 /* Container being iterated */
346 * be nPairs for objects) */
349 /* Data proper. This points to the beginning of the variable-length data */
352 /* Current item in buffer (up to nElems) */
355 /* Data offset corresponding to current item */
359 * If the container is an object, we want to return keys and values
360 * alternately; so curDataOffset points to the current key, and
361 * curValueOffset points to the current value.
372/* Convenience macros */
391 #define PG_GETARG_JSONB_P(x) DatumGetJsonbP(PG_GETARG_DATUM(x))
392 #define PG_GETARG_JSONB_P_COPY(x) DatumGetJsonbPCopy(PG_GETARG_DATUM(x))
393 #define PG_RETURN_JSONB_P(x) PG_RETURN_POINTER(x)
395/* Support functions */
403 const char *keyVal,
int keyLen,
420/* jsonb.c support functions */
432 bool *isnull,
bool as_text);
435 const Oid *
types,
bool absent_on_null,
438 const Oid *
types,
bool absent_on_null);
440#endif /* __JSONB_H__ */
#define FLEXIBLE_ARRAY_MEMBER
#define PG_DETOAST_DATUM_COPY(datum)
#define PG_DETOAST_DATUM(datum)
static Jsonb * DatumGetJsonbPCopy(Datum d)
char * JsonbUnquote(Jsonb *jb)
Datum jsonb_build_array_worker(int nargs, const Datum *args, const bool *nulls, const Oid *types, bool absent_on_null)
static Datum JsonbPGetDatum(const Jsonb *p)
struct JsonbParseState JsonbParseState
Datum jsonb_set_element(Jsonb *jb, Datum *path, int path_len, JsonbValue *newval)
JsonbValue * getKeyJsonValueFromContainer(JsonbContainer *container, const char *keyVal, int keyLen, JsonbValue *res)
int compareJsonbContainers(JsonbContainer *a, JsonbContainer *b)
Datum jsonb_get_element(Jsonb *jb, Datum *path, int npath, bool *isnull, bool as_text)
uint32 getJsonbLength(const JsonbContainer *jc, int index)
char * JsonbToCString(StringInfo out, JsonbContainer *in, int estimated_len)
JsonbValue * pushJsonbValue(JsonbParseState **pstate, JsonbIteratorToken seq, JsonbValue *jbval)
JsonbIterator * JsonbIteratorInit(JsonbContainer *container)
const char * JsonbTypeName(JsonbValue *val)
static Jsonb * DatumGetJsonbP(Datum d)
void JsonbHashScalarValue(const JsonbValue *scalarVal, uint32 *hash)
Datum jsonb_build_object_worker(int nargs, const Datum *args, const bool *nulls, const Oid *types, bool absent_on_null, bool unique_keys)
void JsonbToJsonbValue(Jsonb *jsonb, JsonbValue *val)
JsonbValue * findJsonbValueFromContainer(JsonbContainer *container, uint32 flags, JsonbValue *key)
JsonbIteratorToken JsonbIteratorNext(JsonbIterator **it, JsonbValue *val, bool skipNested)
struct JsonbIterator JsonbIterator
uint32 getJsonbOffset(const JsonbContainer *jc, int index)
bool JsonbExtractScalar(JsonbContainer *jbc, JsonbValue *res)
void JsonbHashScalarValueExtended(const JsonbValue *scalarVal, uint64 *hash, uint64 seed)
JsonbValue * getIthJsonbValueFromContainer(JsonbContainer *container, uint32 i)
Jsonb * JsonbValueToJsonb(JsonbValue *val)
char * JsonbToCStringIndent(StringInfo out, JsonbContainer *in, int estimated_len)
bool JsonbDeepContains(JsonbIterator **val, JsonbIterator **mContained)
bool to_jsonb_is_immutable(Oid typoid)
struct JsonbContainer JsonbContainer
static Datum PointerGetDatum(const void *X)
static unsigned hash(unsigned *uv, int n)
JEntry children[FLEXIBLE_ARRAY_MEMBER]
struct JsonbIterator * parent
JsonbContainer * container
struct JsonbParseState * next
struct JsonbValue::@144::@149 datetime
struct JsonbValue::@144::@147 object
struct JsonbValue::@144::@146 array
struct JsonbValue::@144::@148 binary
struct JsonbValue::@144::@145 string