qql-cli 2.0.0

QQL is a SQL-like query language and CLI for Qdrant vector database. Write INSERT, SEARCH, RECOMMEND, DELETE, and CREATE COLLECTION statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, binary, product), WHERE clause filters, script execution, and collection dump/restore.

QQL — Qdrant Query Language

SQL-like query language and CLI for Qdrant vector database.

Write INSERT, SEARCH, RECOMMEND, DELETE, and CREATE COLLECTION statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, binary, product), SQL-style WHERE filters, script execution, and collection dump/restore.

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}

---

How It Works

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) to merge the results of both retrieval methods.

---

Installation

Requirements: Python 3.12+, a running Qdrant instance.

pip install qql-cli

Connect 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>

Then type qql to open the interactive shell.

---

Documentation

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 / RECOMMEND / Hybrid / RERANK	Semantic search, hybrid, reranking, recommendations
WHERE Filters	Full SQL-style filter operators
Collections & Quantization	CREATE, DROP, QUANTIZE (scalar/binary/product), CREATE INDEX
Scripts: EXECUTE / DUMP	Script files, collection backup/restore
Programmatic Usage	Use QQL as a Python library
Reference: Models / Config / Errors	Embedding models, config file, error reference

---

Quick Syntax 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 USING HYBRID
SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID RERANK

-- Recommend
RECOMMEND FROM articles POSITIVE IDS (1001, 1002) LIMIT 5

-- Collections
CREATE COLLECTION articles
CREATE COLLECTION articles HYBRID
CREATE COLLECTION articles QUANTIZE SCALAR
CREATE INDEX ON COLLECTION articles FOR year TYPE integer
SHOW COLLECTIONS
DROP COLLECTION articles

-- 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

---

Running Tests

Tests do not require a running Qdrant instance — the Qdrant client is mocked.

pytest tests/ -v

Expected: 375 tests passing.

---

License

MIT © Kameshwara Pavan Kumar Mantha