GizStack
View .mdOpen in ChatGPTOpen in Claude

gizmodel/sql/types/json

JSON as PostgreSQL 16 reads, prints and queries it: JSON text as exact items (json, jsonb), and SQL/JSON paths, the jsonpath type: its parser (jsonpath_scan.l, jsonpath_gram.y), its canonical text (jsonpath_out) and its evaluation (jsonpath_exec.c). Lax mode unwraps arrays and ignores structural errors; strict mode reports them; predicates are true, false or unknown. Numbers stay numeric text, as jsonb keeps them.

gizlang
import * as Json from "gizmodel/sql/types/json";

Types

JV

gizlang
type JV = { k: i64; s: string; items: Vec<JV>; keys: Vec<string>; off: i64; base: i64; plain: bool; }

A JSON value with exact numbers. k is its kind (J*); s a boolean's or number's text, or a string's characters; items an array's elements or an object's values, keys the object's keys in jsonb order (shorter first, then by bytes; one of each). off and base place a container in PostgreSQL's jsonb binary form, which .keyvalue() reports as the object's id.

  • k: i64
  • s: string
  • items: Vec<M161.JV>
  • keys: Vec<string>
  • off: i64
  • base: i64
  • plain: bool

JsonParts

gizlang
type JsonParts = { kind: i64; keys: Vec<string>; values: Vec<string>; }

A JSON text's top-level parts as written: an array's elements, or an object's keys (decoded) and values. kind is JARR, JOBJ or, for a scalar, its kind; none when the text is not JSON.

  • kind: i64
  • keys: Vec<string>
  • values: Vec<string>

JsonPath

gizlang
type JsonPath = { lax: bool; root: JP; keyvalue: bool; }

A parsed path; keyvalue when it calls .keyvalue(), whose ids need the jsonb layout.

  • lax: bool
  • root: M161.JP
  • keyvalue: bool

Selection

gizlang
type Selection = { items: Vec<JV>; complete: bool; }

What a path selects: its items, and whether the walk completed (an error ends it in silent mode).

  • items: Vec<M161.JV>
  • complete: bool

Functions

container

gizlang
function container(v: JV): bool

Whether V is an array or an object.

readJson

gizlang
function readJson(text: string): JV throws DbError

A JSON text as an item tree; 22P02 when it is not JSON.

Effects: fail, alloc.

readPlain

gizlang
function readPlain(text: string): JV throws DbError

A JSON text as written (SQL/JSON of Oracle): objects keep their key order and duplicate keys, numbers their digits (the exponent mark in upper case).

Effects: fail, alloc.

jvText

gizlang
function jvText(v: JV): string

An item as jsonb text: ", " and ": " between parts, as PostgreSQL prints jsonb.

Effects: fail, alloc.

jvCompact

gizlang
function jvCompact(v: JV): string

An item as JSON text without the spaces.

Effects: fail, alloc.

jvListText

gizlang
function jvListText(items: Vec<JV>): string

Items as the text of a jsonb array of them.

Effects: fail, alloc.

jsonbSetPath

gizlang
function jsonbSetPath(doc: string, path: Vec<string>, value: string, mode: string): string throws DbError

jsonb_set, jsonb_insert or jsonb_delete_path (mode as setPath) of jsonb text doc.

Effects: fail, alloc.

jsonbAssign

gizlang
function jsonbAssign(doc: string, path: Vec<string>, numeric: Vec<bool>, value: string): string throws DbError

UPDATE ... SET j[k1][k2]... = value (PostgreSQL's jsonb subscript assignment): a missing key or element is made, an object for a text subscript and an array for an integer one; an array grows with nulls to the index. doc "" is SQL NULL. numeric tells for each subscript whether it is an integer.

Effects: fail, alloc.

jsonbDelete

gizlang
function jsonbDelete(doc: string, keys: Vec<string>, byIndex: bool, index: i64): string throws DbError

jsonb - key, jsonb - keys (an array's string items or an object's keys) and jsonb - index.

Effects: fail, alloc.

jsonbConcat

gizlang
function jsonbConcat(left: string, right: string): string throws DbError

jsonb || jsonb: two objects merge (the right one's keys win); otherwise an array of the left items then the right items, a scalar or an object counting as one item.

Effects: fail, alloc.

jsonbStripNulls

gizlang
function jsonbStripNulls(doc: string): string throws DbError

jsonb_strip_nulls: object fields whose value is null are left out, at every depth.

Effects: fail, alloc.

jsonbPretty

gizlang
function jsonbPretty(doc: string): string throws DbError

jsonb_pretty: one item a line, four spaces a level.

Effects: fail, alloc.

jsonbCompare

gizlang
function jsonbCompare(a: JV, b: JV): i64

PostgreSQL's jsonb ordering: an object above an array above a boolean above a number above a string above null. Containers with more items are greater; others compare item by item (an object key, then its value), numbers as numbers, strings by bytes and false before true.

Effects: fail, alloc.

jsonPart

gizlang
function jsonPart(text: string, path: Vec<string>, only: i64): Option<string>

The part of JSON text that path reaches, as written (jsonb text gives jsonb text): each step a key of an object, or an element index of an array (from the end when negative), the last of equal keys. only: JOBJ or JARR when every step must be a key (-> text) or an index (-> integer), else 0. None when the path reaches nothing.

Effects: fail, alloc.

jsonPartText

gizlang
function jsonPartText(part: string): Option<string>

A JSON part as ->> and #>> give it: a string's characters, null as none, other parts as written.

Effects: fail, alloc.

jsonParts

gizlang
function jsonParts(text: string): Option<JsonParts>

The top-level parts of the JSON TEXT, or none when it is not JSON.

Effects: fail, alloc.

parsePath

gizlang
function parsePath(source: string): JsonPath throws DbError

A jsonpath text parsed: 42601 for its syntax, 22P02 when it is empty.

Effects: fail, alloc.

jsonpathInput

gizlang
function jsonpathInput(source: string): string throws DbError

jsonpath input as PostgreSQL stores and prints it.

Effects: fail, alloc.

select

gizlang
function select(path: JsonPath, target: JV, vars: JV, hasVars: bool, silent: bool, first: bool, tz: bool): Selection throws DbError

The items path selects in target, with vars when given (an object; without them each variable is null). An error ends the walk with the error unless silent hides it (a missing variable it does not). first: stop at the first item, as only whether one exists matters.

Effects: fail, alloc.

pathQuery

gizlang
function pathQuery(target: string, source: string, varsText: string, hasVars: bool, silent: bool, first: bool, tz: bool): Selection throws DbError

jsonb_path_query and its kin over texts: the target and vars jsonb, the path.

Effects: fail, alloc.

Constants

JNULL

gizlang
const JNULL: i64 = 0

JSON kind: null.

JBOOL

gizlang
const JBOOL: i64 = 1

JSON kind: a boolean.

JNUM

gizlang
const JNUM: i64 = 2

JSON kind: a number.

JSTR

gizlang
const JSTR: i64 = 3

JSON kind: a string.

JARR

gizlang
const JARR: i64 = 4

JSON kind: an array.

JOBJ

gizlang
const JOBJ: i64 = 5

JSON kind: an object.