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)
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 28, 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 28, 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.3-cp38-abi3-win_amd64.whl (3.3 MB view details)

Uploaded CPython 3.8+Windows x86-64

pyqql-0.1.3-cp38-abi3-manylinux_2_28_x86_64.whl (3.2 MB view details)

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

pyqql-0.1.3-cp38-abi3-macosx_11_0_arm64.whl (2.9 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

pyqql-0.1.3-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.3-cp38-abi3-win_amd64.whl.

File metadata

  • Download URL: pyqql-0.1.3-cp38-abi3-win_amd64.whl
  • Upload date:
  • Size: 3.3 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.3-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 f0738f7d3bec771084f1418801b0290953a889ad02f96787920c06d2e6ff018c
MD5 bdfb8b003ab5acb94d1f354b7c7383eb
BLAKE2b-256 0a96187cc6a4d2713c6d615d484907549846e0d1c22aeaf17afb91f002cc8d1f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyqql-0.1.3-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 91c9a9f168e624bf86e61cb5031a023a4a173f7fe10ab4753bad6060ba009cf7
MD5 9e1a512cc14be374011ee58e67868354
BLAKE2b-256 b10fa4ce48656831722ecc88d7fec1ce39ccba94add1164f4a10ab7647f17f23

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: pyqql-0.1.3-cp38-abi3-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 2.9 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.3-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 839f569d2b570bda6f71444c2d707ac20ba8977529353b7e5262411634fbbfaa
MD5 c281d45aba6cbb1cb4dd699f111de9c4
BLAKE2b-256 c25bd3167f33c5eed5124109da37c8f4c47a17b31f9aba401e1f350140f3e069

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyqql-0.1.3-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 9b1fb18cd0bece048f67d00f39e17c4b95e8761ff47b8ec87c5e988e875eca49
MD5 e4193ad36909e98beb49e536e5e50755
BLAKE2b-256 9612cf42f97eb67f3d55f43a89843c49920abc3f0804c6722768418f2f68acf7

See more details on using hashes here.

Provenance

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

This release

0.1.3 This release

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