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
`execute` / `execute_async`	One-shot free functions

`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"
)

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

Syntax · Filters · inject_filter
Multitenancy · Python skill

Development Status
- 3 - Alpha
Programming Language
- Python :: 3
- Rust
Typing
- Typed

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.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pyqql-0.2.1-cp38-abi3-win_amd64.whl (3.5 MB view details)

Uploaded Aug 24, 2026 CPython 3.8+Windows x86-64

pyqql-0.2.1-cp38-abi3-manylinux_2_28_x86_64.whl (3.4 MB view details)

Uploaded Aug 24, 2026 CPython 3.8+manylinux: glibc 2.28+ x86-64

pyqql-0.2.1-cp38-abi3-macosx_11_0_arm64.whl (3.1 MB view details)

Uploaded Aug 24, 2026 CPython 3.8+macOS 11.0+ ARM64

pyqql-0.2.1-cp38-abi3-macosx_10_12_x86_64.whl (3.2 MB view details)

Uploaded Aug 24, 2026 CPython 3.8+macOS 10.12+ x86-64

File details

Details for the file pyqql-0.2.1-cp38-abi3-win_amd64.whl.

File metadata

Download URL: pyqql-0.2.1-cp38-abi3-win_amd64.whl
Upload date: Aug 24, 2026
Size: 3.5 MB
Tags: CPython 3.8+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyqql-0.2.1-cp38-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`af91d61f9e9fe57e08e704785e5c28e66d328749a1e84e7be25093426f03df98`
MD5	`6926efe1a75a68c30566adb9a7facff5`
BLAKE2b-256	`0fa5e649f819c58474ab2daad5e590bf80054cd77e4d2754c6b0a5a15c64aafd`

See more details on using hashes here.

Provenance

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pyqql-0.2.1-cp38-abi3-win_amd64.whl
- Subject digest: af91d61f9e9fe57e08e704785e5c28e66d328749a1e84e7be25093426f03df98
- Sigstore transparency entry: 2579318396
- Sigstore integration time: Aug 24, 2026
Source repository:
- Permalink: srimon12/qql-rs@45356210e8f58df15118e15ec871f06045c6627a
- Branch / Tag: refs/tags/v0.2.1
- Owner: https://github.com/srimon12
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@45356210e8f58df15118e15ec871f06045c6627a
- Trigger Event: push

File details

Details for the file pyqql-0.2.1-cp38-abi3-manylinux_2_28_x86_64.whl.

File metadata

Download URL: pyqql-0.2.1-cp38-abi3-manylinux_2_28_x86_64.whl
Upload date: Aug 24, 2026
Size: 3.4 MB
Tags: CPython 3.8+, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyqql-0.2.1-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`bc8148c8e7b9481301d1af523e6592df28926d95c0d668cfbe0b3d070eed0815`
MD5	`dcd60d951b5eb0c1cfb705aa6ea4e4cb`
BLAKE2b-256	`42b340d0d1c74682d12b26f86466223d28a71fbb10ba27e109a3362e838cab79`

See more details on using hashes here.

Provenance

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pyqql-0.2.1-cp38-abi3-manylinux_2_28_x86_64.whl
- Subject digest: bc8148c8e7b9481301d1af523e6592df28926d95c0d668cfbe0b3d070eed0815
- Sigstore transparency entry: 2579318390
- Sigstore integration time: Aug 24, 2026
Source repository:
- Permalink: srimon12/qql-rs@45356210e8f58df15118e15ec871f06045c6627a
- Branch / Tag: refs/tags/v0.2.1
- Owner: https://github.com/srimon12
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@45356210e8f58df15118e15ec871f06045c6627a
- Trigger Event: push

File details

Details for the file pyqql-0.2.1-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: pyqql-0.2.1-cp38-abi3-macosx_11_0_arm64.whl
Upload date: Aug 24, 2026
Size: 3.1 MB
Tags: CPython 3.8+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyqql-0.2.1-cp38-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`4b4672009d85a8a43f79021b073c6229d47e2582eb9b0c0d453d792f8faf56e3`
MD5	`c2bd0a1948000dca81564508888f5f1b`
BLAKE2b-256	`eb0fe6e118c615afa198dd593a8b7d4dca2cc390ec121ccd86b4526b3defc9bb`

See more details on using hashes here.

Provenance

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pyqql-0.2.1-cp38-abi3-macosx_11_0_arm64.whl
- Subject digest: 4b4672009d85a8a43f79021b073c6229d47e2582eb9b0c0d453d792f8faf56e3
- Sigstore transparency entry: 2579318399
- Sigstore integration time: Aug 24, 2026
Source repository:
- Permalink: srimon12/qql-rs@45356210e8f58df15118e15ec871f06045c6627a
- Branch / Tag: refs/tags/v0.2.1
- Owner: https://github.com/srimon12
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@45356210e8f58df15118e15ec871f06045c6627a
- Trigger Event: push

File details

Details for the file pyqql-0.2.1-cp38-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: pyqql-0.2.1-cp38-abi3-macosx_10_12_x86_64.whl
Upload date: Aug 24, 2026
Size: 3.2 MB
Tags: CPython 3.8+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyqql-0.2.1-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`78d657f1b6cf2d1a9ccdeec03e1bfdee15d6638b84f1af473eaa49d8199b5c18`
MD5	`8c5fbe5e59e03624add25d0bd1dfbd52`
BLAKE2b-256	`eee7753e04a7f1d6fa6c5215af0a0c06b16b887e661b2f30f7ad461a08f3ab60`

See more details on using hashes here.

Provenance

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pyqql-0.2.1-cp38-abi3-macosx_10_12_x86_64.whl
- Subject digest: 78d657f1b6cf2d1a9ccdeec03e1bfdee15d6638b84f1af473eaa49d8199b5c18
- Sigstore transparency entry: 2579318393
- Sigstore integration time: Aug 24, 2026
Source repository:
- Permalink: srimon12/qql-rs@45356210e8f58df15118e15ec871f06045c6627a
- Branch / Tag: refs/tags/v0.2.1
- Owner: https://github.com/srimon12
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@45356210e8f58df15118e15ec871f06045c6627a
- Trigger Event: push