Skip to content

0.4.0

Release type: JSONB accessors and operators.

Purpose

This release extends the partial reader from one top-level object key to the main JSONB read forms. It can read an object key, an array index, or a nested path. Each read can return JSONB or SQL text.

The extension also provides operators for these functions. PostgreSQL's built-in operators do not change.

SQL interface

Function Matching PostgreSQL expression
jsonb_slice_get(jsonb, text) document -> key
jsonb_slice_get(jsonb, integer) document -> index
jsonb_slice_get_text(jsonb, text) document ->> key
jsonb_slice_get_text(jsonb, integer) document ->> index
jsonb_slice_path(jsonb, text[]) document #> path
jsonb_slice_path_text(jsonb, text[]) document #>> path
Extension operator Function
jsonb ~> text jsonb_slice_get(jsonb, text)
jsonb ~> integer jsonb_slice_get(jsonb, integer)
jsonb ~>> text jsonb_slice_get_text(jsonb, text)
jsonb ~>> integer jsonb_slice_get_text(jsonb, integer)
jsonb ~#> text[] jsonb_slice_path(jsonb, text[])
jsonb ~#>> text[] jsonb_slice_path_text(jsonb, text[])

Partial read path

An external, uncompressed JSONB value can use TOAST slices. A key read uses the root object directory and key bytes. An index read uses the root array directory. A path read repeats the correct lookup inside each object or array on the path.

The reader does not fetch sibling value payloads during traversal. It fetches the complete selected value at the final path step. A selected object or array therefore includes that complete container.

Inline values, compressed values, empty paths, and invalid storage metadata use PostgreSQL's complete-value functions.

Result rules

  • A missing key, missing index, or invalid path returns SQL NULL.
  • A negative array index counts from the end.
  • A JSONB result preserves JSON null.
  • A text result converts JSON null to SQL NULL.
  • A path can move through objects and arrays.
  • A path cannot continue through a scalar value.
  • A null path element returns SQL NULL.

Verification

The regression tests compare every accessor and operator with its PostgreSQL equivalent. They cover objects, arrays, nested paths, negative indexes, missing values, JSON null, scalar values, and container results. Fresh installation and upgrade from 0.3.0 are also tested.

For selected external, uncompressed fixtures, a test counter confirms that the requested slice sizes total less than the stored test value. Compressed fixtures confirm that the complete-value fallback is used.

Boundary

This release is an experiment. It makes no general performance claim. The partial read path requires external, uncompressed JSONB storage. It reads the complete directory for each visited container and all key bytes for each visited object.