override_subgraph_urls

The override_subgraph_urls configuration allows you to dynamically change subgraph URLs at runtime based on the incoming request.

This is the primary mechanism for implementing advanced routing patterns. For detailed guides and use cases, see the Dynamic Subgraph Routing guide.

Configuration Structure

The override_subgraph_urls key is a top-level object in your router.config.yaml. It supports two override scopes:

• subgraphs: Per-subgraph URL overrides keyed by subgraph name.
• all: A single override (static URL or expression) applied to all subgraphs that do not have a dedicated override under subgraphs.

Per-subgraph overrides always take precedence over all.

override_subgraph_urls:
  all: 
    url: # ... global static URL or expression
  subgraphs:
    products:
      url: # ... static URL
    reviews:
      url:
        expression: # ... expression

Options

all

• Type: string or object
• Required: No

all lets you define a global override for every subgraph without its own entry under subgraphs. It can be a static URL string or an object with an expression.

Within the expression, you have access to:

• .request: The incoming HTTP request object (headers, parsed operation, url, and path_params).
• .default: The original subgraph URL from the supergraph schema.
• .subgraph.name: The name of the subgraph currently being resolved.

override_subgraph_urls:
  all:
    url:
      expression: |
        if .subgraph.name == "products" && .request.headers."x-region" == "us-east" {
          "https://products-us-east.example.com/graphql"
        } else {
          .default
        }

If http.graphql_endpoint uses path parameters, they are available under .request.path_params:

http:
  graphql_endpoint: /{tenant}/graphql
override_subgraph_urls:
  all:
    url:
      expression: |
        tenant = string!(.request.path_params.tenant)
        replace(string!(.default), "/api/", "/api/" + tenant + "/")

subgraphs.<name>

• Type: string or object
• Required: Yes

Each subgraphs.<name> entry defines the new URL for that subgraph. It can be provided in two forms: a static string or an object for dynamic evaluation.

Static URL

When a string is provided, all requests to that subgraph will be sent to the new static URL. This is useful for permanently redirecting a subgraph without recomposing your supergraph.

override_subgraph_urls:
  subgraphs:
    products: 
      url: "https://products.staging.svc.cluster.local/"

Dynamic URL with expression

When an object is provided, it must contain an expression that returns a URL string. The expression is evaluated for each request, allowing for request-time routing decisions.

• expression: (string, required) An expression that computes the new URL.

Within the expression, you have access to:

• .request: The incoming HTTP request object (headers, parsed operation, url, and path_params).
• .default: The original subgraph URL from the supergraph schema.
• .subgraph.name: The name of the subgraph currently being resolved.

override_subgraph_urls:
  subgraphs:
    reviews:
      url:
        expression: |
          if .request.headers."x-region" == "eu" {
            "https://reviews.eu.api/graphql"
          } else {
            .default
          }