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
nullto SQLNULL. - 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.