Batch Operations

Batch Operations

The batch command executes multiple GraphQL operations in a single HTTP request. It's useful for pipelines, bulk operations, and feeding results through jq transformations.

Input Format

batch reads from stdin or --file. Each operation is a JSON object:

{"query": "{ users { id name } }"}
{"query": "{ posts { id title } }"}

NDJSON (default)

One JSON object per line. Uses Content-Type: application/x-ndjson:

printf '{"query":"{ users { id } }"}\n{"query":"{ posts { id } }"}\n' \
  | gqlcli batch

JSON Array

Standard GraphQL batch format. Uses Content-Type: application/json:

printf '[{"query":"{ users { id } }"},{"query":"{ posts { id } }"}]' \
  | gqlcli batch --array

Reading from a File

gqlcli batch --file operations.ndjson

Example operations.ndjson:

{"query":"{ users { id name status } }"}
{"query":"{ posts { id title } }"}
{"query":"query GetUser($id: ID!) { user(id: $id) { id name } }","variables":{"id":"1"}}

jq Filtering

Per-Operation (Server-Side "jq" Field)

Each operation can include a "jq" field. The response is filtered before being returned:

printf '{"query":"{ users { id name status } }","jq":".data.users[] | select(.status == \"active\") | .name"}\n' \
  | gqlcli batch

Useful jq expressions for the "jq" field:

Expression	Effect
.data	Strip the GraphQL envelope
.data.users[].name	Extract a field from each element
.data.users | length	Count results
.data.users[] | select(.active)	Filter array items
.data.logs[] | select(.message | test("error"))	Regex match
.data | {count: (.users | length)}	Reshape response

Global (Client-Side --jq Flag)

Apply a single jq expression to every response in the batch:

printf '{"query":"{ users { id name } }"}\n{"query":"{ posts { id title } }"}\n' \
  | gqlcli batch --jq '.data'

Pipeline Patterns

Filter then Mutate

Query inactive users, then archive each one:

gqlcli query -q '{ users { id status } }' -f json \
  | jq -c '.data.users[] | select(.status == "inactive") | {query: "mutation($id:ID!){archive(id:$id){ok}}", variables: {id: .id}}' \
  | gqlcli batch

Collect Results

Run multiple queries and aggregate output:

cat <<'EOF' | gqlcli batch --jq '.data'
{"query":"{ users { id name } }"}
{"query":"{ groups { id name } }"}
{"query":"{ roles { id name } }"}
EOF

Process Records in Bulk

# Generate one mutation per ID from a file
cat ids.txt | while read id; do
  echo "{\"query\":\"mutation(\$id:ID!){deleteUser(id:\$id){ok}}\",\"variables\":{\"id\":\"$id\"}}"
done | gqlcli batch

Variables in Batch Operations

Each operation can include a "variables" field:

{"query":"query GetUser($id: ID!) { user(id: $id) { id name } }","variables":{"id":"1"}}
{"query":"query GetUser($id: ID!) { user(id: $id) { id name } }","variables":{"id":"2"}}

Debug Mode

gqlcli batch --file ops.ndjson --debug

Prints request and response details for each operation.