- Docs
- API reference
- Endpoints and schemas
- GraphQL
- Directives
@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.
Arguments
Section titled “Arguments”| 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. |
Where it goes
Section titled “Where it goes”FIELD.
Example
Section titled “Example”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": { …}