Python SDK

pyqql exposes native QQL statement handles while keeping the Python API small: parse source, inspect or mutate a statement, then execute it with a client.

Install the remote client

pip install pyqql

QQLScoped medical-record searchTry in playground

QUERY TEXT 'cardiology'
FROM medical_records
USING dense
LIMIT 5;

Execute and inspect the report

Client.execute returns an execution-report dictionary with ok, results, succeeded, and failed keys. A script may contain multiple semicolon-delimited statements.

from pyqql import Client

client = Client("http://localhost:6333")
report = client.execute(query)

if not report["ok"]:
    raise RuntimeError(report)

print(report["succeeded"], report["failed"])

Parse, isolate, and route

Use an AST predicate for isolation. Assign a shard key only when the host also knows the Qdrant routing partition. The full per-statement behavior of inject_filter is described in the Filter injection guide.

from pyqql import Client, parse

client = Client("http://localhost:6333")
stmt = parse(query)[0]
stmt.inject_filter("tenant_id", "=", "hospital-7")
stmt.shard_key = "hospital-7"

report = client.execute(stmt)

Only =, >, >=, <, and <= are supported by policy injection. Do not substitute != for an exclusion rule; model that rule in the source query.

Plan before you send traffic

from pyqql import compile_query, explain, tokenize

route = compile_query(query)
print(route["method"], route["path"])
print(explain(query))
print(tokenize(query))

API	Returns	Use it when
`Client(url, api_key, use_grpc, embedder)`	client	Configure remote execution once
`Client.execute` / `execute_async`	report dictionary	Execute source, statements, or an array; choose sync or async host flow
`Client.explain` / `Client.compile`	plan or route dictionary	Inspect work before executing it
`parse(source)`	`list[Stmt]`	You need to inspect or mutate a statement
`Stmt.inject_filter`, `Stmt.shard_key`	mutated statement	Enforce a predicate and optionally choose routing
`Stmt.to_dict` / `Stmt.to_json`	AST representation	Log or inspect the rewritten statement
`is_valid`, `tokenize`, `explain`	boolean, tokens, plan	Lightweight strict parser tools
`compile_query`	route dictionary	Obtain the Qdrant method, path, and payload
`inject_filter` / `execute`	host-friendly convenience result	One-shot transform or execution
`HttpEmbedder`	embedder object	Supply a remote embedding model