Plaid Query Language

A query is a pattern you match against your data: you name the things you are looking for, say how they relate, and Plaid returns every combination that fits.

Disjunction (or) and negation (not) are written as explicit clauses, and the seq shorthand covers the common "this token, then that token" case. All of them are built from the same handful of basic clauses.

A query is a JSON object. The wire keys are below; the clients recase them from your language’s idiom (see Clients and casing).

A variable is a string beginning with ?: "?s1", "?token", "?head". The name is arbitrary; what matters is that the same name in two clauses refers to the same entity (that is the join). Every variable in find must be bound by some positive clause in where. Names beginning with ?__ are reserved for the engine; a find variable may not use one.

If some value, like the ID of a layer, is known before the query is executed, you may put it into the query as a literal, like the span layer ID below:

However, it’s often more convenient to use bindings instead, where a variable takes the value’s place, and the variable is separately bound in a "bindings" map:

This is a convenience for you: these two example queries are behaviorally identical, and under the hood, before the latter query is executed, it is transformed into the former query by having all bound variables substituted with their bound values.

A binding value is a scalar (string / number / boolean) or a non-empty list of scalars. A list in a value position matches any of them (see Value matching):

Bindings are strict. Every binding must be referenced, and a placeholder may only stand where a literal is allowed; using one where a variable is required (in find, as the entity slot of a clause, in order-by) is an error.

An entity clause is [kind, "?var", {constraints}]. The kind picks the entity type (and its table and access-control scope); the constraint map filters it.

All constraints are optional, but a layer-less entity is still confined to your readable projects. Two clauses on the same variable conjoin their constraints: splitting compatible constraints across clauses combines them, while contradictory ones (a span ?s with value NOUN in one clause and VERB in another) match nothing.

A ?variable followed by a dot path (?t.begin) reads one of that entity’s fields. The result is a scalar, usable in a predicate, in order-by, or in an aggregate. So to keep only the tokens that begin at or after offset 5:

Supported names, by type:

doc is the document id and id is the entity’s own id. metadata and config go deeper: the segment after them is a key, and you can keep descending into nested objects (?s.metadata.author.name, ?sl.config.editor.color).

layer (every annotation entity — span/token/relation/vocab) and source/target (a relation’s endpoint spans) are reference fields — opaque id columns, the dot-path spelling of the layer / source / target constraint slots. Like other ids they take only =, !=, and in (no ordering), and they compare to a variable or an id, never a name: ["=", "?s.layer", "?sl"] joins to a layer variable, and ["=", "?r.source", "?sp"] is the same as the source clause. A bare layer name on the right (["=", "?s.layer", "pos"]) is a 400 — match a layer by name with the layer constraint or a layer-variable clause instead.

The field name itself (begin, value, the metadata/config word) is part of the query language, so it is matched loosely: case and -/_ are ignored, and you may spell it in whatever idiom your client uses (?t.begin and ?t.Begin are the same). The keys after metadata/config, though, are your data: they are matched exactly, case-sensitive and byte for byte (?s.metadata.caseMarker is not ?s.metadata.casemarker), mirroring how metadata and config are stored. A key containing a literal . can’t be reached with a dot path. Use the metadata constraint for those.

A constraint slot can be filled in several ways. These forms apply wherever a constraint map appears, in entity clauses and in seq elements alike.

A relationship clause is [op, "?a", "?b"], a named edge between two variables. This is where the structure between entities comes from. Each operator fixes the entity kind of both operands, shown as (kind, kind) after the signature; a variable used at the wrong kind (a span where a token is required) is a 400. Only spans, tokens, relations, and vocab items take part in these clauses; documents and texts do not.

In the diagrams below, tokens are boxed words, a bracket marks the tokens a span covers, and an arrow is a relation edge.

Coverage. ["covers", "?span", "?token"] (span, token): the span includes that token.

Precedence. ["precedes", "?t1", "?t2"] (token, token): ?t2 is the immediate next token after ?t1.

["precedes*", "?t1", "?t2"] (token, token): ?t1 comes somewhere before ?t2, not just right before.

"Next" and "before" follow Plaid’s standard reading order (begin, precedence, end, id), the order tokens appear in as you read a document. Both are scoped to a single text and a single token layer: a word token never precedes a morpheme token, and neither relation reaches across texts.

Nesting. ["within", "?child", "?parent"] (token, token): the extent of ?child sits inside the extent of ?parent.

First token. ["first-in", "?token", "?container"] (token, token): ?token is within ?container and is the first token of its layer there.

Both compare tokens by their code-point offsets, so they work across layers: naming child and parent on different token layers (morpheme within word within sentence) is how you walk a hierarchy. Nesting is non-strict, so a child whose extent exactly fills its parent still counts, but a token is never within itself. first-in also requires that no token on the same layer as ?token in the container comes before it in that same reading order.

Overlap. ["overlaps", "?a", "?b"] (span, span): the two spans share at least one token.

Containment. ["contains", "?a", "?b"] (span, span): span ?a covers every token span ?b does.

Coextension. ["coextensive", "?a", "?b"] (span, span): the two spans cover exactly the same tokens.

All three compare spans by the set of tokens each covers, so a discontinuous span works too, and all three exclude a span from matching itself. That is why coextensive is useful: it finds two different spans over the same tokens (e.g. a POS span lined up with an NER span).

Source. ["source", "?relation", "?span"] (relation, span): the span at the relation’s source end.

Target. ["target", "?relation", "?span"] (relation, span): the span at the relation’s target end.

The two ends can be written inline on the relation clause or as separate edges; the two are equivalent:

Reachability. ["related*", "?a", "?b", {layer}] (span, span): ?b is reached from ?a by following one or more relation edges on the named layer.

The trailing map is required: it names the relation layer, and may add a value each edge must carry (a literal or a list of literals only; a regex or value variable there is a 400). It follows one or more hops, never zero, so ?a related* ?a matches only through a cycle. Every span reached along the path must itself sit in a span layer within your scope, so the search never crosses into a project you cannot read.

Vocab link. ["vocab-link", "?token", "?vocab"] (token, vocab): the token is linked to that vocab item.

A predicate compares two already-bound terms: [op, a, b] where op is one of =, !=, <, >, <=, >= and each term is a variable, a field path, or a literal.

Two more predicates work on a field path (or, for in, also a variable):

A seq clause walks one token layer; each element matches a token at the next position, and consecutive elements are adjacent by precedes. It is the readable form of a chain of covers + precedes.

Each element is [kind, {constraints}], optionally followed by "as", "?var" to capture it. A span element matches a token that the span covers; a token element matches the sequence token directly. An element’s constraint map accepts the same keys as the standalone clause of that kind (a span element takes value / doc / metadata, a token element value / begin / end / metadata). The seq config map takes layer (required) and an optional doc to pin the whole sequence to one document.

For "this OR that", use ["or", group, group, …] where each group is a list of clauses (all of which must hold together). The query matches if any group matches.

Surrounding clauses (the ones outside the or) apply to every branch. Rules:

For "one field is one of several values", prefer a value list ({"value": ["NOUN", "PROPN"]}), which is simpler and faster than separate or branches.

["not", clause, …] takes one or more clauses and matches when they have no joint match in your data.

What the not means depends on which variables it shares with the rest of the query:

The body may itself contain or, seq, or another not.

Wherever a clause takes a layer, a scalar reference is the layer’s ID (its UUID) — that is the only way to name a specific layer. There is no addressing by layer name or Project/Layer path: names are non-unique across a multi-tenant instance (two unrelated projects routinely share a layer name), so resolving one to a single layer is brittle, whereas an ID always identifies exactly one layer.

A non-ID reference (a name or path) is a 400. In practice this is no burden: anything that knows a layer’s name fetched it from the API and already holds its ID, so it just passes the ID. To select a layer by name, bind it with a layer variable and a *-layer clause (next section) — the match is then explicit, and you can see every layer it binds instead of a name silently resolving to one.

A query only ever sees data in projects you can read; access control is applied server-side from your authenticated identity and cannot be widened by the request. By default the scope is all your readable projects.

Narrow it with scope, by project ID (projects, like layers, are identified by id only — project names are non-unique):

The requested scope is intersected with what you can read, so you can only ever narrow, never widen. If that intersection is empty (you scoped only to projects you cannot read, or you can read none), the query is a 400, not an empty result. Vocab layers are global; a vocab item is visible when some project in your scope has been granted its layer.

Without order-by, rows come back in an unspecified order. order-by is a list of entries applied left to right; each entry is a dot path (["?t.begin"], or ["?t.begin", "desc"]) — or, equivalently, the longer [variable, attribute] / [variable, attribute, "desc"] form:

Set return to choose the result shape.

ids / entities queries are paginated by limit:

There is no cursor yet; to page a large result, add more selective clauses or query per project. count is bounded separately (above).

Every query is also bounded by a 30-second time limit; a query that exceeds it is aborted with HTTP 408. If you hit it, the pattern is too broad: add a more selective clause or tighten scope.

Two structural limits bound the pattern itself: an or / seq expansion of more than 128 branches is rejected, as is clause nesting deeper than 64.

Author errors return HTTP 400 with a message:

The clients raise this as an exception (PlaidAPIError in Python). Common causes: an unbound or duplicate find variable, an unknown clause or constraint key, a layer reference that does not resolve or is ambiguous, an unbounded seq quantifier, a value variable in find, an empty project scope, or an unsupported return. Passing an as-of / time-travel parameter is also a 400: queries run against current state only.

A query that runs too long returns 408. Internal failures return 500 with a generic message (details are logged server-side, not exposed).

The official clients pass your query body through their normal request/response pipeline, which converts naming conventions automatically:

The same query in JavaScript; only the language idiom differs:

These run against a Universal Dependencies project with a token hierarchy Sentences › Words › Morphemes, a UPOS span layer, and a Dependency Relations relation layer. Layers are addressed by path; swap in ids for real code.