pyqql

Native Python bindings for the Qdrant Query Language (QQL) parser, router, and execution engine, compiled with PyO3 0.23.

Features

  • Live Qdrant Execution: Connect to live Qdrant instances over REST (default) or gRPC
  • Automated Embedding Inference: Integrate custom HTTP embedder models (Ollama, OpenAI, vLLM, TEI) for text-to-vector search
  • Zero-Copy Route Lowering: Lower QQL queries to typed { method, path, payload } route dicts via compile_query
  • Native parsing: Rust-speed QQL parsing in Python returning typed Stmt objects or Python dicts
  • Filter injection: Add tenant isolation filters programmatically
  • Smart batching: Auto-batches contiguous same-collection query/mutation statements into single network calls
  • Shard key: Read/write the shard key on QUERY, COUNT, SCROLL, UPSERT, and DELETE statements
  • Validation: Check if a query string is valid QQL

Compatibility

  • Python 3.8+: Published wheels use Python's stable ABI (abi3-py38) and support Python 3.8 and newer.
  • REST and gRPC: Published wheels include both transports by default.

Installation

pip install pyqql

Quick Start

import pyqql

# 1. Connect to live Qdrant with optional custom embedding provider (e.g. Ollama)
embedder = pyqql.HttpEmbedder(
    endpoint="http://localhost:11434/v1/embeddings",
    model="all-minilm:l6-v2",
    dimension=384,
    api_key=""
)

client = pyqql.Client(
    url="http://localhost:6333",
    api_key="optional-qdrant-secret",
    use_grpc=False,
    embedder=embedder
)

# Execute QQL query (auto-embeds text to vector)
result = client.execute("QUERY 'cardiology' FROM medical_records USING dense LIMIT 5")
print(result)

# Async variant
future = client.execute_async("QUERY 'cardiology' FROM medical_records USING dense LIMIT 5")

# Explain query execution plan
plan = client.explain("QUERY 'cardiology' FROM medical_records USING dense LIMIT 5")
print(plan)

# 2. Pure AST Parsing & Filter Injection
stmt = pyqql.parse("QUERY 'vector database' FROM docs USING dense LIMIT 10")[0]
valid = pyqql.is_valid("QUERY 'test' FROM docs")
secured_stmt = pyqql.inject_filter("QUERY 'patients' FROM medical LIMIT 5", "org_id", "=", "acme-corp")

# 3. Working with Stmt objects
ast_dict = stmt.to_dict()                    # Python dict
ast_json = stmt.to_json()                    # JSON string
stmt.shard_key = "shard-01"                  # setter (QUERY/COUNT/SCROLL/UPSERT/DELETE only)
stmt.inject_filter("tenant_id", "=", "acme") # mutate in-place

# 4. Free-function execute (convenience)
result = pyqql.execute("SHOW COLLECTIONS", url="http://localhost:6333")

# 5. Lower to Qdrant route without executing
route = pyqql.compile_query("QUERY 'search' FROM docs LIMIT 10")
# route = { "method": "POST", "path": "/collections/docs/points/query", "payload": {...} }

All execution methods return an ExecutionReport dict: {"ok": bool, "results": list, "succeeded": int, "failed": int}. The results list always contains one entry per executed statement.

API Summary

Export Description
Client(url, api_key, use_grpc, embedder) Client for executing QQL against a live Qdrant database
HttpEmbedder(endpoint, model, dimension, api_key) First-class HTTP embedding provider configuration
Stmt Parsed statement object with inject_filter(), to_json(), to_dict(), shard_key property
parse(input) Parse one statement or a semicolon-delimited script into a list of Stmt objects
is_valid(input) Validate QQL syntax
inject_filter(query, field, op, value) Inject tenant filter into statement AST (accepts str or Stmt)
tokenize(input) Tokenize QQL string for syntax highlighting or inspection
compile_query(input) Lower QQL statement into typed { method, path, payload } route dict
explain(query) Inspect the execution plan without executing network calls (accepts str or Stmt)
execute(query, ..., on_error="stop") Free-function convenience execute
execute_async(query, ..., on_error="stop") Free-function async execute
Client.execute(query, on_error="stop") Execute a string, Stmt, list[str], or list[Stmt]
Client.execute_async(query, on_error="stop") Async variant of execute
Client.explain(query) Inspect execution plan (accepts str or Stmt)

Project links

Data verified by PyPI on Jul 27, 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 Jul 27, 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.8

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.1.2-cp38-abi3-win_amd64.whl (3.4 MB view details)

Uploaded CPython 3.8+Windows x86-64

pyqql-0.1.2-cp38-abi3-manylinux_2_28_x86_64.whl (3.3 MB view details)

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

pyqql-0.1.2-cp38-abi3-macosx_11_0_arm64.whl (3.0 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

pyqql-0.1.2-cp38-abi3-macosx_10_12_x86_64.whl (3.1 MB view details)

Uploaded CPython 3.8+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: pyqql-0.1.2-cp38-abi3-win_amd64.whl
  • Upload date:
  • Size: 3.4 MB
  • Tags: CPython 3.8+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyqql-0.1.2-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 6d2829159575ca5cd59dcd48b17c74d628971f19308896d63fde002e25dd5b39
MD5 229cbc391358967423b242b6666bbe49
BLAKE2b-256 20e8dfcaf72b18b04eadf57087174dcf90b6ae7c4741a905c9ec8e66431ee31d

See more details on using hashes here.

Provenance

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

File details

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

File metadata

File hashes

Hashes for pyqql-0.1.2-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c123c21b52fb557ae58058180c73b35b60be46d16177f3b5d9329678f0cedfa1
MD5 c384dbae6bbea02bfb17bf89d73a4842
BLAKE2b-256 85d80bb643b1883d1a515a331e62d892e3c8b413f1d60cf89cdebebf92e64508

See more details on using hashes here.

Provenance

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

File details

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

File metadata

  • Download URL: pyqql-0.1.2-cp38-abi3-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 3.0 MB
  • Tags: CPython 3.8+, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyqql-0.1.2-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f4a1aef1bea0bbd797a5273a9f3c123211f3ca82b300113812ad90f1b99ecf12
MD5 3d39eb8b670e5f4c96aee1f7d07f429f
BLAKE2b-256 2943f5a15c62e5c32093cfb1faf2011d25623aeb036cb6677ac2d2482bbdddc4

See more details on using hashes here.

Provenance

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

File details

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

File metadata

File hashes

Hashes for pyqql-0.1.2-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 0a19c99344ae417775c78bc6c34c1191d0c85c8ca98d820e7a51f7a2059eac97
MD5 eecb2c26346da863addd6b63eda03218
BLAKE2b-256 896c114f3eb1149bc2d338d93cdf3f1bd35bfb25f0d61974f3cdb1c144f1e453

See more details on using hashes here.

Provenance

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

Release history Release notifications | RSS feed

0.3.1

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

This release

0.1.2 This release

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