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.8+ (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

Export Role
Client(url, api_key=None, use_grpc=False, embedder=None, route_affinity=None) Execute against Qdrant
HttpEmbedder(endpoint, model, dimension, api_key="") OpenAI-compatible embeddings
parse / parse_json / is_valid / tokenize Frontend — is_valid is the full gate (parse + plan), matching execution and the language conformance suite
inject_filter(query|Stmt, field, op, value) Host isolation (AST)
Stmt.shard_key Same field as QQL SHARD '…' (get/set; no inject_shard_key)
compile_query / explain Offline plan / REST projection
bind(query, params) Substitute :name (dict) or ? (list)
execute / execute_async One-shot free functions (params= same as bind)

inject_filter operators

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

Isolation vs routing

Concern API Wire
Isolation inject_filter / WHERE REST/gRPC Filter
Routing SHARD '…' or stmt.shard_key REST shard_key / gRPC ShardKeySelector
Partition DDL CREATE SHARD KEY '…' Admin shard-key API

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

Docs

Project links

Data verified by PyPI on Sep 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for srimon12 from gravatar.com srimon12

Credits

Author: Srimon Danguria

GitHub Statistics

Data verified by PyPI on Sep 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Tags

qql qdrant vector-search query-language database

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

pyqql-0.3.1-cp310-abi3-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.10+Windows x86-64

pyqql-0.3.1-cp310-abi3-manylinux_2_28_x86_64.whl (3.4 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ x86-64

pyqql-0.3.1-cp310-abi3-macosx_11_0_arm64.whl (3.1 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

pyqql-0.3.1-cp310-abi3-macosx_10_12_x86_64.whl (3.2 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file pyqql-0.3.1-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: pyqql-0.3.1-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 3.5 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyqql-0.3.1-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 8016efd6ec5d893cb405e3dc5ab9a6e0ed7ae70144fc9b96b9153b66c2e982e0
MD5 7b82174b38c9e596ff3342dd85fb0b9b
BLAKE2b-256 9c1c3f2b0dfecabcb144e01fa9289c06fd029f86ba0f8933b9cb99f942fb1124

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.3.1-cp310-abi3-win_amd64.whl:

Publisher: release.yml on srimon12/qql-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqql-0.3.1-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqql-0.3.1-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 310b97a3886b4e989ea74f8b0034c0fb1a3e5078b8a6dfb081d2d0c76034e172
MD5 239021daaf82d6095f33753b6aef1753
BLAKE2b-256 f211fa07d7aaf19fbd98b98597c4cf15855d6f6d324327224580eca94ea7fc97

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.3.1-cp310-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on srimon12/qql-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqql-0.3.1-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pyqql-0.3.1-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6ef1846c02220e704f2b968234f07e6615ab8e183144d51c27c31c09f63168e6
MD5 63fb4bccaa6bbd21ec9865888a3a5bc5
BLAKE2b-256 52ac743112880b53aaa9fee3a6b21da454c7aec36d2f36b42d6f5bcad4051947

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.3.1-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on srimon12/qql-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqql-0.3.1-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pyqql-0.3.1-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 2adfab5aaa884fda9e74328445bf8054b5b8fe4bb08b31f441f4057a6959a75c
MD5 387f0c9a83e7051f1d128ff9a6328378
BLAKE2b-256 b92af5a2c7558e07d31586bd0874158987aad966d8862aadfed284772634e5d9

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.3.1-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on srimon12/qql-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.3.1 This release

4 files

0.3.0

4 files

0.2.1

4 files

0.2.0

4 files

0.1.5

4 files

0.1.4

4 files

0.1.3

4 files

0.1.2

4 files

0.1.1

4 files

0.1.0

4 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page