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
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 Aug 30, 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:
Newer release available (0.3.1)

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 Aug 30, 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.0-cp310-abi3-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.10+Windows x86-64

pyqql-0.3.0-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.0-cp310-abi3-macosx_11_0_arm64.whl (3.1 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

pyqql-0.3.0-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.0-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: pyqql-0.3.0-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.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 8187b87b246c1e62c4eab71cfcc2dfa3630091c496489d8c0a33c263fc2dda02
MD5 e315c6b4ef1ad943e14f163d407e1fe1
BLAKE2b-256 c2c049a782e890de3e68ae969b54e7bbfedbb2386f98c8349c62180c18183985

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.3.0-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.0-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqql-0.3.0-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 1128b32d177cf5b797f31a525e160f1da426ab7b86360d152c74c22daa4e6070
MD5 e173ea81a2d3c22e14deff245d447436
BLAKE2b-256 ee99b6b273f44e94bd2bd25c3399c8532b221765fd38b78ac6a49e53c15a5351

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.3.0-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.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pyqql-0.3.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f9ba69fc7d11c9c8e229420352a2f9145ea08c499b0800f17e6d8c2a9d65acbd
MD5 ffd4f6312aff926782fdb2292fd85441
BLAKE2b-256 d125eb724554f404095bf77d0ce9c66164926cdfc845aea98e8cce215119efef

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.3.0-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.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pyqql-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 63db63cefe9b74bdb0c00e587dc96ef66cf46d0c8676fceafff14aa9a471ba7b
MD5 92fb701705dfc1247a7c1e2ec8d86c4e
BLAKE2b-256 ef83cd3fce3c191a11d90d82fd8e718fc61dbbb73751642206894f04a34c719a

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.3.0-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

0.3.1

4 files

This release

0.3.0 This release

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