Skip to content

Terms

SQL and C interface

Datum

The general C type that PostgreSQL uses to pass SQL values. A small value can fit in the Datum. A variable-length value normally uses the Datum as a pointer.

fcinfo

The information for one PostgreSQL function call. It contains the arguments, null flags, result information, and other call data. PG_FUNCTION_ARGS declares this value for a C function.

PG_GETARG_POINTER

A macro that returns the raw pointer from a function argument. It does not detoast the value. The extension uses it to inspect the current storage form before it selects a read path.

PG_GETARG_JSONB_P

A macro that returns a usable Jsonb *. PostgreSQL detoasts and decompresses the argument when this is necessary. This can read the complete value.

SQL null

The absence of an SQL value. PostgreSQL does not call a STRICT function when an argument is SQL null.

JSON null

A real JSON value whose JSON type is null. It is different from SQL null.

Variable-length values

varlena

The common PostgreSQL representation for variable-length values, such as text and jsonb. A normal value starts with a four-byte header. A raw varlena pointer can also identify a short value, a compressed value, or an external value.

varlena header

The prefix that identifies the varlena form and its size. PostgreSQL code must use the varlena macros to read it.

Form Prefix before its data
Normal inline value 4 bytes
Short inline value 1 byte
Compressed inline value 8 bytes
On-disk external pointer 2 bytes before the pointer metadata

The compressed form has a four-byte varlena header and a four-byte compression information field. An on-disk TOAST pointer normally has a two-byte prefix and 16 bytes of pointer metadata. It does not contain the value data.

logical data

The uncompressed bytes that form the SQL value. A TOAST slice offset starts in this data, after the original varlena header. For jsonb, offset zero is the root container header.

stored size

The number of bytes in the current stored form. Compression can make the stored size smaller than the logical size.

TOAST storage

TOAST

PostgreSQL's system for values that are too large for normal row storage. It can compress a value or move it to a secondary table in chunks.

inline value

A value that is present in the main table row. It can be uncompressed or compressed.

compressed value

A value whose data uses a PostgreSQL compression method. Compression does not show whether the value is in memory or on disk. A value can be compressed inline or compressed in a TOAST table.

external value

A value that PostgreSQL stores outside the main table row. The table row keeps a small pointer to the value. An external value can be compressed or uncompressed.

TOAST pointer

Metadata that identifies an external value. An on-disk TOAST pointer records the logical size, stored size and compression information, value identifier, and TOAST table identifier. It does not contain the JSONB data.

TOAST chunk

One numbered part of an external value in a TOAST table.

TOAST slice

A requested byte range from a TOAST value. For an external, uncompressed value, PostgreSQL reads the TOAST chunks that cover the range.

detoast

To make the logical value available from its current TOAST form. This can include reading all chunks and decompressing the value.

storage representation

The current form of one stored value: inline, compressed, or external. PostgreSQL macros inspect this form. They do not calculate whether the value could fit in the row.

storage strategy

The column setting that tells TOAST which storage operations it can use.

Strategy Behavior
PLAIN Keep the value inline. Do not compress it.
MAIN Allow compression. Prefer inline storage.
EXTERNAL Allow external storage. Do not compress it.
EXTENDED Allow compression and external storage.

VARATT_IS_EXTERNAL_ONDISK

A macro that reports whether a raw value is an on-disk TOAST pointer. It inspects the current representation. It does not test whether the complete value can fit in a row.

VARATT_EXTERNAL_IS_COMPRESSED

A macro that reports whether the value behind an on-disk TOAST pointer is compressed.

JSONB layout

jsonb

PostgreSQL's binary representation of JSON data. It stores a container directory before the container data.

JSONB container header

The first four bytes of a JSONB container. It records the container type and item count. It is part of the logical JSONB data. It is not the varlena header.

JEntry

A four-byte JSONB directory entry. It records a value type and either a length or an end offset. An object uses one key entry and one value entry for each field.

JSONB object directory

The JEntry array at the start of a JSONB object. The key entries come first. The value entries follow them. The key and value bytes come after the complete directory.

JSONB array directory

The JEntry array at the start of a JSONB array. It contains one entry for each array element. Array elements do not have key entries.

nested container

An object or array stored as a value inside another JSONB container. It has its own container header and directory. It does not have another outer varlena header.

raw scalar wrapper

The one-element root array that PostgreSQL uses to store a JSON scalar in JSONB. The scalar flag is valid only on this root container.

Project structures

SliceSource

The per-call context for partial reads. It keeps the raw external value, the logical read boundary, and the byte counter used by the regression test. It is a local C structure. It is not stored in PostgreSQL.

ValueLocation

The decoded location of one JSONB value. It keeps the JEntry type, absolute slice offset, and requested size. This lets the code validate a location before it fetches and rebuilds the result.

ContainerLocation

The absolute start and byte size of one JSONB container. It also records whether the container is the root. Path traversal replaces this value when it enters a nested object or array.

complete-value fallback

The call to a PostgreSQL JSONB function when the extension cannot safely use TOAST slices. Inline input, compressed input, an empty path, or invalid storage metadata can select this path.

Planner terms

planner hook

A PostgreSQL function pointer that lets an extension wrap normal planning. jsonb_slice calls the previous hook or PostgreSQL's standard planner first. It then inspects the completed plan.

Query

PostgreSQL's analyzed representation of a statement before planning. Transparent mode does not change this structure.

PlannedStmt

The top-level executable plan returned by the planner. It owns the main plan tree, subplans, range-table entries, and invalidation dependencies.

OpExpr

An expression written with an SQL operator. It stores the operator OID in opno and the executable function OID in opfuncid. Transparent mode keeps opno and can replace opfuncid.

FuncExpr

A direct SQL function call in an expression tree. Its funcid field identifies the executable function.

copy-on-write plan traversal

A traversal that returns the original plan node when nothing changes. When a field changes, it copies the complete concrete node and updates the copy. This avoids modifying a plan returned by PostgreSQL or another extension hook.

transparent mode

The optional jsonb_slice.transparent setting. When it is on, supported built-in JSONB accessor calls can use validated extension functions. The mode is off by default.

plan invalidation dependency

A catalog dependency stored in a planned statement. A relevant function or permission change invalidates the cached plan so PostgreSQL can plan it again.