Scripting

QQL supports multi-statement script files for automating setup, migrations, and operational workflows.

Script Format

Scripts are plain text files with .qql extension. Statements are separated by newlines. Comments start with --.

-- my-workflow.qql

-- Setup collection
CREATE COLLECTION docs HYBRID
  WITH HNSW (m = 32, ef_construct = 100)
  WITH QUANTIZATION (type = 'scalar')

-- Create indexes
CREATE INDEX ON docs FOR category TYPE keyword
CREATE INDEX ON docs FOR year TYPE integer

-- Insert data
INSERT INTO docs VALUES {'id': 1, 'text': 'First document', 'category': 'tech', 'year': 2024} USING HYBRID
INSERT INTO docs VALUES {'id': 2, 'text': 'Second document', 'category': 'science', 'year': 2025} USING HYBRID

-- Verify
SHOW COLLECTION docs
SCROLL FROM docs LIMIT 5

No Semicolons

Do not use semicolons between statements. Each statement must be on its own line.

Execute a Script

Execute a QQL script

qql-go execute my-workflow.qql
Stop on first error (recommended for setup scripts)Section titled “Stop on first error (recommended for setup scripts)”
qql-go execute --stop-on-error my-workflow.qql
Structured JSON outputSection titled “Structured JSON output”
qql-go execute --quiet --json my-workflow.qql

Collection Dump

Export a collection as a runnable QQL script:

Dump a collection

qql-go dump docs backup.qql
Control batch size (default: 100 points per INSERT statement)Section titled “Control batch size (default: 100 points per INSERT statement)”
qql-go dump --batch-size 500 docs backup.qql
JSON outputSection titled “JSON output”
qql-go dump --quiet --json docs backup.qql

The dump output includes:

• CREATE COLLECTION statement with all config (HNSW, quantization, named vectors)
• CREATE INDEX statements for all payload indexes
• INSERT INTO ... VALUES statements for all points (batched)

REPL Shortcuts

From the interactive REPL:

REPL shortcuts

\e <file>                    Execute a .qql file \dump <collection> <file>    Dump a collection to a .qql file
Example sessionSection titled “Example session”
qql-go repl
\e setup.qql \dump docs backup.qql

Use Cases

Script	Purpose
create-collection.qql	Provision a collection with indexes
seed-data.qql	Insert test or seed data
backup.qql	Full collection export (from dump)
migration.qql	Schema or data migration
regression.qql	CI smoke test queries
cleanup.qql	Drop collections after testing

CI Integration

.github/workflows/smoke-test.yml

- name: Run QQL smoke tests
  run: |
    qql-go connect --url ${{ secrets.QDRANT_URL }} --secret ${{ secrets.QDRANT_SECRET }}
    qql-go execute --stop-on-error --quiet --json examples/release-validation/validate.qql

Script from Go SDK

// Run a script file via ExecBatch
lines := readLines("workflow.qql") // strip comments, split by newline
results, err := qql.ExecBatch(ctx, client, lines, true)