Batch Operations

QQL has two batch execution modes and a bulk insert statement for efficient high-throughput workflows.

Bulk INSERT

Insert multiple documents in a single statement:

INSERT INTO docs VALUES
  {'id': 1, 'text': 'first document', 'category': 'tech'},
  {'id': 2, 'text': 'second document', 'category': 'science'},
  {'id': 3, 'text': 'third document', 'category': 'tech'}
USING HYBRID

This sends a single UpsertPoints batch to Qdrant — no overhead per document.

ExecBatch — Sequential Mixed Statements

Use ExecBatch for mixed statement types (INSERT + QUERY + CREATE). Executes each statement in order.

CLI

Execute a batch script

qql-go execute workflow.qql --stop-on-error

Go SDK

results, err := qql.ExecBatch(ctx, client, []string{
    "CREATE COLLECTION medical HYBRID WITH HNSW (m = 32) WITH QUANTIZATION (type = 'turbo', bits = 2)",
    "CREATE INDEX ON COLLECTION medical FOR specialty TYPE keyword",
    "INSERT INTO medical VALUES {'text': 'stroke protocol', 'specialty': 'neurology'} USING HYBRID",
    "INSERT INTO medical VALUES {'text': 'cardiac arrest', 'specialty': 'cardiology'} USING HYBRID",
    "QUERY 'emergency' FROM medical LIMIT 5 USING HYBRID",
}, true) // stopOnError = true

Each result has:

ok — whether the statement succeeded
operation — statement type (e.g., INSERT, QUERY)
message — human-readable result
data — JSON-encoded result data

Gateway (HTTP)

Gateway ExecBatch endpoint

curl -X POST http://localhost:50051/qql.QQL/ExecBatch
-H "Content-Type: application/json"
-d '{ "queries": [ {"query": "QUERY "a" FROM docs LIMIT 5"}, {"query": "QUERY "b" FROM docs LIMIT 5"} ], "stop_on_error": true }'

BatchQuery — Single Round-Trip QUERY Batches

When all statements are pure QUERY statements, use BatchQuery. All queries are sent in a single QueryBatchPoints call to Qdrant — 3–5× faster than sequential execution.

Go SDK

results, err := qql.BatchQuery(ctx, client, []string{
    "QUERY 'emergency triage' FROM docs LIMIT 5 USING HYBRID",
    "QUERY 'cardiac arrest protocol' FROM docs LIMIT 5 USING HYBRID",
    "QUERY 'neurological assessment' FROM docs LIMIT 5 USING HYBRID",
})
// All 3 queries executed in ONE round-trip to Qdrant

Gateway Auto-Detection

When all queries in an ExecBatch call are pure QUERY statements, the gateway automatically routes them through QueryBatch. You don't need to call a different endpoint.

Choosing the Right Mode

Scenario	Use
Multiple independent similarity searches	`BatchQuery`
Setup script (CREATE + INDEX + INSERT + QUERY)	`ExecBatch` with `stopOnError = true`
Bulk data ingest	Bulk `INSERT INTO ... VALUES {...}, {...}`
A/B testing multiple queries	`BatchQuery`
CI pipeline with mixed operations	`ExecBatch`

Script Files (.qql)

Write multi-statement scripts as .qql files. Statements are separated by newlines. Comments start with --.

-- setup.qql
-- Create collection
CREATE COLLECTION medical HYBRID

-- Create indexes
CREATE INDEX ON medical FOR specialty TYPE keyword
CREATE INDEX ON medical FOR year TYPE integer

-- Insert data
INSERT INTO medical VALUES {'text': 'stroke protocol', 'specialty': 'neurology'} USING HYBRID
INSERT INTO medical VALUES {'text': 'cardiac protocol', 'specialty': 'cardiology'} USING HYBRID

-- Verify
SHOW COLLECTION medical

Run with:

Run a QQL script

qql-go execute setup.qql qql-go execute --stop-on-error setup.qql