qql-go and QQL Retrieval Operations for Qdrant

TL;DR

The Operations Gap: Relational databases have CLI tools (like psql) and migrations, but vector databases lack similar operational layers for regression testing and runbooks.

Declarative Retrieval: QQL (Qdrant Query Language) abstracts verbose, nested JSON REST/gRPC API payloads into standard, SQL-like declarative queries.

Operational CLI (qql-go): A portable Go binary designed to execute version-controlled .qql files, benchmark query recall, and assert constraints in CI.

Agent Tool Bound: Exposing a restricted, read-first CLI command surface is safer for autonomous agents than raw SDK access.

Introduction

QQL (Qdrant Query Language) is a declarative format for defining vector retrieval operations using SQL-like syntax instead of hand-written JSON payloads. The first thing developers notice about QQL is the cleanliness of its query syntax. But the deeper, more critical architecture story is retrieval operations: establishing a repeatable testing, benchmarking, and debugging framework around the vector database.

You can express semantic search, sparse token lookups, hybrid dense-sparse fusion, payload filters, and index topologies as short statements that humans, CI loops, and agents can easily parse and execute.

This post details the operational role of qql-go, tracing its origins next to Python QQL, and walking through its four core production workflows.

QQL Did Not Start With qql-go

QQL did not start in Go. The original project was created by Kameshwara Pavan Kumar Mantha as a SQL-like query language and CLI for Qdrant built on top of the Python SDK¹. It maps readable statements like SEARCH, INSERT, SCROLL, RECOMMEND, UPDATE, DELETE, and CREATE COLLECTION to the underlying database engine.

The Python implementation is a mature query engine. It supports hybrid dense-sparse queries, reranking logic, payload index creation, quantization, and data dump/restore scripts¹. It remains the optimal interface for notebooks, data-science scripts, and workflows inside the Python ecosystem.

qql-go is an independent Go implementation designed to translate those same language concepts into a single compile target². I maintain the Go CLI and contribute to the Python repository, meaning this is not a fork-versus-original conflict, but rather a single language idea running across different environments.

The operational boundaries split logically:

Qdrant SDKs: Expose the full client API inside your application’s hot path.
Python QQL: Powers interactive data-science notebooks, evaluation scripts, and Python orchestration.
qql-go: Serves as a single, zero-dependency binary with version-controlled .qql scripts, structured JSON output, and CLI assertions for CI and agent tools.

The SDK builds the application. QQL makes retrieval work readable. qql-go makes that work portable.

Why Retrieval Needs Operations Tooling

Traditional databases fail loudly. If a service runs out of memory or a database connection drops, your APM tools throw stack traces and trigger alerts. RAG systems, however, fail quietly.

A minor tweak in the chunking parameters moves the golden document from rank 3 to rank 11. An embedding model update improves average recall across 90% of requests but silently degrades performance on a subset of high-value corporate terms. A schema change on a metadata field quietly causes runtime filters to stop matching.

The application still returns 200 OK. The LLM continues generating confident, fluent prose. But the retrieval quality has degraded.

To solve this, operations teams must ask deterministic questions:

Did this critical query return the exact expected document ID?
How does hybrid search performance compare to dense-only or sparse-only search?
Are payload indexes still applied after a schema migration?
Did latency or retrieval sizes drift beyond our SLA thresholds?

Most teams solve this with ad hoc scripts and local notebooks. qql-go shifts this into a portable command line interface:

qql-go exec --quiet --json \
  "SEARCH docs SIMILAR TO 'refund policy' LIMIT 3 USING HYBRID"

This structured command can be checked into git, executed by cron jobs, or integrated directly into deployment checkouts.

Workflow 1: Retrieval Regression CI

The most valuable role for qql-go is acting as a regression check in your CI/CD pipeline.

GitHub Actions PR check failing on a qql-go retrieval regression test

When a pull request introduces updates to vector dimensions, chunking limits, or payload schemas, teams must verify that retrieval quality has not drifted. The release-validation example in the qql-go repository treats this as a test assertion gate⁵.

The expectations are codified in a JSON suite:

{
  "collection": "release_validation_docs",
  "collection_expect": {
    "topology": "hybrid",
    "min_points": 6,
    "payload_indexes": ["team", "title"]
  },
  "checks": [
    {
      "id": "04-hybrid-refund",
      "command": "exec",
      "statement": "SEARCH release_validation_docs SIMILAR TO 'refund policy for annual plan' LIMIT 3 USING HYBRID",
      "expect": {
        "min_results": 3,
        "hybrid": true,
        "top_ids": ["1101"]
      }
    }
  ]
}

This JSON file ensures the target collection meets basic requirements (hybrid setup, minimum document counts, index coverage) and asserts that a hybrid query for "refund policy for annual plan" returns document 1101 in the top 3 positions.

GitHub Actions then pulls the qql-go binary and executes the suite against the staging database:

name: retrieval-regression

on:
  pull_request:
    paths:
      - "examples/release-validation/**"
      - ".github/workflows/retrieval-regression.yml"

jobs:
  retrieval-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install qql-go
        run: |
          INSTALL_DIR="$RUNNER_TEMP/bin" curl -fsSL https://raw.githubusercontent.com/srimon12/qql-go/main/install.sh | sh
          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"

      - name: Run retrieval regression against existing Qdrant
        env:
          QDRANT_URL: ${{ secrets.QDRANT_URL }}
          QDRANT_API_KEY: ${{ secrets.QDRANT_API_KEY }}
        run: bash examples/release-validation/run-demo.sh

Because qql-go emits standard, machine-readable JSON artifacts, CI can fail the build and output a clean diff showing which document ID fell out of the rankings.

Workflow 2: Retrieval Debug Runbooks

When a customer reports a search regression, support and on-call engineers need a structured sequence to isolate the issue. Running local scripts or checking out notebooks is slow and introduces security risks around database credentials.

A retrieval-debug-runbook using qql-go enables engineers to analyze the vector stack systematically⁵:

Terminal output of qql-go executing a hybrid search debug runbook

# 1. Verify connection and cluster health
qql-go doctor --quiet --json

# 2. Inspect target collection schema
qql-go exec --quiet --json \
  "SHOW COLLECTION retrieval_debug_runbook"

# 3. Explain the vector query execution plan
qql-go explain --quiet --json \
  "SEARCH retrieval_debug_runbook SIMILAR TO 'billing policy search regression after index removal' LIMIT 3 USING HYBRID"

# 4. Compare search modes side-by-side
qql-go exec --quiet --json \
  "SEARCH retrieval_debug_runbook SIMILAR TO 'billing policy search regression after index removal' LIMIT 3 USING HYBRID"

qql-go exec --quiet --json \
  "SEARCH retrieval_debug_runbook SIMILAR TO 'billing policy search regression after index removal' LIMIT 3 USING SPARSE"

qql-go exec --quiet --json \
  "SEARCH retrieval_debug_runbook SIMILAR TO 'billing policy search regression after index removal' LIMIT 3 EXACT"

# 5. Rerun with a metadata filter
qql-go exec --quiet --json \
  "SEARCH retrieval_debug_runbook SIMILAR TO 'billing policy search regression after index removal' LIMIT 3 USING HYBRID WHERE team = 'billing'"

# 6. Select and view the expected document directly
qql-go exec --quiet --json \
  "SELECT * FROM retrieval_debug_runbook WHERE id = 4104"

This runbook traces the problem down the stack: checking cluster health, verifying payload index topology, explaining the query weights, comparing retrieval modes (dense, sparse, exact), evaluating filters, and inspecting the raw document payload.

Because the tool outputs structured JSON, engineers can easily copy the diagnostics directly into incident logs.

Workflow 3: Agent-Safe Retrieval for Qdrant

Exposing full SDK access to runtime AI coding agents or sidecar agents presents a security hazard. If the agent’s prompt is injected or if it suffers from a logical error, it can run commands to delete collections or drop indexes.

A restricted, single-purpose CLI like qql-go provides a secure, read-first wrapper around the database:

qql-go exec --quiet --json \
  "SHOW COLLECTION docs"

qql-go explain --quiet --json \
  "SEARCH docs SIMILAR TO 'HIPAA policy' LIMIT 5 USING HYBRID"

qql-go exec --quiet --json \
  "SEARCH docs SIMILAR TO 'HIPAA policy' LIMIT 5 USING HYBRID WHERE department = 'compliance'"

For an agent, this interface is highly structured:

Declarative String: The model writes a single query line rather than compiling nested SDK payloads.
Stable JSON Output: Predictable parsing with no regex extraction needed.
Controlled Capabilities: Command permissions can be restricted to read-only statements (SEARCH, SCROLL, SELECT), preventing any state-modifying database operations.

This separation of database operations from raw SDK access aligns with modern agent tool boundaries and zero-trust guidelines⁶⁷.

Workflow 4: Benchmark Packs for Retrieval Quality

Determining whether to use dense search, sparse vectors, or hybrid RRF/DBSF requires testing parameters against real evaluation sets.

The medical-retrieval-ops benchmark in the qql-go repository provisions a medical QA corpus from ChatMED-Project/RAGCare-QA, imports it into Qdrant, and runs evaluation checks across multiple search configurations⁵:

medical-retrieval-ops/
├── 01-provision.qql
├── build-medical-corpus.py
├── generated/
│   ├── 02-seed.qql
│   ├── benchmark-questions.json
│   └── eval.json
├── run-demo.sh
├── run-benchmark.sh
└── artifacts/

Expressing the benchmark workspace as a set of version-controlled .qql files and scripts ensures reproducibility. Teams can run the benchmark suites offline, verifying how updates to sharding, distance functions, or threshold scoring impact recall metrics before deploying changes to production⁸⁹.

QQL Files Make Retrieval Work Reviewable

Retrieval configurations and schema setups should live in version control alongside application code. With qql-go, these setups are stored as .qql files:

CREATE COLLECTION docs HYBRID

CREATE INDEX ON COLLECTION docs FOR department TYPE keyword
CREATE INDEX ON COLLECTION docs FOR doc_type TYPE keyword

SEARCH docs SIMILAR TO 'refund policy' LIMIT 3 USING HYBRID
SEARCH docs SIMILAR TO 'billing portal invoice download' LIMIT 3 USING SPARSE
SEARCH docs SIMILAR TO 'security compliance and audit logs' LIMIT 6 USING HYBRID GROUP BY department GROUP_SIZE 2

Automation then executes the scripts:

qql-go execute --stop-on-error smoke-tests.qql

This is not designed to replace infrastructure-as-code tools like Terraform. It is for database migrations and schema seeds: explicit, version-controlled scripts that define your retrieval setup and verify index health.

Where qql-go Fits

To maintain a clean database boundary, keep the operational split clear:

Tooling Layer	Primary Use Case	Target Persona	Deployment Mode
Qdrant SDK	Application hot path, low-latency search	Developers	Application container
Python QQL	Evaluation notebooks, data cleaning, pipelines	Data Scientists	Python runtime env
qql-go	CI checks, runbooks, benchmarks, agent tools	SREs & Agents	Zero-dependency CLI

qql-go is not an ORM or a full database engine driver. It is a compact, operational interface designed to make retrieval quality, testing, and debugging repeatable.

The syntax makes Qdrant queries readable. The compiled CLI makes retrieval operations repeatable.

A Practical Starting Workflow

If you want to adopt retrieval operations, start small:

Create a read-only regression suite: Identify the core queries that are business-critical to your product.
Codify five target queries: Store the query statements and expected results in a regression-suite.json file.
Run validation in CI: Execute qql-go against your staging database on every pull request.
Build support runbooks: Replace ad hoc debugging scripts with structured qql-go sequences.

retrieval/
├── regression-suite.json
├── smoke-tests.qql
└── run-regression.sh

The commands can be simple too:

qql-go doctor --quiet --json
qql-go exec --quiet --json "SHOW COLLECTION docs"
qql-go execute --stop-on-error smoke-tests.qql

A small, maintained regression suite and a few structured runbooks will capture most retrieval regressions before they impact production users.

Conclusion

QQL is not a single code repository. It is a language concept: making vector database operations readable, versionable, and repeatable.

The original Python QQL proves the design’s readability. The Qdrant SDKs remain the correct choice for application code. qql-go explores what happens when we package that query language into a zero-dependency operational layer: providing versioned scripts, CI checks, support runbooks, and a restricted tool boundary for agents.

To dive deeper into setting up and using QQL, explore the QQL Go Official Documentation(opens in a new tab)¹⁰ or check out the codebase on GitHub(opens in a new tab)² (and specifically the gateway compiler(opens in a new tab)¹¹).

If you are working on the ingestion side of retrieval quality, RAG Chunking Visualizer in Rust (WebAssembly) is the upstream companion. If you care about agent execution boundaries, Governed Code Mode is the adjacent runtime story. And if your retrieval layer is becoming a maintained knowledge system, Schema-First Extraction for LLM Wikis is the next layer up.

References

Kameshwara Pavan Kumar Mantha. “QQL - Qdrant Query Language.” GitHub. https://github.com/pavanjava/qql(opens in a new tab) ↩ ↩²
Srimon Danguria. “qql-go - A Single-Binary Operational CLI for Qdrant.” GitHub. https://github.com/srimon12/qql-go(opens in a new tab) ↩ ↩²
Evidently AI. “A complete guide to RAG evaluation: metrics, testing and best practices.” https://www.evidentlyai.com/llm-guide/rag-evaluation(opens in a new tab) ↩
Braintrust. “RAG evaluation metrics: How to evaluate your RAG pipeline with Braintrust.” https://www.braintrust.dev/articles/rag-evaluation-metrics(opens in a new tab) ↩
Srimon Danguria. “qql-go examples.” GitHub. https://github.com/srimon12/qql-go/tree/main/examples(opens in a new tab) ↩ ↩² ↩³
xpander.ai. “MCP vs CLI for AI Agents.” https://xpander.ai/resources/mcp-vs-cli-for-ai-agents(opens in a new tab) ↩
Endor Labs. “Introducing Agent Governance: Using Hooks to Bring Visibility to AI Coding Agents.” https://www.endorlabs.com/learn/introducing-agent-governance-using-hooks-to-bring-visibility-to-ai-coding-agents(opens in a new tab) ↩
Qdrant. “Hybrid Queries.” https://qdrant.tech/documentation/search/hybrid-queries/(opens in a new tab) ↩
Qdrant. “Hybrid Search and the Universal Query API.” https://qdrant.tech/course/essentials/day-3/hybrid-search/(opens in a new tab) ↩
Srimon Danguria. “qql-go official documentation.” Veristamp. https://qql-go.veristamp.in/docs(opens in a new tab) ↩
Srimon Danguria. “qql-go gateway compiler code.” GitHub. https://github.com/srimon12/qql-go/tree/main/server(opens in a new tab) ↩