pyqql

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

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
  • Native 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 asyncio
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)

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

# Async execution example
async def main():
    report = await client.execute_async("QUERY 'cardiology' FROM medical_records USING dense LIMIT 5")
    print(report)

asyncio.run(main())

# 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": {...} }

Execution Results & Error Handling

ExecutionReport Format

All execution methods return an ExecutionReport dictionary:

{
    "ok": True,
    "results": [
        {
            "ok": True,
            "operation": "QUERY",
            "message": "Found 5 hits",
            "data": [...]
        }
    ],
    "succeeded": 1,
    "failed": 0
}

Failure Policy (on_error)

Policy Behavior
"stop" (default) Halts execution on the first error and raises a Python exception.
"continue" Continues executing remaining statements, collecting failures into results with ok: False.

Exceptions

pyqql raises standard Python exception types:

  • SyntaxError — QQL parse or lex errors.
  • TypeError — Invalid option or argument types.
  • ValueError — Invalid configuration values or unaccepted filter operators.
  • RuntimeError — Network transport or Qdrant backend failures.

Filter Injection Operators

inject_filter accepts comparison operators:

  • Accepted: =, ==, eq, >, gt, >=, gte, <, lt, <=, lte
  • Rejected: !=, neq, <>, in, is_null (raises SyntaxError — wrap with NOT or write in QQL query)

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)
inject_shard_key(query, key) Inject a shard key into a QQL string or Stmt (host multi-tenant routing)
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)
__version__ Package runtime version string

Documentation Links

Project links

Data verified by PyPI on Jul 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 Jul 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.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.4-cp38-abi3-win_amd64.whl (3.4 MB view details)

Uploaded CPython 3.8+Windows x86-64

pyqql-0.1.4-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.4-cp38-abi3-macosx_11_0_arm64.whl (3.0 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

pyqql-0.1.4-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.4-cp38-abi3-win_amd64.whl.

File metadata

  • Download URL: pyqql-0.1.4-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/7.0.0 CPython/3.13.14

File hashes

Hashes for pyqql-0.1.4-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 cad1af969b2534cfd7021d8f701285b2fe9e13f4e846e238d273840dbe82b67e
MD5 b55e47557cbcba330c5ccf60bd61d6b1
BLAKE2b-256 d697599d8b6f1f5c49d7b32a6bffeeccfc554e1e2e0f8e7345eaf3a61d2984e5

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.1.4-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.4-cp38-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqql-0.1.4-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 95354e656e326194e34ba5a2a2731e909ee379eb80de081c49463beb15179fb7
MD5 b45b0223ee60592d08a31b560b0a909f
BLAKE2b-256 915bc147783cc05322aa86c8f351fd1f659c54135ba61fdfc5b8bddf810ff601

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.1.4-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.4-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

  • Download URL: pyqql-0.1.4-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/7.0.0 CPython/3.13.14

File hashes

Hashes for pyqql-0.1.4-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 582cd847633f427cbc4bc44eebd4da5836a5a22e8164a15328b3c60f75c9fb96
MD5 115ee29bf234d3e54fdbdfc5f931a12b
BLAKE2b-256 3c882dee6cd2c28837649ac018aaaa9641c16b7f37bd05634ef8b34b3d468861

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqql-0.1.4-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.4-cp38-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pyqql-0.1.4-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 dc16a92a06da330d284bfee07056403f5e17984a4e791d313ce82307ec948211
MD5 03f0edc738b0f192f83a54c27e8857ea
BLAKE2b-256 f9c52a4c024f94f43ea9d21f81043884c24efdf263ba429d8295255da205d8cd

See more details on using hashes here.

Provenance

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

This release

0.1.4 This release

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