pyqql-edge

Local QQL execution for Python — qdrant-edge + fastembed-rs, zero network.

Features

  • In-Process Vector Storage: Run Qdrant search engine locally inside Python process with zero server daemon requirement
  • Embedded ONNX Inference: Automatically fetch and run FastEmbed ONNX models on-device
  • 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 Stmt objects or Python dicts
  • Filter Injection: Programmatically add tenant isolation filters
  • Validation: Check if a query string is valid QQL
  • Smart Batching: Auto-batches contiguous same-collection query/mutation statements

Compatibility & Platforms

  • Python 3.8+: Published wheels use Python's stable ABI (abi3-py38).
  • Supported Platforms:
    • Linux x64 (glibc)
    • macOS arm64 (Apple Silicon)
    • Windows x64 (msvc)
  • Note: Prebuilt wheels are not published for macOS Intel (Darwin x64) because ONNX Runtime lacks Darwin x64 prebuilds.

Installation

pip install pyqql-edge

Quick Start

import pyqql_edge

# 1. Discover local ONNX models
models = pyqql_edge.list_embedding_models()
# [{'name': 'BGESmallENV15', 'model_code': 'Xenova/bge-small-en-v1.5', 'dim': 384, ...}, ...]

# 2. Edge execution — pick model (default BGESmallENV15 / 384-d)
client = pyqql_edge.local_executor(
    "./qdrant_data",
    on_disk_payload=False,
    model="bge-small-en-v1.5",        # enum name, HF code, or short alias
    cache_dir="/var/cache/fastembed", # optional
)

# Schema-aware text auto-embed (dense-only, sparse-only, and hybrid)
client.execute("CREATE COLLECTION docs HYBRID")
client.execute(
    'UPSERT INTO docs VALUES {id: "550e8400-e29b-41d4-a716-446655440001", text: "hello"}'
)
result = client.execute("QUERY 'hello' FROM docs USING dense LIMIT 10", on_error="stop")
print(result)

# 3. Parser & Filter Injection
stmt = pyqql_edge.parse("QUERY 'hello' FROM docs LIMIT 10")[0]
tokens = pyqql_edge.tokenize("QUERY 'test' FROM docs")
secured_stmt = pyqql_edge.inject_filter("QUERY 'search' FROM docs", "org_id", "=", "acme")

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.

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)

Edge Gotchas

Gotcha Reality
Point IDs Integers or UUIDs only — "doc-1" is rejected
Text UPSERT into an existing collection Auto-embedding follows the schema: dense-only gets dense, sparse-only gets sparse, hybrid gets both
QUERY 'text' on HYBRID Dense+sparse topology is ambiguous, so specify the target with USING <vector_name>
GROUP BY / shard keys Rejected clearly; never silently ignored in edge mode
Model locked at local_executor() USING MODEL 'other' mismatches fail
Client lifetime Call close() before deleting data_dir

API Summary

Export Description
local_executor(data_dir, ...) Create a fully local edge Client backed by fastembed-rs & qdrant-edge
list_embedding_models() List dense ONNX models available for local_executor(model=...)
http_executor(data_dir, url, ...) Create an edge Client with local vector storage and remote HTTP embedder
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
parse_json(input) Parse to raw JSON string (bypasses Python object allocation)
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") One-shot execute with a temporary edge client
execute_async(query, ..., on_error="stop") Async variant of execute
__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 embeddings edge

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_edge-0.1.4-cp38-abi3-win_amd64.whl (21.3 MB view details)

Uploaded CPython 3.8+Windows x86-64

pyqql_edge-0.1.4-cp38-abi3-manylinux_2_28_x86_64.whl (22.1 MB view details)

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

pyqql_edge-0.1.4-cp38-abi3-macosx_11_0_arm64.whl (19.3 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

File details

Details for the file pyqql_edge-0.1.4-cp38-abi3-win_amd64.whl.

File metadata

  • Download URL: pyqql_edge-0.1.4-cp38-abi3-win_amd64.whl
  • Upload date:
  • Size: 21.3 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_edge-0.1.4-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 599d35d286b7300e6f06906eb8e1895ddcae836f5f4de613d4eed6e3939b1d65
MD5 ba0295dfcaa8521a3e55559dec3b0b80
BLAKE2b-256 bd1043fd4b137dbaa1b5d64d5366a203d43ca0b300dd61d50aeb214ab49471cd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyqql_edge-0.1.4-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 ac9ffcb07b3188d42e2746b26fb81211f95cfcadfa25c3146ed6bb2657452d32
MD5 1e2c2e9470f17160f386921cd722fea5
BLAKE2b-256 c9e2e2828e7cddca49cdf9ba2226d7c81c1029e65de8a4c80829b080a4442cfe

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyqql_edge-0.1.4-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 807da895c496ef2a83cc910af0b5c852112e42e63f7e69efbf433cf18633cb94
MD5 2e10f79ab27ce9e9d47a03960e22e703
BLAKE2b-256 039946b99ea77f49f02a527d9b96fce6b607dd0fc8f4600d587ff3f3bad04379

See more details on using hashes here.

Provenance

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

Release history Release notifications | RSS feed

0.3.1

3 files

0.3.0

3 files

0.2.1

3 files

0.2.0

3 files

0.1.5

3 files

This release

0.1.4 This release

3 files

0.1.3

3 files

0.1.2

3 files

0.1.1

3 files

0.1.0

3 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