pyqql

Native Python bindings for QQL (parser, plan, execute) via PyO3.

Proposition

Write Qdrant operations as QQL instead of hand-built JSON. Same language as the CLI and other SDKs: hybrid search, multitenancy (inject_filter + SHARD), schema-as-code, REST or gRPC. Language surface tracks Qdrant ≥ 1.19 (quotas, memory placement, MATCH PREFIX / SLICE, sparse idf, turbo4).

Install

pip install pyqql

Python 3.10+ (stable ABI wheels). REST + gRPC included.

Quick start

import pyqql

embedder = pyqql.HttpEmbedder(
    endpoint="http://localhost:11434/v1/embeddings",
    model="all-minilm:l6-v2",
    dimension=384,
)
client = pyqql.Client("http://localhost:6333", embedder=embedder)

report = client.execute(
    "QUERY TEXT 'cardiology' FROM medical_records USING dense LIMIT 5"
)
print(report)  # ExecutionReport: ok, results[], succeeded, failed

# Isolation (always on untrusted QQL)
stmt = pyqql.parse("QUERY TEXT 'risks' FROM sec10k USING dense LIMIT 10")[0]
pyqql.inject_filter(stmt, "tenant_id", "=", "honeywell")

# Routing (custom sharding): prefer SHARD in QQL, or set after parse
#   QUERY ... SHARD 'honeywell' LIMIT 10
stmt.shard_key = "honeywell"
client.execute(stmt)

API summary

inject_filter operators

Accepted: =, >, >=, <, <= (and aliases).
Rejected: !=, IN, … — write those in QQL or inject equality only.

Isolation vs routing

Qdrant 1.19 notes

# Quotas: REST only (default Client URL :6333). use_grpc=True → QQL-GRPC-QUOTA
client.execute("SHOW QUOTAS")
client.execute(
    "SET QUOTA (enabled = true, max_resident_memory_percent = 80, "
    "max_disk_usage_percent = 90, release_margin_percent = 5) WAIT true"
)

# Filters / DDL that require Qdrant ≥ 1.19
client.execute(
    "CREATE INDEX ON COLLECTION docs FOR title TYPE keyword "
    "WITH (prefix = true, memory = 'cached')"
)
client.execute(
    "QUERY TEXT 'q' FROM docs USING dense WHERE title MATCH PREFIX 'Comp' LIMIT 5"
)
client.execute(
    "QUERY TEXT 'q' FROM docs USING sparse PARAMS (idf = 'global') LIMIT 5"
)
client.execute(
    "QUERY TEXT 'q' FROM docs USING sparse "
    "WHERE tenant_id = 'acme' SHARD 'acme' "
    "PARAMS (idf = WHERE tenant_id = 'acme') LIMIT 5"
)

SET QUOTA is a full replace of the cluster config.

Route affinity (Qdrant 1.19+)

Pin reads to a stable replica with route_affinity at construction — sent as the X-Qdrant-Route-Affinity header (REST) / x-qdrant-route-affinity metadata (gRPC). Empty string is treated as unset. Readable via client.route_affinity.

client = pyqql.Client("http://localhost:6333", route_affinity="session-acme-42")
print(client.route_affinity)  # "session-acme-42"
# One-shot convenience:
pyqql.execute("SHOW COLLECTIONS", url="http://localhost:6333", route_affinity="session-acme-42")

Execution report

{
  "ok": True,
  "results": [{"ok": True, "operation": "QUERY", "message": "…", "data": …}],
  "succeeded": 1,
  "failed": 0,
}

on_error="stop" (default) or "continue".

Formula queries vs Qdrant SDK FormulaQuery

In QQL, custom formula scoring is declarative SQL-like syntax executed directly:

report = client.execute("""
    QUERY FORMULA score * 0.8 + LOG(views + 1.0) * 0.2
    DEFAULTS (score = 0.0, views = 0)
    FROM articles
    LIMIT 10
""")

Important: Do not wrap QQL strings in qdrant_client.models.FormulaQuery! In the official Qdrant Python SDK, FormulaQuery expects an object tree of Expression classes (e.g. models.SumExpression(...)), not query text. Pass formula queries directly to client.execute().

Shell quoting: Prefer bare score instead of $score. While $score works inside Python strings, POSIX shells (bash, zsh) interpolate $score into "" when run via CLI or shell scripts. Bare score is shell-safe across all environments.

Docs

• Syntax · Filters · inject_filter
• Multitenancy · Python skill