> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jakan.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Operations

> Data structures and helpers for batched GraphQL mutations.

Data structures and helpers for batched GraphQL mutations. These low-level
primitives underlie the three-layer batch API:

* **`client.execute_batch(operations)`** — executes a list of `BatchOperation`s
  in a single aliased GraphQL request. Handles chunking (default 250 ops),
  aliasing, and partial-failure propagation. Returns a `BatchResult`.
* **`store.save_batch(entities)`** — takes entity objects and builds the
  appropriate operations automatically, including any queued side-mutations.
* **`store.save_all()`** — flushes every dirty or new entity the store is
  currently tracking.

For end-to-end usage patterns, see the
[Batched Mutations guide](/sgc/guide/batched-mutations).

Batched GraphQL mutation support.

This module provides data structures and helpers for combining multiple GraphQL mutations into a single aliased document, reducing HTTP round-trips.

Example

```python theme={null}
from stash_graphql_client.client.batch import BatchOperation, build_batch_document

ops = [
    BatchOperation("sceneUpdate", "SceneUpdateInput!", {"input": {"id": "1", "title": "New"}}),
    BatchOperation("tagCreate", "TagCreateInput!", {"input": {"name": "Action"}}),
]
query, variables = build_batch_document(ops)
# query = 'mutation Batch($input0: SceneUpdateInput!, $input1: TagCreateInput!) {
#   op0: sceneUpdate(input: $input0) { id __typename }
#   op1: tagCreate(input: $input1) { id __typename }
# }'
# variables = {"input0": {"id": "1", "title": "New"}, "input1": {"name": "Action"}}
```

## Classes

### BatchOperation

```python theme={null}
BatchOperation(
    mutation_name: str,
    input_type_name: str,
    variables: dict[str, Any],
    return_fields: str = "id __typename",
    result: dict[str, Any] | None = None,
    error: Exception | None = None,
)
```

A single operation within a batch request.

Attributes:

| Name              | Type                     | Description                                                                                                                 |
| ----------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `mutation_name`   | `str`                    | The GraphQL mutation field name (e.g. `"sceneUpdate"`).                                                                     |
| `input_type_name` | `str`                    | The GraphQL input type with `!` suffix (e.g. `"SceneUpdateInput!"`).                                                        |
| `variables`       | `dict[str, Any]`         | Variables dict, typically `{"input": {...}}`.                                                                               |
| `return_fields`   | `str`                    | Space-separated fields to request in the response. Defaults to `"id __typename"` so callers can validate the returned type. |
| `result`          | `dict[str, Any] \| None` | Populated after execution with the mutation's response dict, or `None` if the operation hasn't run or had an error.         |
| `error`           | `Exception \| None`      | Populated after execution with the exception if this specific operation failed, or `None` on success.                       |

#### Attributes

##### mutation\_name

```python theme={null}
mutation_name: str
```

##### input\_type\_name

```python theme={null}
input_type_name: str
```

##### variables

```python theme={null}
variables: dict[str, Any]
```

##### return\_fields

```python theme={null}
return_fields: str = 'id __typename'
```

##### result

```python theme={null}
result: dict[str, Any] | None = field(
    default=None, repr=False
)
```

##### error

```python theme={null}
error: Exception | None = field(default=None, repr=False)
```

### BatchResult

```python theme={null}
BatchResult(
    operations: list[BatchOperation],
    raw_response: dict[str, Any] | None = None,
)
```

Result of a batch execution.

Contains the full list of operations (in the same order they were submitted) with each operation's `.result` and `.error` populated.

Attributes:

| Name           | Type                     | Description                                                               |
| -------------- | ------------------------ | ------------------------------------------------------------------------- |
| `operations`   | `list[BatchOperation]`   | The operations list with results/errors filled in.                        |
| `raw_response` | `dict[str, Any] \| None` | The raw aggregated GraphQL response dict(s), or `None` for empty batches. |

#### Attributes

##### operations

```python theme={null}
operations: list[BatchOperation]
```

##### raw\_response

```python theme={null}
raw_response: dict[str, Any] | None = field(
    default=None, repr=False
)
```

##### succeeded

```python theme={null}
succeeded: list[BatchOperation]
```

Operations that completed successfully.

##### failed

```python theme={null}
failed: list[BatchOperation]
```

Operations that encountered errors.

##### all\_succeeded

```python theme={null}
all_succeeded: bool
```

True if every operation succeeded.

## Functions

### build\_batch\_document

```python theme={null}
build_batch_document(
    operations: list[BatchOperation],
) -> tuple[str, dict[str, Any]]
```

Build an aliased GraphQL mutation document from a list of operations.

Each operation gets a unique alias (`op0`, `op1`, ...) and a unique variable name (`$input0`, `$input1`, ...).

Parameters:

| Name         | Type                   | Description                                   | Default    |
| ------------ | ---------------------- | --------------------------------------------- | ---------- |
| `operations` | `list[BatchOperation]` | Non-empty list of `BatchOperation` instances. | *required* |

Returns:

| Type                         | Description                                                     |
| ---------------------------- | --------------------------------------------------------------- |
| `tuple[str, dict[str, Any]]` | A `(query_string, merged_variables)` tuple ready for execution. |

Example output for 2 operations

```python theme={null}
mutation Batch($input0: SceneUpdateInput!, $input1: TagCreateInput!) {
  op0: sceneUpdate(input: $input0) { id __typename }
  op1: tagCreate(input: $input1) { id __typename }
}
{"input0": {"id": "1", "title": "New"}, "input1": {"name": "Action"}}
```