Setting the file. One moment.
Subchapter 2.6
references/variables.mdMarkdown7 KBView on GitHub
You MUST NOT make up variable names - only use variables listed here.
| Variable | Description | Availability |
|---|---|---|
$ | Root/parent reference | selection, errors in @connect |
$args | Field arguments | @connect when field has arguments |
$batch | Entity batch references | @connect on types only |
$config | Router configuration | Always available |
$context | Coprocessor context | When customizations set context |
$env | Environment variables | Always available |
$request.headers | Incoming request headers | Always available |
$response.headers | Response headers | selection, errors |
$status | HTTP response status code | selection, errors in @connect |
$this | Parent object fields | Non-root types only |
@ | Transformation context | Within method arguments |
At the top level, $ refers to the API response body root. Within a sub-selection, $ refers to the parent value.
selection: """
# $ refers to response root
$.results {
# Inside here, $ refers to each item in results
id
fullName: $.name.first
}
"""Usage:
@connect‘s selection and errorsAccess arguments passed to the GraphQL field.
type Query {
user(id: ID!): User
@connect(
http: { GET: "/users/{$args.id}" }
selection: "id name"
)
users(limit: Int, offset: Int): [User]
@connect(
http: {
GET: "/users"
queryParams: """
limit: $args.limit
offset: $args.offset
"""
}
selection: "id name"
)
}Usage:
"/path/{$args.id}"limit: $args.limit"userId: $args.id"Used to batch multiple entity resolution requests into a single API call.
type Product @connect(
source: "api"
http: {
POST: "/products/batch"
body: "ids: $batch.id"
}
selection: """
id
name
price
"""
) {
id: ID!
name: String
price: Float
}Rules:
@connect attached to types$batch must be in the selectionSee entities.md for detailed batching patterns.
Access values from router configuration file.
Router config (router.yaml):
connectors:
sources:
my_subgraph.my_api:
$config:
api_version: "v2"
feature_flag: trueSchema usage:
@connect(
http: { GET: "/api/{$config.api_version}/users" }
selection: "id name"
)Note: Prefer $env over $config when possible.
Access context set by router customizations like coprocessors.
@connect(
http: {
GET: "/users"
headers: [
{ name: "X-Tenant", value: "{$context.tenantId}" }
]
}
selection: "id name"
)Usage:
Access environment variables available to the router process.
@source(
name: "api"
http: {
baseURL: "https://api.example.com"
headers: [
{ name: "Authorization", value: "Bearer {$env.API_KEY}" }
]
}
)Common patterns:
# API keys
{ name: "X-API-Key", value: "{$env.API_KEY}" }
# Dynamic base URLs
baseURL: "{$env.API_BASE_URL}"
# Feature flags
# (use in combination with conditional logic)Always available. Prefer this over hardcoding secrets.
Access headers from the client request to the router.
@connect(
http: {
GET: "/users"
headers: [
{ name: "Authorization", value: "{$request.headers.authorization->first}" }
]
}
selection: "id name"
)Important:
->first to get the first value$request.headers.'x-my-header'->firstAccess headers from the connector’s HTTP response.
@connect(
http: { GET: "/users" }
selection: """
id
name
rateLimit: $response.headers.'x-rate-limit'->first->parseInt
"""
)Usage:
selection and errors->firstAccess the numeric HTTP status code from the response.
@connect(
http: { DELETE: "/users/{$args.id}" }
selection: """
success: $(true)
"""
errors: {
message: "$status->match([404, 'Not found'], [@, 'Error'])"
}
)Usage:
selection and errors of @connectAccess sibling fields from the parent object. Used for field-level connectors that need parent data.
type User {
id: ID!
name: String
posts: [Post] @connect(
http: { GET: "/users/{$this.id}/posts" }
selection: "id title"
)
}Usage:
Example with nested access:
type Order {
id: ID!
customerId: ID!
customer: Customer @connect(
http: { GET: "/customers/{$this.customerId}" }
selection: "id name email"
)
}The current value being transformed within a method. Changes meaning based on context.
selection: """
# In filter: @ is each array item
activeUsers: $.users->filter(@.isActive)
# In map: @ is each item being transformed
names: $.users->map(@.name)
# In echo: @ is the input value
wrapped: $.data->echo({ value: @ })
# Nested: @ refers to innermost context
items: $.list->map({ doubled: @->mul(2) })
"""Context changes:
filter(@.field) - @ is each item being testedmap(@.field) - @ is each item being transformedecho({ a: @ }) - @ is the input to echomatch([cond, @]) - @ is the original value