---
title: "graphql | Speedscale Docs"
description: "Address a value inside a GraphQL request by semantic path with the graphql transform in Speedscale — variables, arguments and operation names — let downstream transforms rewrite it, then write it back into the document."
canonical: "https://docs.speedscale.com/guides/transformation/transforms/graphql/"
---

[Documentation index](https://docs.speedscale.com/guides/llms.txt) | [Markdown](https://docs.speedscale.com/guides/transformation/transforms/graphql/index.md) | [Canonical page](https://docs.speedscale.com/guides/transformation/transforms/graphql/)

# graphql

The `graphql` transform extracts a value from a GraphQL request by _semantic path_ — `variables.email`, `createUser.args.input.plan`, `operationName` — and acts as a window onto that value for the rest of the chain. Downstream transforms see a plain scalar; when they are done, `graphql` writes the new value back into the document, preserving the value's GraphQL kind.

It is the GraphQL counterpart to [`json_path`](https://docs.speedscale.com/guides/transformation/transforms/json_path/), and it is how nearly every GraphQL chain begins.

*   **Transform type name (config/API):** `graphql`
*   **Shorthand format:** `graphql(path=...)` or `graphql(path=...,op=...)`
*   **Path syntax:** [Speedscale's GraphQL semantic paths](https://docs.speedscale.com/guides/graphql/semantic-paths/)
*   **Side:** request bodies. A GraphQL response is ordinary JSON — use [`json_path`](https://docs.speedscale.com/guides/transformation/transforms/json_path/) for it.

<a id="quick-start"></a>

## Quick Start

Replace a value carried in `variables`:

```json
"type": "graphql",
"config": {
    "path": "variables.token"
}
```

Replace a literal written into the query text, naming the operation because the document defines several:

```text
req_body() → graphql(path="createUser.args.input.plan", op="CreateUser") → constant(new="enterprise")
```

The chain extracts `pro`, hands it to `constant`, and writes `enterprise` back into the same argument.

<a id="how-it-works"></a>

## How It Works

Like `json_path`, the transform is a bookend around the rest of the chain.

1.  **First phase** — parse the request body, resolve the semantic path, and return the value as a plain scalar. The parsed document is remembered for re-insertion.
2.  **Second phase** — take what the downstream chain produced, convert it to a node of the same GraphQL kind as the value it replaces, put it back in the document, and re-serialize the body.

```text
input:  {"query":"mutation { createUser(input: {plan: \"pro\"}) { id } }", ...}
        └─ 1st phase, path="createUser.args.input.plan": extracted = "pro"
        └─ downstream transforms produce "enterprise"
        └─ 2nd phase: writes it back into the argument
output: {"query":"mutation { createUser(input: {plan: \"enterprise\"}) { id } }", ...}
```

<a id="body-forms"></a>

### Body forms

A GraphQL request reaches transforms in one of two shapes, and the transform accepts both and writes back in the form it received:

| Form | Where it comes from |
| --- | --- |
| **AST JSON** | The `req_body` extractor's representation of a captured GraphQL request — what a chain sees during replay and analysis. |
| **Raw** | The request as it goes on the wire: `{"query": "mutation { ... }", "variables": {...}}`. |

You do not choose between them; the transform detects which it was handed.

<a id="type-preservation"></a>

### Type preservation

The replacement node keeps the kind of the value it replaces, so an edit cannot turn a valid document into one the server rejects for a type error:

| Original | New value |
| --- | --- |
| String | Used as-is. |
| Int | Must parse as an integer, or the transform errors. |
| Float | Must parse as a float, or the transform errors. |
| Boolean | Must parse as a boolean, or the transform errors. |
| Enum | Used as-is, as an enum value. |
| Variable reference | Cannot be replaced — target the variable instead (see below). |
| Object / list | Cannot be replaced wholesale — target a scalar inside it. |

For `variables.` paths the JSON type is preserved instead, exactly as [`json_path`](https://docs.speedscale.com/guides/transformation/transforms/json_path/#type-preservation) does it.

<a id="arguments-supplied-by-a-variable"></a>

### Arguments supplied by a variable

An argument written as `input: {email: $email}` holds a reference, not a literal. Reading it returns `$email`; writing to it fails with a message naming the path to use:

```text
argument references variable $email; target variables.email instead
```

This is deliberate: rewriting the reference would decouple the request from the variable the client actually sends.

<a id="missing-paths"></a>

### Missing paths

A path that cleanly resolves to nothing — an argument that is not passed, a field that is not selected, a variables key that is absent — leaves the request untouched rather than failing the chain, so one chain can sweep a snapshot of mixed operations. Structural problems (an ambiguous field, an unknown fragment, an `op` that names no operation) are errors.

<a id="persisted-queries"></a>

### Persisted queries

A request that carries only a persisted-query hash has no document to address. Document paths find nothing and the request passes through unmodified; `variables.` paths still work. See [Persisted queries](https://docs.speedscale.com/guides/graphql/#persisted-queries).

<a id="configuration"></a>

## Configuration

```json
"type": "graphql",
"config": {
    "path": "<semantic path>",
    "op": "<operation name>",
    "create": "<boolean>"
}
```

| Parameter | Required | Default | Description |
| --- | --- | --- | --- |
| `path` | **Yes** | — | The semantic path to the value. Missing config fails chain initialization. |
| `op` | No | — | Which operation the path applies to, when the document defines more than one. Defaults to the envelope's `operationName`. |
| `create` | No | `false` | Create the value if it is missing. Applies to `variables.` paths only — document nodes cannot be synthesized. Note this default is the opposite of `json_path`'s. |

`path` supports `${{...}}` variable substitution, resolved at runtime against the variable cache.

<a id="examples"></a>

## Examples

<a id="example-1--replace-a-variable"></a>

### Example 1 — Replace a variable

```text
req_body() → graphql(path="variables.email") → constant(new="z@y.com")
```

*   Input: `{"query":"mutation CreateUser($email: String!) { ... }","variables":{"email":"a@b.com"}}`
*   Output: the same request with `variables.email` set to `z@y.com`.

<a id="example-2--replace-an-inline-argument"></a>

### Example 2 — Replace an inline argument

```text
req_body() → graphql(path="createUser.args.input.plan") → constant(new="enterprise")
```

*   Input: `createUser(input: {email: $email, plan: "pro"})`
*   Output: `createUser(input: {email: $email, plan: "enterprise"})`

<a id="example-3--rename-the-operation"></a>

### Example 3 — Rename the operation

```text
req_body() → graphql(path="operationName") → constant(new="MakeUser")
```

Both the envelope's `operationName` and the matching operation definition in the document are renamed, so the request stays executable.

<a id="example-4--pick-one-of-several-operations"></a>

### Example 4 — Pick one of several operations

```text
req_body() → graphql(path="user.args.id", op="GetUser") → rand_string(pattern="u-[0-9]{3}")
```

Without `op`, a document defining both `GetPlans` and `GetUser` fails with `document has 2 operations; set op to choose one`.

<a id="example-5--a-value-inside-a-named-fragment"></a>

### Example 5 — A value inside a named fragment

```text
req_body() → graphql(path="fragment.UserFields.avatar.args.size") → constant(new="small")
```

<a id="example-6--json-embedded-in-an-argument"></a>

### Example 6 — JSON embedded in an argument

```text
req_body()
  → graphql(path="trackEvent.args.payload")
  → json_path(path="client.os")
  → constant(new="linux")
```

The `graphql` transform yields the argument's string; `json_path` addresses inside it. Both re-insert in reverse order on the way back out.

<a id="common-misconceptions"></a>

## Common Misconceptions

1.  **"It works on GraphQL responses."** It does not, and does not need to. Responses are plain JSON — use `res_body()` with `json_path`.
    
2.  **"The path is a JSONPath into the AST."** No. It is a semantic path. Positional AST paths with `json_path` still work for backward compatibility, but see [Migrating legacy AST-path chains](https://docs.speedscale.com/guides/graphql/recipes/#migrating-legacy-ast-path-chains).
    
3.  **"`create` works like `json_path`'s."** It defaults to `false` and only applies to `variables.` paths. A selection or argument the query never contained is not invented.
    
4.  **"An ambiguous field picks the first match."** It errors. Add an alias in the client, or address the value through its variable.
    
5.  **"A missing path fails the replay."** It leaves the request alone. This is what lets one chain cover a snapshot of mixed operations.
    

<a id="troubleshooting"></a>

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Chain init: `missing parameter path` | `path` not set | Add `"path": "..."` |
| `body is not a GraphQL request` | The chain ran against traffic that is not GraphQL, or against a response | Scope the chain with an endpoint filter; use `json_path` for responses |
| `document has N operations; set op to choose one` | Multi-operation document, no `operationName` in the envelope | Set `op` |
| `field "x" is ambiguous (N matches)` | The same field label appears more than once in the selection set | Alias the field in the client, or target its variable |
| `argument references variable $x` | The argument holds a variable reference, not a literal | Target `variables.x` |
| `new value "abc" is not an Int` | The downstream chain produced text that does not fit the argument's kind | Produce a value of the right kind |
| `the operation type is read-only` | Writing to `operation` | Read it if you need it; `query`/`mutation` cannot be rewritten |
| Nothing changed, no error | The path resolved cleanly to nothing, or the request is a persisted query | Check the path against the **Raw** tab; see [Persisted queries](https://docs.speedscale.com/guides/graphql/#persisted-queries) |

<a id="related-transforms"></a>

## Related Transforms

*   [`graphql_delete`](https://docs.speedscale.com/guides/transformation/transforms/graphql_delete/) — remove a selection or argument instead of rewriting it.
*   [`json_path`](https://docs.speedscale.com/guides/transformation/transforms/json_path/) — the JSON counterpart, and what chains after `graphql` when a JSON document is embedded in an argument.
*   [`smart_replace`](https://docs.speedscale.com/guides/transformation/transforms/smart_replace/) — propagate a value extracted from a GraphQL request across the rest of the RRPair.

<a id="advanced-notes"></a>

## Advanced Notes

*   The transform does not require recorded response data.
*   `path` is re-resolved on both phases against the variable cache, so a `${{var:...}}` reference picks up whichever value is current at each phase.
*   Renaming `operationName` also renames the matching operation definition, keeping the envelope and the document consistent.
*   Inline fragments are transparent to a path; named fragments are addressed explicitly with the `fragment.<Name>` prefix.
