- Docs
- API reference
- Endpoints and schemas
- GraphQL
The anatomy of a query
The parts of every search, the layer that reshapes an answer, and the two parts that appear only with files and writes. Learn them once with search, and reuse them everywhere.
You have picked an intent. Before you write anything else, there is one structure worth learning, because every intent is built from it.
Intents differ in what they hand back. search returns records, aggregate
returns a number, enrich returns a file, createList stores a list.
Underneath, they ask the same kind of question in the same way: name what you
are looking for, describe who you mean, narrow it down, walk to the records
that hold the answer, say what you want to know, and shape how it reads.
Let’s learn the anatomy once with search, where every part of a read is
visible. The other intents are the same query with a different ending, and two
of them add a part of their own.
That sentence has the same moving parts as the query below, in the same order.
Each comment names one part. Note where the comment sits: limit applies to the
search, while filter and orderBy apply to the locations you read. The
Condition section explains why.
query { search(searchInput: { # Intent entityType: BRAND # Subject name: "Safeway" # Match conditions: { limit: 1 } # Condition }) { ... on Brand { # Subject id # Selection names(first: 1) { edges { node { name } } } operatingLocations(first: 25, conditions: { filter: { EQ: ["addresses.state", "TX"] } # Condition orderBy: ["cardTransactions.projectedQuantity DESC"] # Condition }) { edges { node { # Connection addresses(first: 1) { edges { node { streetAddress1 city state } } # Selection } } } } cities: _fn # Directives @map(refs: ["operatingLocations"], field: "edges.*.node.addresses.edges.0.node.city") @unique @join(sep: ", ") } }}The parts of every search
Section titled “The parts of every search”Intent: search
Section titled “Intent: search”What kind of answer do I want?
What you are asking us to do. You chose this in the previous section, and it sets the scope and direction of everything after it: which input it takes, which parts that input can hold, and what comes back.
Subject: entityType: BRAND and ... on Brand
Section titled “Subject: entityType: BRAND and ... on Brand”What kind of thing am I looking for?
The kind of record you want. Our data holds a few kinds that can be identified: a brand, a legal entity, a location, a person, an address. Naming one fixes the vocabulary for the rest of the query: what you may describe, what you may narrow by, and what you may read.
It appears twice. Once to say what to look for, once to say what to read from. Both name the same thing.
Match: name: "Safeway"
Section titled “Match: name: "Safeway"”Who do I mean?
Your description of the business you are after, in the terms you happen to have: a name, an address, a phone number, a website. You are not naming a row in our database. You are describing a business in the world, and we find the records that answer to it.
Because it is a description rather than an exact value, we score how well each record answers to it, and you can require a stronger resemblance if you want fewer, closer matches.
Condition: conditions: { filter · orderBy · limit }
Section titled “Condition: conditions: { filter · orderBy · limit }”Which of those do I keep, and in what order?
A rule every record must satisfy, and the shape of the list you get back. Unlike a description, a rule is exact: a record either satisfies it or it does not. Texas is Texas.
Conditions attach at two places, and the two are not equal. On a connection,
such as operatingLocations, all three work: filter, orderBy and paging.
On the search itself, only limit has an effect. A filter or orderBy
written there is accepted and then ignored, with no error. Write every rule on
the connection that holds the data.
Two syntax rules
Section titled “Two syntax rules”Sort is a field and a direction, separated by a space:
"cardTransactions.projectedQuantity DESC". The direction is required, and
only ASC and DESC are accepted. A leading minus, as in
"-projectedQuantity", is a convention from other APIs. It is rejected here.
Filter keys are written without quotation marks: { EQ: [...] }, not
{ "EQ": [...] }. The operators are EQ, NE, IN, GT, GTE, LT,
LTE, LIKE, ILIKE, IS_NULL and IS_NOT_NULL, combined with AND, OR
and NOT.
Connection: operatingLocations { edges { node } }
Section titled “Connection: operatingLocations { edges { node } }”How do I reach the records that hold the answer?
A record does not contain its related records. It connects to them. A brand
connects to its locations, a location to its addresses. Every relationship has
the same shape: the field names the relationship, edges is the list, and
node is one related record. Walking through a connection moves you to a new
place, and the Condition and Selection you write there are about that place.
A connection also decides how many related records you get, and which comes
first. Write first to say how many. The list is ranked, so first: 1 is the
primary address, the primary name, the primary anything.
Selection: id · names · addresses · streetAddress1
Section titled “Selection: id · names · addresses · streetAddress1”What do I want to know about them?
The specific fields you want returned in your response. While our records contain extensive details like trading names, locations, and parent companies, you only select the data points you need.
The API will never return unrequested data. This means responses are highly
tailored to your query, and you avoid paying for information you don’t intend
to use. A number is a selection too: count, sum and the other math fields
stand where a list of rows would stand.
The layer on top
Section titled “The layer on top”Directives: cities: _fn @map @unique @join
Section titled “Directives: cities: _fn @map @unique @join”How should the answer read?
The final adjusting layer. A directive runs after the query has been answered.
The server reads the records, builds the response, and then walks the response
once more to apply every directive it carries. @map collects one city per
location, @unique keeps each city once, @join writes them on one line.
A directive can only reshape what the Selection already read. It cannot reach a field you did not select, and it cannot make a query cheaper. It changes what you see, not what is read.
The parts a search never has
Section titled “The parts a search never has”Two parts appear only with certain intents. They do not describe the business you mean or the fields you want. The examples below are not run against production data.
File: output: { filename, format } and s3Path
Section titled “File: output: { filename, format } and s3Path”Where does the data live?
When the answer, or the question, is a file. enrich reads its questions from
a file at s3Path and writes its answer to a file named by output. search
can write to a file the same way. A saved list reads its rows from a file and
writes its result in a file format. The File part says where the data goes,
and in what shape.
enrich(enrichmentInput: { s3Path: "s3://…/merchants.csv" # File sourceId: "q3-portfolio" # File entityType: BRAND # Subject output: { filename: "matched", format: CSV } # File}) { ... on Brand { id } # Subject, Selection}Payload: name: "Texas merchants"
Section titled “Payload: name: "Texas merchants"”What do I store?
The new values a write stores as they are. A write such as createList has
the same parts as a read, plus this one: the list’s own name and description,
a materialization’s status, the value a suggestion proposes. Inside a saved
list, the stored query is written with the same Subject, Match, Condition and
Selection you already know.
mutation { createList(input: { # Intent name: "Texas merchants" # Payload listType: LIST_GENERATION # Payload searchInput: { entityType: BRAND # Subject conditions: { # Condition filter: { EQ: ["operatingLocations.addresses.state", "TX"] } } } }) { list { id } # Selection }}Where each part lives
Section titled “Where each part lives”The GraphQL reference lists every keyword of the schema under the part it belongs to, in the order above. A part opens with what it answers, then lists the inputs, types or directives that belong to it.