Batch Operations

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 dataclass

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 instance-attribute

mutation_name: str

input_type_name instance-attribute

input_type_name: str

variables instance-attribute

variables: dict[str, Any]

return_fields class-attribute instance-attribute

return_fields: str = 'id __typename'

result class-attribute instance-attribute

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

error class-attribute instance-attribute

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

BatchResult dataclass

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 instance-attribute

operations: list[BatchOperation]

raw_response class-attribute instance-attribute

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

succeeded property

succeeded: list[BatchOperation]

Operations that completed successfully.

failed property

failed: list[BatchOperation]

Operations that encountered errors.

all_succeeded property

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