Served words — Ablative docs

Reading records in

collection source

Read records from the named collection, including names that cannot be written bare.

name a nonempty collection name in double quotes

collection("patients")

match source

Match a labelled collection or a fixed chain of directed relations first or immediately after its collection.

nodes (binding:collection) or up to eight labelled nodes joined by directed relations
binding distinct names matching [a-z_][a-z0-9_]*
relation -[:kind]-> or <-[:kind]- at each of up to seven hops

match (p:patients)
match (c:patients)-[:admitted_to]->(w:wards)<-[:staffed_by]-(n:nurses)

{ } shape

Keep selected fields in record order; a first-stage shape reads collections in root order before worker Input.

fields bare names with nested selection sets
source one or several collection roots in a first-stage shape

collection("patients") | { name ward }
{ patients(ward: "3A") { name } wards { code } }

Searching

similar search

Search by vector similarity first after its source or later over the records that reached it.

field a top-level vector field with a leading dot
question double-quoted text or record("id")
measure cosine, l2 or dot

collection("patients") | similar(.embedding; record("p0"); cosine) | limit(10)
collection("notes") | similar(.embedding; "unsteady on feet overnight"; cosine) | limit(5)

record target

Use the stored vector of the named record as the similarity question.

id a record id in double quotes

cosine measure

Compare vectors by their cosine similarity.

l2 measure

Compare vectors by their Euclidean distance.

dot measure

Compare vectors by their dot product.

rg search

Keep whole records in order when their compact JSON or named field matches the pattern.

field optional top-level field with a leading dot
pattern a regular expression in double quotes
flags optional quoted -i, -s, -S, -w, -x, -F, -v and -U switches and their long forms; --no-ignore-case resets case sensitivity; -U dot matches newlines

patients | rg(.ward; "4b"; "-i -F")
patients | grep(.ward; "4B"; "-v")
collection("notes") | rg("fall risk"; "-i")

grep search

Alias of rg: keep whole records in order when their compact JSON or named field matches the pattern.

field optional top-level field with a leading dot
pattern a regular expression in double quotes
flags optional quoted -i, -s, -S, -w, -x, -F, -v and -U switches and their long forms; --no-ignore-case resets case sensitivity; -U dot matches newlines

Order and bound

limit bound

Stop the upstream after at most n records or values at this point in the pipeline.

n a whole number from 1 to 4294967295

collection("patients") | sort(.admitted; desc) | limit(2)

sort order

Order the whole upstream by a field before the quoted jq stage.

field a top-level field with a leading dot
direction optional desc after a semicolon

collection("patients") | sort(.admitted; desc)

desc order

Order the sort field from greatest to least instead of ascending order.

rerank order

Drain the bounded upstream, reorder by vector score, replace scores and count unscored records last; no continuation.

field a top-level vector field with a leading dot
question double-quoted text or record("id")
measure cosine, l2 or dot

collection("patients") | similar(.embedding; record("p0"); dot) | limit(20) | rerank(.embedding; record("p0"); dot) | limit(2)

window bound

Keep records by their revision append version, never by a time inside the record.

from an included unsigned version or quoted RFC 3339 instant
to an excluded bound of the same form, or $now

collection("patients") | window("1970-01-01T00:00:00Z"; $now)
collection("patients") | window(120; 240)

One answer

count count

Consume the whole upstream and answer its size as the last stage.

patients(ward: "4B") | count

group_by group

Drain records before jq into key, count and values groups in jq value order; missing fields group under null and no continuation is available.

field a top-level field with a leading dot

collection("patients") | group_by(.ward)

percentile aggregate

Drain records before jq into one nearest-rank JSON number; empty numeric input gives null, zero selects the minimum, non-numbers are counted as skipped, and no continuation is available.

field a top-level numeric field with a leading dot
percentile a number from 0 to 100 inclusive

collection("patients") | percentile(.admitted; 95)

Reserved

sort_by stage not yet not yet

Reserve an unquoted sort_by stage that is not available yet.

expression a sort key

Inside quoted jq

The 22 jq keywords served inside quotes

and: Join collection equalities or combine boolean expressions inside quoted jq.
as: Bind values to variables within a quoted jq expression.
def: Define a reusable filter inside quoted jq.
if: Start a conditional expression inside quoted jq.
then: Introduce a conditional branch inside quoted jq.
elif: Add another conditional test inside quoted jq.
else: Introduce the alternative branch inside quoted jq.
end: Close a conditional expression inside quoted jq.
or: Combine boolean expressions by disjunction inside quoted jq.
reduce: Fold generated values into an accumulator inside quoted jq.
foreach: Fold generated values while emitting intermediate results inside quoted jq.
in: Test whether the current key belongs to a container inside quoted jq.
try: Evaluate an expression with error handling inside quoted jq.
catch: Handle an error from a try expression inside quoted jq.
label: Name a control-flow boundary inside quoted jq.
break: Exit a named control-flow boundary inside quoted jq.
module: Declare module metadata inside a jq program.
import: Import a module under an alias inside a jq program.
include: Include a module directly inside a jq program.
true: Produce the boolean true inside quoted jq or a collection argument.
false: Produce the boolean false inside quoted jq or a collection argument.
null: Produce the null value inside quoted jq or a collection argument.