You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* feat: add async execution and batched programmatic APIs
Add async QQL support with AsyncConnection and AsyncExecutor, plus sync
and async batching helpers for running multiple statements through one
programmatic API. Introduce BEGIN BATCH syntax, parameterized query
helpers, and optional gRPC connection settings.
Refactor shared parser and executor logic into qql.utils so sync and
async paths can reuse filter conversion, vector shaping, topology parsing,
batch grouping, and search parsing helpers.
Update tests and docs for async usage, batching, parameterized queries,
gRPC configuration, and batch block execution.
* feat: enhance batch processing with strict result count checks and null handling
* feat: enhance batch processing and query handling with improved error management and null support
* feat: enhance InExpr and NotInExpr handling with null support in filter building
---------
Co-authored-by: Srimon <srimon12mckv@gmail.com>
qql> INSERT INTO COLLECTION notes VALUES {'text': 'Qdrant is a vector database', 'author': 'alice', 'year': 2024}
@@ -50,16 +50,23 @@ Your query string
50
50
51
51
When you run `INSERT`, the `text` field is automatically converted into a dense vector using [Fastembed](https://github.com/qdrant/fastembed). In **hybrid mode** (`USING HYBRID`), a sparse BM25 vector is also generated alongside the dense vector, and searches use Qdrant's Reciprocal Rank Fusion (RRF) by default to merge the results of both retrieval methods. You can switch hybrid search to DBSF with `FUSION 'dbsf'`.
52
52
53
-
QQL also exposes a **programmatic API** for use inside Python applications — no CLI required:
53
+
QQL also exposes a **programmatic API** for use inside Python applications — no CLI required. Use `Connection` for sync code, `AsyncConnection` for async apps, and batch helpers when you want QQL to combine compatible operations into fewer Qdrant requests:
54
54
55
55
```python
56
-
from qql import Connection
56
+
from qql import Connection, QQLBatch
57
57
58
58
with Connection("http://localhost:6333") as conn:
59
59
conn.run_query("INSERT INTO COLLECTION notes VALUES {'text': 'Qdrant is fast'}")
60
-
result = conn.run_query("SEARCH notes SIMILAR TO 'vector database' LIMIT 5")
61
-
for hit in result.data:
62
-
print(hit["score"], hit["payload"])
60
+
result = conn.run_parameterized_query(
61
+
"SEARCH notes SIMILAR TO :query LIMIT 5",
62
+
{"query": "vector database"},
63
+
)
64
+
65
+
with QQLBatch(conn) as batch:
66
+
neurology = batch.add("SEARCH notes SIMILAR TO 'neurology' LIMIT 5")
67
+
cardiology = batch.add("SEARCH notes SIMILAR TO 'cardiology' LIMIT 5")
Copy file name to clipboardExpand all lines: docs/getting-started.md
+9-2Lines changed: 9 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ title: "Getting Started"
5
5
6
6
# Getting Started with QQL
7
7
8
-
QQL is a SQL-like query language and CLI for [Qdrant](https://qdrant.tech). Instead of writing Python SDK calls you write natural query statements to insert, search, manage, and delete vector data.
8
+
QQL is a SQL-like query language and CLI for [Qdrant](https://qdrant.tech). Instead of writing Python SDK calls you write natural query statements to insert, search, manage, and delete vector data. It can also be used as a sync or async Python library with batching, parameterized queries, and optional gRPC transport.
9
9
10
10
---
11
11
@@ -172,6 +172,12 @@ SHOW COLLECTION notes
172
172
173
173
-- Retrieve a point by ID
174
174
SELECT*FROM notes WHERE id =1
175
+
176
+
-- Run compatible queries as one batch
177
+
BEGIN BATCH;
178
+
SEARCH notes SIMILAR TO 'vector databases'LIMIT5;
179
+
SEARCH notes SIMILAR TO 'semantic search'LIMIT5;
180
+
END BATCH
175
181
```
176
182
177
183
---
@@ -182,5 +188,6 @@ SELECT * FROM notes WHERE id = 1
|`secret`|`str \| None`|`None`| API key; `None` for unauthenticated |
181
199
|`default_model`|`str \| None`|`None` → `sentence-transformers/all-MiniLM-L6-v2`| Dense embedding model used when no `USING MODEL` clause is given |
200
+
|`prefer_grpc`|`bool`|`False`| Passes `prefer_grpc=True` to the Qdrant client |
201
+
|`grpc_port`|`int`|`6334`| gRPC port used when `prefer_grpc=True`|
182
202
|`verify`|`bool \| str`|`True`| TLS verification setting; use `False` to skip verification or a CA bundle path for internal/self-signed certificates |
183
203
|`default_dense_vector_name`|`str`|`"dense"`| Dense vector name used when QQL creates a collection and no explicit `USING VECTOR` name is given |
184
204
|`default_sparse_vector_name`|`str`|`"sparse"`| Sparse vector name used when QQL creates a hybrid collection and no explicit sparse vector name is given |
185
205
206
+
---
207
+
208
+
## Parameterized Queries
209
+
210
+
Parameterized helpers render `:name` placeholders before parsing the QQL statement. String values are quoted and escaped; booleans are rendered as `true` / `false`.
211
+
212
+
```python
213
+
from qql import Connection
214
+
215
+
with Connection("http://localhost:6333") as conn:
216
+
result = conn.run_parameterized_query(
217
+
"SEARCH notes SIMILAR TO :query LIMIT 5 WHERE author = :author",
218
+
{"query": "vector database", "author": "alice"},
219
+
)
220
+
221
+
results = conn.run_parameterized_batch(
222
+
"SEARCH notes SIMILAR TO :query LIMIT 5 WHERE category = :category",
Parameterized queries are a convenience for building QQL strings safely in application code; they are not sent to Qdrant as server-side prepared statements.
231
+
232
+
---
233
+
234
+
## Batch Execution
235
+
236
+
`run_queries_batch()` parses multiple QQL strings into a `BatchBlockStmt`. The executor groups compatible statements:
237
+
238
+
- compatible `SEARCH` / `RECOMMEND` statements use Qdrant `query_batch_points`
239
+
- compatible `INSERT` statements become one `INSERT BULK`
240
+
- mixed or incompatible statements still execute in order
241
+
242
+
```python
243
+
from qql import Connection
244
+
245
+
with Connection("http://localhost:6333") as conn:
246
+
results = conn.run_queries_batch([
247
+
"SEARCH docs SIMILAR TO 'neurology' LIMIT 5",
248
+
"SEARCH docs SIMILAR TO 'cardiology' LIMIT 5",
249
+
])
250
+
251
+
for result in results:
252
+
print(result.message)
253
+
```
254
+
255
+
For ergonomic batching in application code, use `QQLBatch`:
256
+
257
+
```python
258
+
from qql import Connection, QQLBatch
259
+
260
+
with Connection("http://localhost:6333") as conn:
261
+
with QQLBatch(conn) as batch:
262
+
neuro = batch.add("SEARCH docs SIMILAR TO 'neurology' LIMIT 5")
263
+
cardio = batch.add("SEARCH docs SIMILAR TO 'cardiology' LIMIT 5")
264
+
265
+
print(neuro.result.data)
266
+
print(cardio.result.data)
267
+
```
268
+
269
+
Each proxy's `.result` becomes available after the context manager exits.
270
+
271
+
---
272
+
273
+
## Async API
274
+
275
+
`AsyncConnection` mirrors the sync API for `asyncio` applications and uses `AsyncQdrantClient` under the hood.
276
+
277
+
```python
278
+
from qql import AsyncConnection
279
+
280
+
asyncwith AsyncConnection("http://localhost:6333") as conn:
281
+
await conn.run_query(
282
+
"INSERT INTO COLLECTION notes VALUES {'text': 'async QQL'}"
283
+
)
284
+
result =await conn.run_query(
285
+
"SEARCH notes SIMILAR TO 'async vector search' LIMIT 5"
286
+
)
287
+
print(result.data)
288
+
```
289
+
290
+
Async batching and parameterized helpers are also available:
291
+
292
+
```python
293
+
from qql import AsyncConnection, QQLAsyncBatch
294
+
295
+
asyncwith AsyncConnection("http://localhost:6333", prefer_grpc=True) as conn:
296
+
result =await conn.run_parameterized_query(
297
+
"SEARCH docs SIMILAR TO :query LIMIT 5",
298
+
{"query": "clinical notes"},
299
+
)
300
+
301
+
asyncwith QQLAsyncBatch(conn) as batch:
302
+
first = batch.add("SEARCH docs SIMILAR TO 'neurology' LIMIT 5")
303
+
second = batch.add("SEARCH docs SIMILAR TO 'cardiology' LIMIT 5")
304
+
305
+
print(first.result.data, second.result.data)
306
+
```
307
+
308
+
The async executor preserves the same `ExecutionResult` shape as the sync executor.
309
+
310
+
---
311
+
186
312
### Power-user: `executor` property
187
313
188
314
For low-level access to the pipeline, use `conn.executor` directly:
@@ -275,7 +401,8 @@ class ExecutionResult:
275
401
|---|---|
276
402
| INSERT (dense) |`{"id": int \| "<uuid>", "collection": "<name>"}`|
277
403
| INSERT (hybrid) |`{"id": int \| "<uuid>", "collection": "<name>"}`|
278
-
| INSERT BULK |`None` (count in `result.message`) |
404
+
| INSERT BULK |`{"ids": [int \| "<uuid>", ...]}`|
405
+
| BEGIN BATCH / programmatic batch |`[ExecutionResult, ...]`|
279
406
| SELECT |`{"id": str, "payload": dict}` or `None` when not found |
|`Unknown index type '...'`| Invalid schema type in CREATE INDEX | Use one of: `keyword`, `integer`, `float`, `bool`, `text`, `geo`, `datetime`, `uuid`|
221
247
|`Unknown CREATE INDEX option '...'`| Unsupported advanced option for the chosen payload index type | Check which `WITH { ... }` keys are supported for `keyword`, `uuid`, or `text`|
222
248
|`Qdrant error during CREATE INDEX: ...`| Qdrant rejected the index creation | Check field name and collection state |
249
+
|`Unterminated batch block; expected END BATCH`| A `BEGIN BATCH` block was not closed | Add `END BATCH` at the end of the block |
250
+
|`Batch has not been executed yet.`| Read a `QQLBatch` proxy result before leaving the context manager | Access `.result` only after the `with QQLBatch(...)` block exits |
251
+
|`AsyncBatch has not been executed yet.`| Read a `QQLAsyncBatch` proxy result before leaving the async context manager | Access `.result` only after the `async with QQLAsyncBatch(...)` block exits |
0 commit comments