Expressions

The Hive Router uses expressions written in VRL (Vector Remap Language) to make dynamic decisions at runtime. VRL is a small, declarative language originally created by DataDog for the Vector observability pipeline and is well‑suited for parsing and transforming structured data. In Hive Router, expressions let you:

• Route requests to different subgraph URLs based on HTTP headers, geographic region or other request metadata.
• Insert, modify or remove HTTP headers before forwarding a request to a subgraph or before sending a response back to the client.

Although the concept of “expressions” appears in several parts of the configuration, the syntax and available APIs are consistent. This page explains what variables and functions are available, when different variables can be used, and links you to the official VRL documentation for the full language reference.

Syntax overview

Every expression evaluates to a value, and you can build more complex logic using functions and control‑flow. For example:

if .request.headers."x-feature-toggle" == "beta" {
  "https://beta.example.com/graphql"
} else {
  .original_url
}

VRL supports variables (prefixed with a dot), built‑in functions, simple arithmetic and comparisons, and control structures such as if … else.

Multi‑line expressions are especially useful for readability and complex routing logic.

Available values

Within an expression you interact with a few top‑level values. The most important ones are:

.request

Represents the incoming HTTP request. It exposes nested fields such as:

• .request.headers - a case‑insensitive map of request headers. For example, .request.headers.authorization gives you the value of the Authorization header.
• .request.method - the HTTP method as a lowercase string (e.g. "post").
• .request.url.host - the request host (e.g. api.example.com).
• .request.url.port - the request port (e.g. 443).
• .request.url.path - the request path (e.g. /graphql).
• .request.operation.name - the name of the GraphQL operation being executed, if provided.
• .request.operation.type - the type of GraphQL operation being executed (e.g. "query", "mutation", or "subscription").
• .request.operation.query - the full GraphQL query string being executed.

These values allow you to branch logic based on who is calling your API and what data they send.

.response

Available only in response header rules. It represents the HTTP response from a subgraph call. You can inspect .response.url or .response.headers and then set or override additional headers. For example, you could conditionally add a cache header based on the subgraph’s status code. This variable is not present when computing request headers or dynamic URLs, because the response does not yet exist.

• .response.headers - a case‑insensitive map of response headers.

.subgraph

Available in both request and response header rules. It provides metadata about the subgraph handling the current request, including:

• .subgraph.name - the name of the subgraph as defined in your supergraph schema.

.timestamp

While not a full object, the special variable .timestamp yields the current UNIX timestamp. The header manipulation guide demonstrates using .timestamp to add a X‑Request‑Time header. This is useful for debugging and tracing requests.

.original_url

This variable is only available in dynamic routing expressions. 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.

Available functions

The Hive Router exposes the full set of VRL built‑in functions. The configuration guides use a few of them in examples:

• replace(value, pattern, replacement) - returns a new string with all matches of pattern replaced. In the header manipulation guide it’s used to normalise an Authorization header by stripping existing prefixes.
• contains(value, substring) - tests whether a string contains a substring.
• random_int(min, max) - produces a random integer in the inclusive range. Combined with if to create percentage‑based canary routing of subgraphs.
• lowercase(value), uppercase(value), split(value, delimiter), to_int(value) - helpful for normalising and parsing header values.

For a complete list of functions - including string manipulation, number conversion, JSON parsing, and more - see the VRL function reference. When writing expressions, you can call any of these functions directly.

Troubleshooting

When an expression doesn’t work as expected, it can be due to a compilation error (syntax) or a runtime error (evaluation). The Hive Router provides detailed logs to help you diagnose the issue.

Compilation Errors

Compilation errors occur if your expression has invalid VRL syntax. The router will fail to start and log an error message pointing to the problematic expression. Common syntax errors include mismatched parentheses, missing commas, or incorrect function names.

Runtime Errors

Runtime errors happen when a syntactically correct expression fails during execution. These are logged by the router during a request. The router will also return an error response to the client.

Here are some frequent causes of runtime errors in expressions:

1. Accessing an unavailable variable: Expressions run in specific contexts. For example, trying to access .response in a request header rule will fail because the response from the subgraph doesn’t exist yet.
2. Type Mismatches: VRL is strongly typed. If you try to perform an operation on incompatible types, like comparing a string with an integer, you’ll get a runtime error.
3. Handling null values: Accessing a non-existent header or field returns null. Operations on null values can lead to errors. Always check for the existence of a value or provide a fallback. You can use the || operator to provide a default value (e.g., .request.headers."x-custom-header" || "default-value").

For a full list of error codes and their meanings, refer to the VRL error reference.