Python SDK

Python SDK

Connect RPC Python

The QQL Python SDK is a Connect RPC client that wraps the QQL gateway. It lets you run QQL from Python without the CLI.

Prerequisites

Start the QQL gateway:

Start gateway

qql-go serve --qdrant-url http://localhost:6334 --inference-mode local
--embedding-endpoint http://127.0.0.1:1234/v1/embeddings
--embedding-model text-embedding-all-minilm-l6-v2-embedding

Install

The QQL Python SDK is not yet published to PyPI. Install from the repository:

from source:

cd sdks/python
pip install -e .

Quick Start

from qql import QQLClient

client = QQLClient("http://localhost:50051")

# Execute a query
result = client.exec("QUERY 'emergency triage' FROM docs LIMIT 5 USING HYBRID")
print(result)

# Batch queries
results = client.exec_batch([
    "QUERY 'emergency triage' FROM docs LIMIT 5",
    "QUERY 'cardiac arrest' FROM docs LIMIT 5",
])

# Explain without executing
plan = client.explain("QUERY 'search' FROM docs LIMIT 5 USING HYBRID RERANK")
print(plan)

# Health check
health = client.health()
print(health)

API

Method	Description
client.exec(query)	Execute a single QQL statement
client.exec_batch(queries)	Execute multiple statements sequentially
client.explain(query)	Return execution plan without running
client.health()	Check gateway + Qdrant connectivity

With Authentication

client = QQLClient(
    "http://localhost:50051",
    token="eyJhbGciOiJSUzI1NiIs..."  # JWT bearer token
)

Response Shape

result = client.exec("QUERY 'search' FROM docs LIMIT 5")
# result.ok        bool
# result.operation str   e.g. "QUERY"
# result.message   str   e.g. "Found 5 results"
# result.data      dict  decoded JSON result