Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 21 additions & 5 deletions packages/web/docs/src/content/router/configuration/expressions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ control‑flow. For example:
if .request.headers."x-feature-toggle" == "beta" {
"https://beta.example.com/graphql"
} else {
.original_url
.default
}
```

Expand Down Expand Up @@ -89,13 +89,29 @@ While not a full object, the special variable `.timestamp` yields the current UN
header manipulation guide demonstrates using `.timestamp` to add a `X‑Request‑Time` header. This is
useful for debugging and tracing requests.

### `.original_url`
### `.default`

This variable is only available in [dynamic routing expressions](./override_subgraph_urls). It holds
the default URL for the current subgraph, as declared in your supergraph schema. Because the
expression must return a URL, you should always provide a fallback using `.original_url` so that
requests are routed somewhere when no condition matches. The configuration reference emphasises this
by showing a pattern where the expression returns `.original_url` in the `else` branch.
expression must return a URL, you should always provide a fallback using `.default` so that requests
are routed somewhere when no condition matches. The configuration reference emphasises this by
showing a pattern where the expression returns `.default` in the `else` branch.

### `.default`

This variable is available in [dynamic routing expressions](./override_subgraph_urls) and
[traffic shaping expressions](./traffic_shaping). It holds the default value for the context in
which it is used:

- In **dynamic routing**, it holds the default URL for the current subgraph, as declared in your
supergraph schema.
- In **traffic shaping**, it holds the default timeout value set at the global level (available for
subgraph overrides).

When writing expressions with conditional logic (like `if` statements), you must ensure a value is
returned for all paths. You may return any valid value, but `.default` is commonly used as a
fallback. This allows you to override the configuration for specific conditions while maintaining
the originally assigned value for all other cases.

## Available functions

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ decisions.
Within the `expression`, you have access to two key variables:

- `.request`: The incoming HTTP request object, including its headers.
- `.original_url`: The original subgraph URL from the supergraph schema, which should be used as a
- `.default`: The original subgraph URL from the supergraph schema, which should be used as a
fallback.

```yaml
Expand All @@ -70,6 +70,6 @@ override_subgraph_urls:
if .request.headers."x-region" == "eu" {
"https://reviews.eu.api/graphql"
} else {
.original_url
.default
}
```
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ For each request, the router evaluates your expression and routes to the URL it
**What you have access to:**

- `.request` - The incoming HTTP request (headers, method, etc.)
- `.original_url` - The default URL from your supergraph schema
- `.default` - The default URL from your supergraph schema

Simple example configuration that routes based on a runtime condition:

Expand All @@ -34,7 +34,7 @@ override_subgraph_urls:
if .router.headers."x-use-special-instance" == "true" {
"https://special-instance.com/graphql"
} else {
.original_url # Always provide a fallback
.default # Always provide a fallback
}
```

Expand All @@ -61,7 +61,7 @@ override_subgraph_urls:
if .request.headers."x-deploy-track" == "canary" {
"https://products-canary.example.com/graphql"
} else {
.original_url
.default
}
```

Expand All @@ -82,7 +82,7 @@ override_subgraph_urls:
if random_int(1, 100) <= 10 {
"https://products-canary.example.com/graphql"
} else {
.original_url
.default
}
```

Expand Down Expand Up @@ -110,6 +110,6 @@ override_subgraph_urls:
"https://reviews-ap.example.com/graphql"
} else {
# Default to primary region
.original_url
.default
}
```
Loading