Skip to content
Console(opens in a new tab)

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: ", ")
}
}
}

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.

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.

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.

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.

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
}

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
}
}

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.