PassQL

PassQL is the textual query language of Synex Lab. You write it in the Lab workspace or submit its AST to the Lab API; it compiles to the same AST the visual Blocks builder produces and runs against the Lab read model (Postgres) — never against the passport store directly. That's why queries are metered as Postgres-only · 0 RCU.

A query is a pipeline: one from clause followed by stages, each introduced by a pipe (|).

from ontology:"Battery X" depth:C status:published
| where p"Weight" > 10 and (p"Material" in ["steel", "aluminium"] or p"Recycled" = true)
| where p"Dimensions".width <= 40
| group by p"Material"
| agg avg(p"Weight") as avg_weight, count() as n
| sort avg_weight desc
| limit 100

Syntax rules

• Keywords and property names are case-insensitive (WHERE ≡ where).
• Strings use double quotes with backslash escapes: "Fo\"o", "a\\b", \n, \t.
• # starts a comment that runs to the end of the line.
• Whitespace is insignificant — the multi-line layout is convention, not requirement.
• Errors carry the exact byte offset of the offending token; the editor underlines the span and lists what was expected.

from — the source

Selects which passports the pipeline reads. ontology: is required and repeatable (or comma-separated).

from ontology:"Battery X" ontology:"Chargers" depth:C,B status:published,draft

Only ontologies belonging to your team resolve; anything else fails at compile time.

Property references

Properties are the typed fields defined on your ontologies.

Each property type supports a specific set of operators:

| where — filtering

| where p"Weight" > 10 and not p"Origin" = "CN"
| where p"Material" in ["steel", "aluminium"] or p"Tags" contains "recycled"

Boolean logic

and, or, not, and parentheses, with the usual precedence (not before and before or). Multiple where stages are AND-ed together — split long filters across stages to keep them readable.

Operators

Values are numbers (10, -2.5), strings ("steel"), or booleans (true / false). Dates are written as strings ("2026-01-01") and parsed server-side.

JSON paths

Nested values (typically composites) are addressed with dot paths. Numeric comparisons only match values that are actually numeric in the JSON.

| where p"Dimensions".width <= 40

Publish-status conditions

Two status dimensions can be filtered anywhere a property condition can, and compose with and / or / not:

| where publish_status != "published"          # explicit status (null-aware)
| where resolved_status = "draft"              # effective/inherited status

resolved_status is computed live by walking the parent chain (≤25 hops), so it's never stale but heavier than other filters — prefer status: or publish_status when explicit status is what you mean.

| select — projection

Row queries project a mix of dimensions and properties. Without a select, the default projection is snowflake, friendly_id, tppmp.

| select friendly_id, tppmp, p"Weight", p"Tags"

Available dimensions: snowflake, friendly_id, tppmp, depth, ontology_id, publish_status, created_at, updated_at. Property values come back in their raw shape (numbers as numbers, tags as lists).

| group by + | agg — analytics

| group by p"Material"
| agg avg(p"Weight") as avg_weight, count() as n

• Group keys: groupable properties (short_text, long_text, number, boolean, date, measurement, composite) or dimensions.
• Aggregates: count(), sum(p"X"), avg(p"X"), min(p"X"), max(p"X"), distinct_count(p"X"). sum / avg / min / max need numeric-ish properties. Every aggregate needs an alias (as name).
• agg without group by computes whole-result aggregates (one row).
• Grouped results are capped at 1000 groups (the Chart tab, at 50) — beyond that you get a typed error asking you to narrow.

| sort and | limit

| sort avg_weight desc, n
| limit 200

• Row queries sort by one dimension or property (ties broken by snowflake) and paginate by keyset cursor — pages stay stable even as data changes. limit is the page size, 1–500 (default 100).
• Grouped queries sort by aggregate aliases or group keys (up to two terms).
• Direction is asc (default) or desc; empty values sort last.

| set — transforms (bulk writes)

Appending a set stage turns the query into a transform: from + where select the passports, set describes the writes. Transforms are the only Lab operation that writes data, so they require the admin/owner role, a mandatory preview, and the most recent one can be rolled back.

from ontology:"Battery X" | where p"Weight" exists
| set p"Weight" = p"Weight" * 2.20462,
      p"Origin" = concat("EU-", p"Plant Code"),
      publish_status = "draft"

Targets — writable property types (short_text, long_text, number, boolean, date, measurement) and publish_status (a quoted status, or null to clear it so the passport inherits again; setting a status pins it).

Expressions

Values are recomputed from live passport data when the transform runs — the read model only steers selection. A passport whose expression fails (non-numeric operand, division by zero, cast failure, type mismatch) is skipped and reported; the run always finishes. Up to 16 assignments per transform.

Limits

Results carry a watermark ("data as of …"): the read model syncs from the passport store within seconds of a write, and repeated identical queries are served from a cache that auto-invalidates on any team write. Full result sets are downloaded via exports (CSV/XLSX from the Run history).

Recipes

# Heaviest materials, published stock only
from ontology:"Products" status:published
| group by p"Material" | agg avg(p"Weight") as w, count() as n | sort w desc

# Everything that is NOT effectively published (incl. inherited/unset)
from ontology:"Products" | where resolved_status != "published"

# Data quality: missing critical fields
from ontology:"Products" | where p"Weight" is_empty or p"Datasheet" is_empty

# Bulk release a batch's series instances
from ontology:"Products" depth:B | where p"Batch No" = "B-2026-07"
| set publish_status = "published"

# Unit migration with a provenance note
from ontology:"Products" | where p"Weight (lbs)" exists
| set p"Weight" = p"Weight (lbs)" / 2.20462, p"Notes" = concat(p"Notes", " [kg-migrated]")

Ready to run these? Head to Synex Lab for the query, transform, and rollback endpoints.