Batch Operations - Stash Tools & Scrapers

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 BatchOperations 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. 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

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

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

mutation_name: str

input_type_name

input_type_name: str

variables

variables: dict[str, Any]

return_fields

return_fields: str = 'id __typename'

result

result: dict[str, Any] | None = field(
    default=None, repr=False
)

error

error: Exception | None = field(default=None, repr=False)

BatchResult

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

operations: list[BatchOperation]

raw_response

raw_response: dict[str, Any] | None = field(
    default=None, repr=False
)

succeeded

succeeded: list[BatchOperation]

Operations that completed successfully.

failed

failed: list[BatchOperation]

Operations that encountered errors.

all_succeeded

all_succeeded: bool

True if every operation succeeded.

Functions

build_batch_document

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

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"}}

​Classes

​BatchOperation

​Attributes

mutation_name

input_type_name

variables

return_fields

result

error

​BatchResult

​Attributes

operations

raw_response

succeeded

failed

all_succeeded

​Functions

​build_batch_document

Classes

BatchOperation

Attributes

BatchResult

Attributes

Functions

build_batch_document