Skip to content
Console(opens in a new tab)

@map

Extracts a nested field from each element in an array.

Directives. This directive runs after the query has its answer. It changes what you see, not what the query reads.

Extracts a nested field from each element in an array. The ‘field’ argument is a dot-separated path; a list along the path is indexed by an integer segment (‘edges.0.node’) or expanded by the ‘’ wildcard segment (‘edges..node’), which collects the values from every element into one flat list. Returns null for elements where the path does not exist. Example: _fn @map(refs: [“items”], field: “a.b.c”) extracts ‘a.b.c’ from each item; _fn @map(refs: [“websites”, “operatingLocations”], field: “edges..node.technologiesUseds.edges..node.technology”) returns every technology of every website and operating location as one list. If field is omitted, returns the entire array. Alternatively, the ‘fields’ argument accepts a list of { key, path } pairs and returns a list of objects, one per source element, with each object keyed by ‘key’ and valued by the dot-path ‘path’. Example: _fn @map(refs: [“items”], fields: [{ key: “name”, path: “a.name” }, { key: “count”, path: “a.stats.count” }]) returns [{ “name”: …, “count”: … }, …]. ‘field’ and ‘fields’ are mutually exclusive.

Argument Type Description
ref String A dot path to one value in the response, relative to the object that holds _fn. Each segment is a field name or alias, a list index, or * for every item of a list. Write ref or refs as the first argument of the directive.
refs [String!] A list of dot paths, written as for ref. The directive takes the list of their values as its input. In a chain of directives, only the first directive reads ref or refs, and each later directive takes the output of the one before it.
field String A dot path to read from each item of the input list. A number segment picks one list item, and a * segment collects the values from every list item into one flat list. If you omit both field and fields, the directive returns the input list unchanged.
fields [MapFieldInput!] A list of key and path pairs. For each input item, the directive returns an object that maps each key to the value at its path. Use field or fields, not both.

FIELD.

query {
search(searchInput: {
entityType: BRAND
name: "Safeway"
conditions: { limit: 1 }
}) {
... on Brand {
id
cities: _fn @map(refs: ["operatingLocations"], field: "edges.*.node.addresses.edges.0.node.city")
operatingLocations(first: 3) { edges { node { addresses(first: 1) { edges { node { city } } } } } }
}
}
}

Response, as returned:

{
"data": {
"search": [
{
"id": "0f26fbef-3436-4f85-8bcd-31fe12a4f99a",
"cities": [
"BEND",
"PRINCE FREDERICK",
"DELTA"
],
"operatingLocations": {
"edges": [
{
"node": {
"addresses": {
"edges": [
{
"node": {
"city": "BEND"
}
}
]
}
}
},
{
"node": {
"addresses": {
"edges": [
{
"node": {
"city": "PRINCE FREDERICK"
}
}
]
}
}
},
{
"node": {
…
}