SQL-like query language and CLI for Qdrant vector database.
Write INSERT, SELECT, SEARCH, SCROLL, RECOMMEND, UPDATE, DELETE, and CREATE COLLECTION statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, grouped search (GROUP BY), cross-encoder reranking, quantization (scalar, turbo, binary, product), SQL-style WHERE filters, script execution, collection dump/restore, async execution, gRPC transport, parameterized queries, and batched query execution.
qql> INSERT INTO COLLECTION notes VALUES {'text': 'Qdrant is a vector database', 'author': 'alice', 'year': 2024}
✓ Inserted 1 point [3f2e1a4b-8c91-4d0e-b123-abc123def456]
qql> SEARCH notes SIMILAR TO 'vector storage engines' LIMIT 3 WHERE year >= 2023
✓ Found 1 result(s)
Score │ ID │ Payload
────────┼──────────────────────────────────────┼──────────────────────────────────────
0.8931 │ 3f2e1a4b-8c91-4d0e-b123-abc123def456 │ {'text': 'Qdrant is a ...', 'author': 'alice', 'year': 2024}
qql> SEARCH notes SIMILAR TO 'vector databases' LIMIT 5 USING HYBRID RERANK
✓ Found 1 result(s) (hybrid, reranked)
Score │ ID │ Payload
────────┼──────────────────────────────────────┼──────────────────────────────────────
5.3754 │ 3f2e1a4b-8c91-4d0e-b123-abc123def456 │ {'text': 'Qdrant is a ...', 'author': 'alice', 'year': 2024}
QQL is a thin translation layer between a SQL-like query language and the Qdrant Python client. Every statement you type goes through three stages:
Your query string
│
▼
[ Lexer ] — tokenizes the input into keywords, identifiers, literals
│
▼
[ Parser ] — builds a typed AST node (e.g. InsertStmt, SearchStmt)
│
▼
[ Executor ] — maps the AST node to a Qdrant client call
│
▼
Qdrant instance
When you run INSERT, the text field is automatically converted into a dense vector using Fastembed. In hybrid mode (USING HYBRID), a sparse BM25 vector is also generated alongside the dense vector, and searches use Qdrant's Reciprocal Rank Fusion (RRF) by default to merge the results of both retrieval methods. You can switch hybrid search to DBSF with FUSION 'dbsf'.
QQL also exposes a programmatic API for use inside Python applications — no CLI required. Use Connection for sync code, AsyncConnection for async apps, and batch helpers when you want QQL to combine compatible operations into fewer Qdrant requests:
from qql import Connection, QQLBatch
with Connection("http://localhost:6333") as conn:
conn.run_query("INSERT INTO COLLECTION notes VALUES {'text': 'Qdrant is fast'}")
result = conn.run_parameterized_query(
"SEARCH notes SIMILAR TO :query LIMIT 5",
{"query": "vector database"},
)
with QQLBatch(conn) as batch:
neurology = batch.add("SEARCH notes SIMILAR TO 'neurology' LIMIT 5")
cardiology = batch.add("SEARCH notes SIMILAR TO 'cardiology' LIMIT 5")
print(neurology.result.data, cardiology.result.data)Requirements: Python 3.12+, a running Qdrant instance.
pip install qql-cliConnect to a Qdrant instance:
# Local
qql connect --url http://localhost:6333
# Qdrant Cloud
qql connect --url https://<your-cluster>.qdrant.io --secret <your-api-key>
# Internal/self-signed certificate
qql connect --url https://<your-host>:6333 --secret <your-api-key> --ca-cert /path/to/ca.pem
# Disable TLS verification when you cannot provide a CA bundle
qql connect --url https://<your-host>:6333 --secret <your-api-key> --no-verifyThen type qql to open the interactive shell.
Full documentation lives in the docs/ folder and at pavanjava.github.io/qql:
| Topic | Description |
|---|---|
| Getting Started | Installation, connecting, first queries |
| INSERT / INSERT BULK | Adding documents, batch inserts, payload types |
| SEARCH / SELECT / SCROLL / RECOMMEND / Hybrid / GROUP BY / RERANK | Semantic search, grouped search, point retrieval, pagination, hybrid, reranking, recommendations |
| WHERE Filters | Full SQL-style filter operators |
| Collections & Quantization | SHOW, CREATE, DROP, QUANTIZE (scalar/turbo/binary/product), CREATE INDEX, UPDATE VECTOR, UPDATE PAYLOAD |
| Scripts: EXECUTE / DUMP | Script files, BEGIN BATCH blocks, collection backup/restore |
| Programmatic Usage | Sync/async Python APIs, parameterized queries, batching, gRPC |
| Reference: Models / Config / Errors | Embedding models, config file, error reference |
-- Insert
INSERT INTO COLLECTION articles VALUES {'text': '...', 'year': 2024}
INSERT BULK INTO COLLECTION articles VALUES [{'text': '...'}, {'text': '...'}]
-- Search
SEARCH articles SIMILAR TO 'query' LIMIT 10
SEARCH articles SIMILAR TO 'query' LIMIT 10 WHERE year >= 2020
SEARCH articles SIMILAR TO 'query' LIMIT 10 WHERE active = true
SEARCH articles SIMILAR TO 'query' LIMIT 10 WITH { mmr_diversity: 0.5, mmr_candidates: 50 }
SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID
SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID FUSION 'dbsf'
SEARCH articles SIMILAR TO 'query' LIMIT 10 WITH { indexed_only: true }
SEARCH articles SIMILAR TO 'query' LIMIT 10 WITH { quantization: { ignore: true, oversampling: 2 } }
SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID RERANK
-- Scroll
SCROLL FROM articles LIMIT 50
SCROLL FROM articles WHERE year >= 2024 LIMIT 50
SCROLL FROM articles AFTER 'cursor-id' LIMIT 50
-- Recommend
RECOMMEND FROM articles POSITIVE IDS (1001, 1002) LIMIT 5
-- Select (retrieve a point by ID)
SELECT * FROM articles WHERE id = '3f2e1a4b-...'
-- Collections
CREATE COLLECTION articles
CREATE COLLECTION articles HYBRID
CREATE COLLECTION articles WITH HNSW { payload_m: 16 }
CREATE COLLECTION articles WITH VECTORS { on_disk: true } WITH HNSW { full_scan_threshold: 10000 }
ALTER COLLECTION articles WITH OPTIMIZERS { indexing_threshold: 10000 }
ALTER COLLECTION articles WITH PARAMS { read_fan_out_factor: 4, on_disk_payload: false }
ALTER COLLECTION articles QUANTIZE DISABLED
CREATE COLLECTION articles QUANTIZE SCALAR
CREATE COLLECTION articles QUANTIZE TURBO
CREATE COLLECTION articles QUANTIZE TURBO BITS 2
CREATE COLLECTION articles QUANTIZE TURBO BITS 1.5 ALWAYS RAM
CREATE INDEX ON COLLECTION articles FOR year TYPE integer
CREATE INDEX ON COLLECTION articles FOR tenant_id TYPE keyword WITH { is_tenant: true, on_disk: true }
CREATE INDEX ON COLLECTION articles FOR doc_id TYPE uuid
CREATE INDEX ON COLLECTION articles FOR title TYPE text WITH { tokenizer: 'word', min_token_len: 2, lowercase: true }
SHOW COLLECTIONS
SHOW COLLECTION articles
DROP COLLECTION articles
-- Search with grouping
SEARCH articles SIMILAR TO 'query' LIMIT 5 GROUP BY category
SEARCH articles SIMILAR TO 'query' LIMIT 5 GROUP BY category GROUP_SIZE 3
SEARCH articles SIMILAR TO 'query' LIMIT 5 WHERE year >= 2020 GROUP BY category GROUP_SIZE 2
SEARCH articles SIMILAR TO 'query' LIMIT 5 USING HYBRID GROUP BY category
-- Update
UPDATE articles SET VECTOR WHERE id = '3f2e1a4b-...' [0.1, 0.2, 0.3, 0.4]
UPDATE articles SET PAYLOAD WHERE id = '3f2e1a4b-...' {'year': 2025, 'status': 'active'}
UPDATE articles SET PAYLOAD WHERE category = 'draft' {'status': 'published'}
-- Delete
DELETE FROM articles WHERE id = '3f2e1a4b-...'
DELETE FROM articles WHERE year < 2020
-- Scripts
EXECUTE /path/to/script.qql
DUMP articles /path/to/backup.qql
-- Batch block
BEGIN BATCH;
SEARCH articles SIMILAR TO 'query one' LIMIT 5;
SEARCH articles SIMILAR TO 'query two' LIMIT 5;
END BATCHTests do not require a running Qdrant instance — the Qdrant client is mocked.
pytest tests/ -vExpected: 635 tests passing.