First-class array values for pgwire-datahike.
Mirrors PostgreSQL's ArrayType (src/include/utils/array.h): a
value carrying element-type, the element vector (possibly nested
for multi-dim), per-dimension sizes, and per-dimension lower
bounds. Subscripting, slicing, membership, containment, concat,
PG text-format codec.
Design notes:
elem-type is a keyword matching our types/oid-* naming
(:int8, :text, :name, :bool, :float8, …) — not an OID.
Resolution to OID happens at the oid-infer / describeResult layer.elements is a Clojure vector. For 1-D arrays it's a flat
vector of element values (nil represents SQL NULL). For
multi-dim it's a nested vector — outermost level is the first
dimension, innermost is the last. Always a uniform shape; PG
rejects ragged arrays and so do we (the parser raises on a
dimension mismatch).dims is the vector of per-dimension sizes. nil is shorthand
for [(count elements)] — a 1-D array. For multi-dim,
(count dims) = ndim, (reduce * dims) = total leaf count.lbounds is the vector of per-dimension lower bounds. nil is
shorthand for [1, 1, …]. PG defaults to 1; non-1 lbounds come
from ARRAY[lo:hi]=… literals (rare). Preserved through
to-pg-text/from-pg-text round-trip when non-default.:__null__ sentinel inside
arrays. Arrays are values we own end-to-end, so element NULLs
are Clojure nil.nil (SQL NULL), NOT an error.
arr[0] and arr[-1] return nil for the default lbound=1.defrecord gives us structural equality/hash — important for
datahike/datalog round-trip (arrays flow through query results,
bind params, and DISTINCT/GROUP BY without special handling).Text codec follows PG (src/backend/utils/adt/arrayfuncs.c:
array_out / array_in):
{} for empty,; nested dimensions emit nested {…}"…" when element contains ,, ", \, {, }, or
whitespace, or is empty, or is the literal NULL (case-insensitive)\ and " with backslashNULL tokent/f (PG text format for BOOL)[lo1:hi1][lo2:hi2]…= prefixFirst-class array values for pgwire-datahike.
Mirrors PostgreSQL's `ArrayType` (src/include/utils/array.h): a
value carrying element-type, the element vector (possibly nested
for multi-dim), per-dimension sizes, and per-dimension lower
bounds. Subscripting, slicing, membership, containment, concat,
PG text-format codec.
Design notes:
- `elem-type` is a keyword matching our types/oid-* naming
(`:int8`, `:text`, `:name`, `:bool`, `:float8`, …) — not an OID.
Resolution to OID happens at the oid-infer / describeResult layer.
- `elements` is a Clojure vector. For 1-D arrays it's a flat
vector of element values (`nil` represents SQL NULL). For
multi-dim it's a nested vector — outermost level is the first
dimension, innermost is the last. Always a uniform shape; PG
rejects ragged arrays and so do we (the parser raises on a
dimension mismatch).
- `dims` is the vector of per-dimension sizes. `nil` is shorthand
for `[(count elements)]` — a 1-D array. For multi-dim,
`(count dims) = ndim`, `(reduce * dims) = total leaf count`.
- `lbounds` is the vector of per-dimension lower bounds. `nil` is
shorthand for `[1, 1, …]`. PG defaults to 1; non-1 lbounds come
from `ARRAY[lo:hi]=…` literals (rare). Preserved through
to-pg-text/from-pg-text round-trip when non-default.
- We deliberately do NOT use the `:__null__` sentinel inside
arrays. Arrays are values we own end-to-end, so element NULLs
are Clojure `nil`.
- Subscript semantics follow PG exactly: 1-indexed (offset by
lbound), out-of-range returns `nil` (SQL NULL), NOT an error.
`arr[0]` and `arr[-1]` return nil for the default lbound=1.
- `defrecord` gives us structural equality/hash — important for
datahike/datalog round-trip (arrays flow through query results,
bind params, and DISTINCT/GROUP BY without special handling).
Text codec follows PG (`src/backend/utils/adt/arrayfuncs.c`:
`array_out` / `array_in`):
- `{}` for empty
- Elements joined by `,`; nested dimensions emit nested `{…}`
- Quote `"…"` when element contains `,`, `"`, `\`, `{`, `}`, or
whitespace, or is empty, or is the literal `NULL` (case-insensitive)
- Inside quotes: escape `\` and `"` with backslash
- NULL elements emit unquoted `NULL` token
- Booleans as `t`/`f` (PG text format for BOOL)
- Non-default lbounds emit a `[lo1:hi1][lo2:hi2]…=` prefix(all-match? a pred)Predicate form: returns true if (pred leaf) returns truthy for
every leaf. Vacuously true for an empty array (PG semantics for
x = ALL(<empty>)).
Predicate form: returns true if (pred leaf) returns truthy for every leaf. Vacuously true for an empty array (PG semantics for `x = ALL(<empty>)`).
(any-match? a pred)Predicate form: returns true if (pred leaf) returns truthy for some leaf. Walks all dimensions.
Predicate form: returns true if (pred leaf) returns truthy for some leaf. Walks all dimensions.
(array elem-type elements)(array elem-type elements dims-or-lbound)(array elem-type elements dims lbounds)Construct a PgArray. Element-type is a keyword (:int8, :text,
:bool, …). Optional dims (vector of per-dim sizes) and lbounds
(vector of per-dim lower bounds, defaulting to 1 for each).
For 1-D arrays you can omit dims/lbounds — they're derived from
(count elements) and 1 respectively. For multi-dim, pass a
nested-vector elements and dims is computed automatically; or
pass dims explicitly when the elements form is something exotic.
Construct a PgArray. Element-type is a keyword (`:int8`, `:text`, `:bool`, …). Optional dims (vector of per-dim sizes) and lbounds (vector of per-dim lower bounds, defaulting to 1 for each). For 1-D arrays you can omit dims/lbounds — they're derived from `(count elements)` and `1` respectively. For multi-dim, pass a nested-vector `elements` and dims is computed automatically; or pass dims explicitly when the elements form is something exotic.
(array? v)True iff v is a PgArray instance.
True iff v is a PgArray instance.
(coerce-oid-elements a)Resolve every OID-alias array leaf to its numeric identity. A cast from a text ARRAY must run typinput just as an array text literal does.
Resolve every OID-alias array leaf to its numeric identity. A cast from a text ARRAY must run typinput just as an array text literal does.
(concat-arrs a b)PG a || b — full multi-dim semantics via cat-rejecting-mismatch.
Element-types must match; we leave compatibility checks to the
call-site (PG coerces via least common supertype).
PG `a || b` — full multi-dim semantics via `cat-rejecting-mismatch`. Element-types must match; we leave compatibility checks to the call-site (PG coerces via least common supertype).
(contains-arr? a b)PG a @> b: every leaf of b is present somewhere in a.
A NULL leaf of b makes the answer FALSE -- it is not "trivially
contained", and it does not even match a NULL in a:
ARRAY[4,NULL] <@ ARRAY[1,2,3,4,NULL] is false. Treating nil as
satisfied made arr <@ ARRAY[…] match rows PostgreSQL excludes.
Operates on flattened leaves -- PG ignores shape for @>.
PG `a @> b`: every leaf of b is present somewhere in a. A NULL leaf of b makes the answer FALSE -- it is not "trivially contained", and it does not even match a NULL in a: `ARRAY[4,NULL] <@ ARRAY[1,2,3,4,NULL]` is false. Treating nil as satisfied made `arr <@ ARRAY[…]` match rows PostgreSQL excludes. Operates on flattened leaves -- PG ignores shape for `@>`.
(element-at-indices a indices)PostgreSQL array element fetch for one complete subscript chain.
PostgreSQL does not expose a lower-rank row array through element syntax:
the number of supplied indices must equal the stored rank. A NULL index,
rank mismatch, empty array, or out-of-range index returns SQL NULL (nil).
PostgreSQL array element fetch for one complete subscript chain. PostgreSQL does not expose a lower-rank row array through element syntax: the number of supplied indices must equal the stored rank. A NULL index, rank mismatch, empty array, or out-of-range index returns SQL NULL (`nil`).
(element-type a)Element-type keyword (:text, :int8, etc.).
Element-type keyword (:text, :int8, etc.).
(flat-elements a)Walk a (possibly nested) elements vector to a flat seq of leaves —
used by member? / contains-arr? / overlap? and the binary codec
which encode element-by-element regardless of shape. Preserves nil
leaves so 3-valued logic works through them. Descends into nested
PgArray records as well as Clojure sequentials so an outer
PgArray whose :elements happen to hold inner PgArrays (the
common shape produced by expr.clj's ArrayConstructor build-fn for
ARRAY[ARRAY[…],…]) is walked correctly.
Walk a (possibly nested) elements vector to a flat seq of leaves — used by member? / contains-arr? / overlap? and the binary codec which encode element-by-element regardless of shape. Preserves nil leaves so 3-valued logic works through them. Descends into nested PgArray records as well as Clojure sequentials so an outer PgArray whose `:elements` happen to hold inner PgArrays (the common shape produced by expr.clj's ArrayConstructor build-fn for `ARRAY[ARRAY[…],…]`) is walked correctly.
(from-pg-text s elem-type)Parse PG array text format into a PgArray of the given element-type.
Inverse of to-pg-text. Handles:
{} — empty array{1,2,3} — flat 1-D{{1,2},{3,4}} — multi-dim (nested braces)[2:4]={a,b,c} — non-default lbound[1:2][1:2]={{1,0},{0,1}} — non-default multi-dim lbound,, ", \ escape sequencesNULL token → element nil
Raises on malformed input or ragged shape.Parse PG array text format into a PgArray of the given element-type.
Inverse of `to-pg-text`. Handles:
- `{}` — empty array
- `{1,2,3}` — flat 1-D
- `{{1,2},{3,4}}` — multi-dim (nested braces)
- `[2:4]={a,b,c}` — non-default lbound
- `[1:2][1:2]={{1,0},{0,1}}` — non-default multi-dim lbound
- quoted strings with `,`, `"`, `\` escape sequences
- unquoted `NULL` token → element nil
Raises on malformed input or ragged shape.(lbound a)(lbound a d)Lower bound for dimension d (1-indexed, default 1). PG: arrays
default to 1; explicit [lo:hi]= literals can shift this.
Lower bound for dimension `d` (1-indexed, default 1). PG: arrays default to 1; explicit `[lo:hi]=` literals can shift this.
(length a)Element count along the outermost (first) dimension. For 1-D arrays
that's the total leaf count. For multi-dim it's the size of dim 1.
Differs from PG's array_length — this returns 0 for an empty
array; call-sites that need PG's NULL-for-empty check explicitly.
Element count along the outermost (first) dimension. For 1-D arrays that's the total leaf count. For multi-dim it's the size of dim 1. Differs from PG's `array_length` — this returns 0 for an empty array; call-sites that need PG's NULL-for-empty check explicitly.
(length-d a d)Length along dimension d (1-indexed). PG's array_length(arr, d)
returns NULL when d is out of range — call-sites should check
(<= d (ndim a)) before relying on the result.
Length along dimension `d` (1-indexed). PG's `array_length(arr, d)` returns NULL when d is out of range — call-sites should check `(<= d (ndim a))` before relying on the result.
(match-shape a b)Predicate: does b have a shape that's compatible with being a
sub-element of a? PG accepts this when (rest dims-a) matches
dims-b exactly. Used by array_cat for the asymmetric N-D || (N-1)-D
and (N-1)-D || N-D cases (array_userfuncs.c:471–479).
Predicate: does `b` have a shape that's compatible with being a sub-element of `a`? PG accepts this when `(rest dims-a)` matches `dims-b` exactly. Used by array_cat for the asymmetric N-D || (N-1)-D and (N-1)-D || N-D cases (`array_userfuncs.c:471–479`).
(member? a x)PG x = ANY(arr) semantics with 3-valued logic. Operates on
flattened leaves so multi-dim arrays match anywhere:
ARRAY[[1,2],[3,4]] = ANY(…) is true if any leaf equals x.
PG `x = ANY(arr)` semantics with 3-valued logic. Operates on flattened leaves so multi-dim arrays match anywhere: ARRAY[[1,2],[3,4]] = ANY(…) is true if any leaf equals x. - returns true if any leaf = x - returns false if no leaf = x AND no NULL leaves - returns nil (UNKNOWN) if x isn't matched but NULL leaves exist (a NULL leaf could match any x)
(multidim? a)True if the array has more than one dimension. Several PG functions (array_append, array_prepend, array_position, array_remove) explicitly reject multi-dim arrays; callers raise the matching feature_not_supported error in that case.
True if the array has more than one dimension. Several PG functions (array_append, array_prepend, array_position, array_remove) explicitly reject multi-dim arrays; callers raise the matching feature_not_supported error in that case.
(ndim a)Number of dimensions. 1 for the 1-D default; more for nested arrays.
Number of dimensions. 1 for the 1-D default; more for nested arrays.
(overlap? a b)PG a && b: any leaf of a is a leaf of b (NULLs ignored).
Operates on flattened leaves.
PG `a && b`: any leaf of a is a leaf of b (NULLs ignored). Operates on flattened leaves.
(render-stored-array value oid)Render canonical storage in the reader's session. Older non-ISO temporal text has no writer DateStyle metadata, so preserve its wire spelling.
Render canonical storage in the reader's session. Older non-ISO temporal text has no writer DateStyle metadata, so preserve its wire spelling.
(replace-leaves a f)Walk every leaf of a's nested elements, applying f to each
leaf value. Returns a new PgArray with the same shape, dims, and
lbounds. Used by array_replace, which PG applies to all leaves
regardless of dimensionality (arrayfuncs.c:6662). Descends into
nested PgArrays as well as Clojure sequentials.
Walk every leaf of `a`'s nested elements, applying `f` to each leaf value. Returns a new PgArray with the same shape, dims, and lbounds. Used by `array_replace`, which PG applies to all leaves regardless of dimensionality (`arrayfuncs.c:6662`). Descends into nested PgArrays as well as Clojure sequentials.
(slice a lo hi)PG array slice: arr[lo:hi]. 1-indexed, inclusive bounds, clamped
to [lbound, lbound+length-1]. Returns a PgArray (possibly empty)
preserving elem-type. nil bounds → PG default (lbound / lbound+len-1).
Slicing operates on the outermost dimension; remaining dimensions select their full range. Result lower bounds reset to 1, as PostgreSQL does.
PG array slice: `arr[lo:hi]`. 1-indexed, inclusive bounds, clamped to `[lbound, lbound+length-1]`. Returns a PgArray (possibly empty) preserving elem-type. nil bounds → PG default (lbound / lbound+len-1). Slicing operates on the outermost dimension; remaining dimensions select their full range. Result lower bounds reset to 1, as PostgreSQL does.
(slice-at a specs)PostgreSQL array slice fetch over a normalized dimension vector.
Each spec has :lower/:upper plus :lower-provided? and
:upper-provided?. Missing dimensions select their complete range. Bounds
clamp to the stored array, and every nonempty slice resets result lower
bounds to 1. A supplied SQL NULL bound returns nil; no overlap, an empty
source, or too many dimensions returns PostgreSQL's zero-dimensional {}.
PostgreSQL array slice fetch over a normalized dimension vector.
Each spec has `:lower`/`:upper` plus `:lower-provided?` and
`:upper-provided?`. Missing dimensions select their complete range. Bounds
clamp to the stored array, and every nonempty slice resets result lower
bounds to 1. A supplied SQL NULL bound returns nil; no overlap, an empty
source, or too many dimensions returns PostgreSQL's zero-dimensional `{}`.(subscript a n)Take one structural dimension from a. This remains useful to array
internals, but is not PostgreSQL's complete SQL element-read operation:
SQL a[i] returns NULL when a has more than one dimension. Use
element-at-indices at the SQL boundary.
Take one structural dimension from `a`. This remains useful to array internals, but is not PostgreSQL's complete SQL element-read operation: SQL `a[i]` returns NULL when `a` has more than one dimension. Use `element-at-indices` at the SQL boundary.
(to-pg-text a)(to-pg-text a array-oid)Render a PgArray to PG's canonical text format: {e1,e2,...} for
1-D, nested {{…},{…}} for multi-dim. Emits [lo1:hi1][lo2:hi2]…=
prefix when any lower bound != 1.
Used by the wire layer's value->string for any PgArray value.
Render a PgArray to PG's canonical text format: `{e1,e2,...}` for
1-D, nested `{{…},{…}}` for multi-dim. Emits `[lo1:hi1][lo2:hi2]…=`
prefix when any lower bound != 1.
Used by the wire layer's value->string for any PgArray value.(to-storage-text a)Persist array text independently of the session's date style, time zone, and search path. Store OID references by numeric identity.
Persist array text independently of the session's date style, time zone, and search path. Store OID references by numeric identity.
(ubound a d)Upper bound for dimension d (1-indexed). (lbound a d) + (length-d a d) - 1, or nil if d out of range.
Upper bound for dimension `d` (1-indexed). `(lbound a d) + (length-d a d) - 1`, or nil if d out of range.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |