|
Note
|
This is the reference for Plaid’s query language. For an introduction by example, see the Querying chapter of the manual. |
A query searches Plaid data across every project you can read, in one request.
You describe a pattern, the entities you are looking for and how they relate, and Plaid returns every match.
Queries are sent as POST /api/v1/query, or with the query() method of the official clients.
The examples here use the Python client.
1. Mental model
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.
-
You declare variables (
?s,?t, …) for the entities you want. -
You write a list of clauses. Each clause either describes one entity (a span on the
poslayer with valueNOUN, call it?s) or relates two of them (?s covers ?t). -
All clauses must hold at once. Using a variable in two clauses joins them, so the name stands for the same thing in both.
-
You ask for some of those variables back, as ids, full entities, or a count.
Alternatives (or) and negation (not) are clauses of their own, and seq is a shorthand for "this token, then that token".
from plaid_client import PlaidClient
client = PlaidClient.login(
"http://localhost:8080", "you@example.com", "password")
# every NOUN immediately followed by a VERB, across all readable projects
result = client.query({
"find": ["?s1", "?s2"],
"where": [
["span", "?s1", {"layer": "pos", "value": "NOUN"}],
["span", "?s2", {"layer": "pos", "value": "VERB"}],
["covers", "?s1", "?t1"], ["covers", "?s2", "?t2"],
["precedes", "?t1", "?t2"],
],
})
# -> {"return": "ids", "columns": ["s1", "s2"],
# "results": [["<noun-id>", "<verb-id>"], ...],
# "count": N, "truncated": false}
|
Note
|
To keep them readable, the examples write a layer as a name such as pos or UPOS.
A real query names a layer by its id (see Layer addressing), so read "layer": "pos" as "the id of the layer called pos".
|
2. Request shape
A query is a JSON object with these keys:
| Key | Required | Meaning |
|---|---|---|
|
usually |
Non-empty list of variables to return, in column order. Omitted only with an aggregate |
|
yes |
Non-empty list of clauses (the pattern). |
|
no |
Restrict to specific projects, by id (see Scope and access control). Default: every project you can read. |
|
no |
Max rows. Default 1000, hard cap 100,000 (see Result-size guardrails). |
|
no |
Sort the rows (see Ordering). Without it, row order is unspecified. |
|
no |
|
|
no |
Substitute |
The clients accept these keys in your language’s own casing (see Clients and casing).
Any other key is refused with a 400 that names it, so a misspelled limit is never ignored.
3. Variables
A variable is a string beginning with ?, such as "?s1" or "?head".
The name is up to you, and the same name in two clauses refers to the same entity.
A variable in find must begin with an ASCII letter after the ? and hold only ASCII letters, digits, or -.
Every variable in find must appear in some clause of where, and names beginning with ?_ are reserved.
4. Bindings
If a value such as a layer id is known before the query runs, you can write it into the query directly:
{
"find": ["?s"],
"where": [["span", "?s", {"layer": "0194e8a1-…-uuid", "value": "NOUN"}]],
}
It is often more convenient to put a placeholder in its place and supply the value separately in bindings.
The two queries mean exactly the same thing:
{
"find": ["?s"],
"where": [["span", "?s", {"layer": "?lyr", "value": "?tag"}]],
"bindings": {"?lyr": "0194e8a1-…-uuid", "?tag": "NOUN"}
}
A binding is a string, number or boolean, or a non-empty list of them.
A list in a value position matches any of its members:
# with bindings {"?tags": ["NOUN", "PROPN"]}
["span", "?s", {"layer": "UPOS", "value": "?tags"}]
Every binding must be used, and a placeholder may stand only where a literal could.
Using one where a variable is required, such as in find or order-by, is an error.
5. Entity clauses
An entity clause is [kind, "?var", {constraints}].
The kind says what sort of entity it is, and the constraint map filters it.
| Kind | Constraints | Notes |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
A vocabulary entry. |
|
|
A document. |
|
|
A document’s text. |
|
|
A vocab link, which ties one or more tokens to a vocab item. |
All constraints are optional.
Two clauses on the same variable combine their constraints, so contradictory ones (NOUN in one clause and VERB in the other) match nothing.
["span", "?s", {"layer": "UPOS", "value": "NOUN"}] # a NOUN annotation
["token", "?t", {"layer": "Words"}] # any word token
["token", "?t", {"layer": "Words", "begin": 0}] # a word starting at 0
["relation", "?r", {"layer": "deprel", "value": "nsubj"}] # an nsubj edge
["vocab", "?v", {"form": "Kemal"}] # the lexeme "Kemal"
6. Field access (dot paths)
A variable followed by a dot path, such as ?t.begin, reads one field of that entity.
You can use it in a predicate, in order-by, or in an aggregate.
For example, to keep only the tokens that begin at or after offset 5:
["token", "?t", {"layer": "Words"}],
[">=", "?t.begin", 5]
Each kind has these fields:
| Kind | Readable fields |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
layer variable |
|
doc is the document’s id and id is the entity’s own.
After metadata or config comes a key, and you can keep descending into nested objects (?s.metadata.author.name).
layer, source, target and item hold ids, so they compare only with =, != and in, and only to a variable or an id.
["=", "?s.layer", "?sl"] joins a span to a layer variable, while a layer name in that position is an error.
Field names such as begin are matched loosely, ignoring case and - or _, so you can spell them in your client’s style.
The keys after metadata or config are your own data, so they are matched exactly, case included.
A dot path reads object keys only, so a key that contains a . needs the metadata constraint instead.
7. Constraints
A constraint can be written in several ways, which work the same in entity clauses and in seq elements.
7.1. Value matching
| Form | Meaning | Allowed on |
|---|---|---|
Literal |
exact equality |
any key |
List |
any of these |
|
Regex |
pattern match (see Regular expressions) |
|
Variable |
bind the value instead of filtering it (see Value variables) |
|
layer takes none of these forms.
It must be a single layer id or a layer variable (see Layer addressing).
7.2. Regular expressions
A regex is written {"regex": "<pattern>"}, optionally with "flags": "i" for a case-insensitive match.
Patterns use Java’s regular expression syntax, and a pattern matches anywhere in a value unless you anchor it with ^ or $.
A malformed pattern, or one longer than 4,096 characters, is an error.
["span", "?s", {"layer": "Lemma", "value": {"regex": "^walk"}}]
["vocab", "?v", {"form": {"regex": "ция$", "flags": "i"}}]
Character classes cover every script.
\w matches letters, marks and digits in any script, \d any decimal digit, and \s any white space, so ^\w+$ matches الكتاب and \d matches ٣.
To name a category or a script, use \p{L} for any letter or \p{IsArabic} for Arabic.
Text is compared as a reader would see it.
A pattern or an equality matches text that differs only in how its characters are composed, so pʰá typed with a precomposed á finds it stored as a plus an accent.
Two marks typed in either order count as the same text too.
A pattern that names a combining mark also finds it inside a precomposed letter, so a pattern of only the acute accent (U+0301) finds the accent in á.
A pattern names a mark when it holds one, writes one as an escape (\x{301}, \u0301, \N{COMBINING ACUTE ACCENT}) or a class range between two, or asks for the mark category (\p{M}, \p{Mn}, \p{Mc}, \p{Me}) on its own, in a class of nothing but marks, or as [^\P{M}].
A pattern that names none never looks inside a letter, so a does not find á, and neither does a., a\w or a[\p{L}\p{M}].
A precomposed letter in a class stays that letter when the pattern looks inside letters: [á\x{301}] finds á and the accent in ấ, never a plain a, and [^á\x{301}] finds the a of ma but not the one in á.
7.3. Value variables
Write {"var": "?v"} where a literal would go, and the clause binds that value instead of filtering it.
The same value variable in two clauses requires the two entities to share a value, without your knowing what it is:
# two DISTINCT spans on the same layer with the same value
["span", "?a", {"layer": "?L", "value": {"var": "?v"}}],
["span", "?b", {"layer": "?L", "value": {"var": "?v"}}],
["!=", "?a", "?b"]
A plain string is always a literal, so a value such as "?x" is never taken for a variable.
A value variable holds a value, not an entity, so it cannot appear in find.
7.4. Comparing JSON types
Values and metadata are stored as JSON, so each has a type, and matching respects it.
{"value": 3} matches the number 3 and not the string "3", and a string never equals a number.
A constraint map matches the stored value exactly, so {"value": 3} does not match a number stored as 3.0.
A predicate compares numbers as numbers, so ["=", "?s.value", 3] matches both.
Use a predicate when you compare numeric values (see Predicate clauses).
A boolean reads as the number 1 or 0.
["=", "?s.value", true] matches a stored true or 1, but "true" as a string matches nothing.
A boolean in an aggregate’s value or a group key reads as 1 or 0 too, never as true or false.
7.5. Metadata
Any entity can carry metadata, an arbitrary JSON object, and the metadata constraint matches some of its keys:
["span", "?s", {"layer": "POS", "metadata": {"translation": "dog"}}]
["span", "?s", {"layer": "POS", "metadata": {"sense": {"regex": "^[0-9]+$"}}}]
["document", "?d", {"metadata": {"genre": ["news", "opinion"]}}]
["span", "?s", {"layer": "Gloss", "metadata": {"gloss": {"literal": "?PL"}}}]
A plain value matches by equality, type included.
A list means "any of these", so the genre example matches a genre of "news" or "opinion", not a genre that is the array ["news", "opinion"].
A regex runs against the value’s text.
Metadata is matched, never bound, so a string beginning with ? is an error there.
To match a value that really begins with ?, such as the gloss ?PL, wrap it as {"literal": "?PL"}.
Matching a value that is itself an array or object is not well supported.
A regex sees such a value as its compact JSON text, so {"regex": "\"news\""} finds a genre array that includes "news".
This is brittle, and restructuring the metadata is usually the better fix.
Keys are matched exactly, case included. Metadata is best used to narrow a search that other constraints have already narrowed, not as the main thing you search by.
7.6. Filtering by document
An annotation’s doc is its document’s id.
It takes an id, a list of ids, or a value variable.
To select by a document’s name or other properties, bind doc to a value variable and equate it with a document clause:
["span", "?s", {"layer": "POS", "doc": {"var": "?dv"}}],
["document", "?d", {"name": {"regex": "^interview-"}}],
["=", "?dv", "?d"] # the span's document is this document
Two annotations sharing one doc value variable are in the same document.
8. Relationship clauses
A relationship clause is [op, "?a", "?b"], a named relation between two variables, and it is where the structure of a query comes from.
Each operator takes two particular kinds of entity, shown after it below, and a variable of the wrong kind is an error.
In the diagrams, tokens are boxed words, a bracket marks the tokens a span covers, and an arrow is a relation.
Coverage. ["covers", "?span", "?token"] (span, token): the span includes that token.
┌─ ?s ─┐
[ Fido ] [ barks ]
?t
Precedence. ["precedes", "?t1", "?t2"] (token, token): ?t2 is the next token after ?t1.
[ dogs ][ run ]
?t1 ?t2
└──▶──┘
["precedes*", "?t1", "?t2"] (token, token): ?t1 comes somewhere before ?t2, not just right before.
[ the ][ big ][ dog ]
?t1 ?t2
└──── … ───▶┘
Both follow the order in which tokens are read in a document. They relate tokens of one layer in one text only, so a word never precedes a morpheme.
Nesting. ["within", "?child", "?parent"] (token, token): the extent of ?child lies inside the extent of ?parent.
word [ replayed ]
morphemes [re][play][ed]
?child
First token. ["first-in", "?token", "?container"] (token, token): ?token is within ?container and is the first token of its layer there.
sentence [ the dog runs ]
words [the][dog][runs]
?token
These two compare tokens by their offsets, so they work across layers, and they are how you walk a hierarchy of morphemes within words within sentences. A child that exactly fills its parent counts as within it, but a token is never within itself.
Overlap. ["overlaps", "?a", "?b"] (span, span): the two spans share at least one token.
[a][b][c][d] ?x └───────┘ ?y └────┘
Containment. ["contains", "?a", "?b"] (span, span): span ?a covers every token span ?b does.
[a][b][c] ?a └───────┘ ?b └─┘
Coextension. ["coextensive", "?a", "?b"] (span, span): the two spans cover exactly the same tokens.
[a][b][c] ?x └───────┘ ?y └───────┘
These three compare spans by the tokens they cover, so they work for discontinuous spans too.
None of them matches a span with itself, which makes coextensive useful for finding two different spans over the same tokens, such as a POS span and an NER span.
Source. ["source", "?relation", "?span"] (relation, span): the span at the relation’s source end.
?relation
[ Fido ] ──────▶ [ barks ]
?span
Target. ["target", "?relation", "?span"] (relation, span): the span at the relation’s target end.
?relation
[ Fido ] ──────▶ [ barks ]
?span
A relation’s ends can also be written inside the relation clause, which means the same thing:
["relation", "?r",
{"layer": "deprel", "value": "nsubj", "source": "?h", "target": "?d"}]
# is the same as:
["relation", "?r", {"layer": "deprel", "value": "nsubj"}],
["source", "?r", "?h"],
["target", "?r", "?d"]
Reachability. ["related*", "?a", "?b", {layer}] (span, span): ?b is reached from ?a by following one or more relations of the named layer.
[x] ──▶ [y] ──▶ [z] ?a ?b
The map at the end is required and names the relation layer.
It may also give a value, or a list of values, that every step must carry.
At least one step is taken, so ?a related* ?a matches only through a cycle.
# every node in ?head's dependency subtree, at any depth
["related*", "?head", "?node", {"layer": "dep"}]
Vocab link. ["vocab-link", "?token", "?vocab"] (token, vocab): the token is linked to that vocab item.
[ Fido ] ──▶ vocab { form: "Fido" }
?token ?v
Link entity. When the link itself matters, such as whether anyone confirmed it or how many tokens it covers, bind it as a link entity.
["link-token", "?link", "?token"] (link, token) and ["link-item", "?link", "?vocab"] (link, vocab) then reach its tokens and its entry.
# machine-made links nobody has confirmed, and the words they sit on
["link", "?l", {"metadata": {"prov": "inferred"}}],
["not", ["link", "?l", {"metadata": {"provConfirmed": True}}]],
["link-token", "?l", "?t"]
# every link to one lexicon entry, however many tokens each covers
["vocab", "?v", {"form": "kick the bucket"}], ["link-item", "?l", "?v"]
9. Predicate clauses
A predicate compares two terms: [op, a, b], where op is one of =, !=, <, >, <= or >=.
Each term is a variable, a field path, or a literal.
["!=", "?s1", "?s2"] # two DIFFERENT spans (compares entity ids)
["=", "?v1", "?v2"] # two value variables that must be equal
["<", "?n", 5] # a value variable bound to begin, vs a literal
["=", "?s.value", "NOUN"] # a field path vs a literal
["=", "?s.metadata.gloss", {"literal": "?PL"}] # a literal that begins with ?
Entity variables compare by id, so they take only = and !=.
That is how you ask for two distinct matches, or keep an entity from matching itself.
Value variables and literals take all six operators.
A predicate only filters, so its variables must be bound by other clauses.
A term beginning with ? is a variable, and a literal that begins with ? is wrapped as {"literal": "?PL"}.
Predicates may not appear inside not.
Two more predicates work on a field path:
["~", "?s.value", "^N"] # regex match (bare pattern)
["~", "?s.value", {"regex": "^n", "flags": "i"}] # …with flags
["in", "?s.value", ["NOUN", "PROPN"]] # membership / alternation
~ matches a text field against a regular expression, given as a bare pattern or as a {"regex": …} spec.
in keeps rows whose term equals one of a non-empty list of literals.
9.1. Constraints, two ways
Most filters can be written either in a constraint map or as a predicate over a field path, with the same result. The constraint map is more compact, while predicates can compare fields of different entities. Use whichever reads better.
| Constraint map | Equivalent predicate form |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The two forms differ only for numeric values, as described under Comparing JSON types.
10. Sequences (seq)
A seq clause walks one token layer, matching each of its elements to the next token in turn.
It is a readable way of writing a chain of covers and precedes.
# a determiner immediately followed by a noun, over the Words layer
["seq", {"layer": "Words"},
["span", {"layer": "UPOS", "value": "DET"}, "as", "?d"],
["span", {"layer": "UPOS", "value": "NOUN"}, "as", "?n"]]
seq over Words: DET then NOUN
Words [ the ][ dog ]
└───▶───┘
UPOS [DET ] [NOUN ]
?d ?n
Each element is [kind, {constraints}], optionally followed by "as", "?var" to name it.
A span element matches a token that such a span covers, and a token element matches the token itself.
The first map of the seq names the token layer to walk, and may also pin the sequence to one document with doc.
10.1. Quantifiers
Wrap an element to repeat it:
| Form | Meaning |
|---|---|
|
0 or 1 |
|
between |
# DET, optional ADJ, NOUN
["seq", {"layer": "Words"},
["span", {"layer": "UPOS", "value": "DET"}, "as", "?d"],
["?", ["span", {"layer": "UPOS", "value": "ADJ"}]],
["span", {"layer": "UPOS", "value": "NOUN"}, "as", "?n"]]
DET ( ADJ )? NOUN ( )? matches ADJ 0 or 1 times
?d ?n
matches the dog (DET NOUN)
the big dog (DET ADJ NOUN)
A repeated element cannot be named with "as".
There is no unbounded * or +, so use rep with an upper bound.
11. Disjunction (or)
For "this or that", write ["or", group, group, …], where each group is a list of clauses that must hold together.
The query matches if any group matches.
# a token tagged NOUN or VERB
["or", [["span", "?s", {"layer": "UPOS", "value": "NOUN"}]],
[["span", "?s", {"layer": "UPOS", "value": "VERB"}]]]
?s is NOUN or VERB:
┌─ NOUN
?s ──┤
└─ VERB
An or needs at least two groups, and every find variable must be bound in each of them.
The clauses outside the or apply to every group, and a row that matches two groups appears once.
For one field taking one of several values, a list such as {"value": ["NOUN", "PROPN"]} is simpler and faster.
12. Negation (not)
["not", clause, …] takes one or more clauses and matches when they have no match together.
# words with no NOUN annotation on them
["token", "?t", {"layer": "Words"}],
["not", ["covers", "?s", "?t"],
["span", "?s", {"layer": "UPOS", "value": "NOUN"}]]
words with no covering NOUN span:
[ runs ] ✓ kept: no NOUN span covers it
?t
┌NOUN┐
[ dog ] ✗ dropped: a NOUN span covers it
?t
A variable that is also used outside the not keeps its value there, so above, the not asks about one particular ?t.
A variable used only inside the not means "there is no such thing", so ?s reads as "there is no NOUN span covering ?t`".
Such a variable cannot be in `find.
13. Layer addressing
A layer is named by its id.
Layer names are not unique, since two unrelated projects often share one, so a name or a path in place of an id is an error.
A program that knows a layer’s name got it from the API, along with its id.
["span", "?s", {"layer": "98ef7a32-...-1327101afee3"}] # by id
13.1. Layer variables
The layer slot can also hold a variable, such as "?sl".
Two entities sharing a layer variable must be on the same layer, and putting the variable in find returns the layer’s id:
# a NOUN and a VERB span on the SAME layer, whichever it is
["span", "?a", {"layer": "?sl", "value": "NOUN"}],
["span", "?b", {"layer": "?sl", "value": "VERB"}]
To select layers by name, constrain a layer variable with a layer clause. It matches every layer of that name in your scope, across projects:
# every NOUN span on a layer named "pos", in ALL readable projects
["span", "?s", {"layer": "?sl", "value": "NOUN"}],
["span-layer", "?sl", {"name": "pos"}]
The layer clauses are span-layer, token-layer, relation-layer, vocab-layer and text-layer, and each is constrained by name.
13.2. Layer structure
A layer clause can also name the layer’s parent layer, by a variable or an id:
| Layer clause | Structural slots |
|---|---|
|
|
|
|
|
|
Chaining these through shared variables filters an entity by any layer above it:
# a span whose span layer's token layer is under a text layer "Transcription"
["span", "?s", {"layer": "?sl"}],
["span-layer", "?sl", {"token-layer": "?tl"}],
["token-layer", "?tl", {"text-layer": "?txtl"}],
["text-layer", "?txtl", {"name": "Transcription"}]
Nested token layers, such as words under sentences, are related with parent-token-layer:
# the token layer named "words" whose parent layer is named "sentences"
["token-layer", "?w", {"parent-token-layer": "?s", "name": "words"}],
["token-layer", "?s", {"name": "sentences"}]
14. Scope and access control
A query sees only projects you can read, and nothing in the request can widen that.
By default it searches all of them.
To narrow it, give scope a list of project ids:
"scope": {"project_ids": ["<uuid>", "<uuid>"]}
If none of the projects in scope is one you can read, the query is an error rather than an empty result.
A vocabulary’s entries are visible when a project in your scope uses that vocabulary.
15. Ordering
Without order-by, rows come back in no particular order.
order-by is a list of fields to sort by, in turn, each a dot path optionally followed by "desc":
# NOUNs, sorted by document then by position in the text
client.query({
"find": ["?t"],
"where": [["token", "?t", {"layer": "Words"}],
["span", "?s", {"layer": "POS", "value": "NOUN"}],
["covers", "?s", "?t"]],
"order_by": [["?t.doc"], ["?t.begin"]],
})
You can sort only by a variable you find, but by any of its fields, metadata included.
Missing values sort last in either direction.
Ordering cannot be combined with an aggregate return.
16. Return shapes
Set return to choose the shape of the result.
16.1. IDs
This is the default.
results is a list of rows, each holding one id per find variable, and columns gives the variable names.
{"return": "ids",
"columns": ["s1", "s2"],
"results": [["<id>", "<id>"], ...],
"count": 12,
"truncated": false}
16.2. Entities
The same, but each cell is the full entity, in the shape its GET endpoint returns.
A layer variable comes back as {"id": …}.
r = client.query({..., "return": "entities"})
r["results"][0][0]
# -> {"id": "...", "layer": "...", "value": "NOUN", "tokens": ["..."], ...}
16.3. Count
The number of distinct matches, counted up to 100,000.
A larger result reports count: 100000, truncated: true.
{"return": "count", "count": 38, "truncated": false}
16.4. Aggregates
return can also be an aggregate spec, which groups the matches by some variables and summarizes each group:
client.query({
"where": [["token", "?t", {"layer": "Words",
"doc": {"var": "?d"},
"begin": {"var": "?b"}}]],
"return": {"group": ["?d"],
"aggregates": [["count"], ["min", "?b"],
["max", "?b"], ["avg", "?b"]]},
})
# -> {"return": "aggregate",
# "columns": ["d", "count", "min_b", "max_b", "avg_b"],
# "results": [["<doc1>", 137, 0, 980, 412.6], ...],
# "count": 12, "truncated": false} # count = number of group rows
The aggregates are count, and sum, avg, min and max over a value variable or field path.
"group": [] gives one row for everything.
find and order-by are not used with an aggregate.
Be careful what else the pattern binds.
Each match is counted once, so adding ["covers", "?s", "?t"] counts a span once per token it covers, which inflates count, sum and avg.
Keep the pattern to the entity you are measuring and the filters on it.
17. Result-size guardrails
A query returns at most 1000 rows unless you set limit, which goes up to 100,000.
truncated: true means there may be more.
There is no paging, so to see more of a large result, narrow the pattern or query one project at a time.
Every query has 30 seconds, after which it is stopped with HTTP 408.
A query that takes that long is too broad, so add a more selective clause or narrow scope.
A count or aggregate may also be refused with 503 when the server is busy with others.
18. Errors
A mistake in a query is answered with HTTP 400 and a message:
{"error": "No span layer with id \"0194e8a1-…\" is visible in the queried project scope"}
The clients raise it as an exception (PlaidAPIError in Python).
Common causes are a find variable no clause binds, an unknown clause or key, a layer reference that is not an id, or a value variable in find.
Queries always read current data, so a time-travel parameter is an error too.
19. Clients and casing
The clients convert the query’s keys to and from your language’s casing, so Python’s order_by and JavaScript’s orderBy both work.
Clause names, variables and values are passed through as written, so "span", "?s1" and "NOUN" are the same in every language.
Entities in the result come back in your language’s casing, like any other read.
The same query in JavaScript:
const result = await client.query({
find: ['?d', '?n'],
where: [
['seq', { layer: 'Words' },
['span', { layer: 'UPOS', value: 'DET' }, 'as', '?d'],
['?', ['span', { layer: 'UPOS', value: 'ADJ' }]],
['span', { layer: 'UPOS', value: 'NOUN' }, 'as', '?n']],
],
scope: { projectIds: ['<uuid>'] }, // -> project-ids on the wire
return: 'entities',
limit: 20,
});
// result.results[0][0] -> { id: '...', value: 'DET', tokens: ['...'] }
20. Worked examples
These run against a Universal Dependencies project with the token layers Sentences › Words › Morphemes, a UPOS span layer, and a Dependency Relations relation layer.
Unlike the short examples above, they carry real layer ids, which you can read from client.projects.get(project_id).
PROJECT = "5b7ce985-9f11-4f2e-a1c0-6d1186cbd822"
SENTENCES = "0194e8a1-2c77-7d6b-9e30-4b1a5f0c8e11" # token layer
MORPHEMES = "0194e8a1-2c77-7d6b-9e30-4b1a5f0c8e13" # token layer
UPOS = "0194e8a1-2c77-7d6b-9e30-4b1a5f0c8e21" # span layer
DEPRELS = "0194e8a1-2c77-7d6b-9e30-4b1a5f0c8e31" # relation layer
# how many NOUNs? -> {"return": "count", "count": 38, "truncated": false}
client.query({
"find": ["?s"],
"where": [["span", "?s", {"layer": UPOS, "value": "NOUN"}]],
"return": "count",
})
# determiner immediately followed by a noun, as full entities
client.query({
"find": ["?d", "?n"],
"where": [["seq", {"layer": MORPHEMES},
["span", {"layer": UPOS, "value": "DET"}, "as", "?d"],
["span", {"layer": UPOS, "value": "NOUN"}, "as", "?n"]]],
"return": "entities",
"limit": 20,
})
# every nsubj dependency whose dependent is sentence-initial
client.query({
"find": ["?r"],
"where": [
["relation", "?r", {"layer": DEPRELS, "value": "nsubj", "target": "?dep"}],
["covers", "?dep", "?td"],
["within", "?td", "?s"],
["token", "?s", {"layer": SENTENCES}],
["first-in", "?td", "?s"],
],
})
# tokens linked to a vocab item
client.query({
"find": ["?t"],
"where": [["vocab", "?v", {"form": "Kemal"}],
["vocab-link", "?t", "?v"]],
})
# how many tokens each unconfirmed machine-made link covers (2+ = a multi-word expression)
client.query({
"where": [["link", "?l", {"metadata": {"prov": "inferred"}}],
["not", ["link", "?l", {"metadata": {"provConfirmed": True}}]],
["link-token", "?l", "?t"]],
"return": {"group": ["?l"], "aggregates": [["count"]]},
})
# restrict to one project by ID
client.query({
"find": ["?s"],
"where": [["span", "?s", {"layer": UPOS, "value": "NOUN"}]],
"scope": {"project_ids": [PROJECT]},
})