The query language¶

A query is one JSON object, sent as POST /rel. Every page in this section covers one part of that object — there's no separate "read" and "write" grammar; the same tree does both (see Writing data back).

Examples throughout use the hotel-booking schema from Getting started: hotel.chains → hotel.properties → hotel.room_types → hotel.rooms, and hotel.guests → hotel.bookings → hotel.payments. Database reference has the full diagram if you want the whole shape at a glance before diving in. Query shape reference does the same for the query language itself — the whole thing in one page — before the rest of this section walks through it by example.

In this section¶

• Query shape reference — every field and every Expression form, in one place, each linked back to the page that explains it.
• Database reference — the hotel-booking schema every example on these pages queries against.
• Shaping a query — roots, schema resolution, aliases.
• Filtering with where — comparisons, boolean logic, between/in/any.
• Selecting fields — own/full and their variants, object literals, get/set/get-set.
• Joining and embedding relations — join/on, incoming vs. outgoing.
• Calling functions — function-rooted and function-embedded nodes.
• Computed fields — call, the Postgres functional-column convention.
• Aggregates — agg/aggregate.
• Operators reference — every operator, JSON/array access, casts.
• Ordering and pagination — order_by, limit/offset.
• Distinctness — distinct/distinct_on, and pairing it with order_by.
• Writing data back — write modes, on_conflict, writability.
• Batching queries in one request — several queries, one transaction.
• Querying with GET — the same read-only queries as a URL query string.
• Well-known queries — named, pre-parsed, typed queries.