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 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:
    expression: # ... global expression
  subgraphs:
    products:
      url: # ... url definition
    reviews:
      url: # ... url definition

Options

all

• Type: object
• Required: No

all.expression lets you define one routing expression that applies to every subgraph without its own entry under subgraphs.

Within the expression, you have access to:

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

override_subgraph_urls:
  all:
    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.url_matches:

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

subgraphs.<name>.url

• Type: string or object
• Required: Yes

The url property defines the new URL for the 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, and url_matches).
• .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
          }