Feat/refractor batch grpc async support

[pavanjava]

Summary by CodeRabbit

Release Notes

• New Features

  • Added async query execution support via AsyncConnection
  • Added gRPC transport option for improved performance
  • Introduced parameterized queries for safer dynamic query construction
  • Added batch execution capabilities: run multiple compatible queries in a single BEGIN BATCH ... END BATCH block
  • Expanded supported quantization modes and cross-encoder reranking capabilities

• Documentation

  • Updated Getting Started guide with async, gRPC, and batching examples
  • Extended Programmatic Usage documentation with new APIs and patterns
  • Added Public Python API reference section
  • Enhanced scripts documentation with batch execution syntax

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces batched statement execution, parameterized query templates, asynchronous APIs, and optional gRPC transport for QQL. The grammar is extended to parse BEGIN BATCH ... END BATCH blocks; a new utilities module centralizes reusable logic for query construction, filtering, and batch grouping; and both synchronous and asynchronous execution paths leverage these shared helpers to execute batches and parameterized queries efficiently.

Changes

Batch Processing, Parameterized Queries, and Async Execution

Layer / File(s)	Summary
Grammar and AST Foundation for Batching src/qql/lexer.py, src/qql/parser.py, src/qql/ast_nodes.py, src/qql/script.py	Lexer adds BEGIN, BATCH, END, SEMICOLON tokens. Parser gains batch block parsing, NULL literal support, refactored SEARCH clause helpers, and trailing semicolon tolerance. AST gains BatchBlockStmt, nullable SearchWith fields, and null values in IN/NOT IN expressions. Script splitter tracks batch_depth to preserve batch regions.
Shared Query Utilities src/qql/utils.py	New module containing parameterized query rendering, batch statement grouping, Qdrant filter construction, dense query building with MMR support, search clause parsing (lookup/using/with/group-by), recommend strategy resolution, and point ID/payload extraction—used by both sync and async executors.
Synchronous Batch and Parameterized APIs src/qql/connection.py	Connection adds prefer_grpc/grpc_port gRPC configuration, run_queries_batch for executing multiple statements, and run_parameterized_query/run_parameterized_batch for template-based execution. Introduces QQLBatch context manager and OperationProxy for deferred per-query result resolution with mismatch error handling.
Synchronous Executor Refactoring and Batch Support src/qql/executor.py	Executor refactored to delegate helper logic to qql.utils; adds _execute_batch_block dispatching grouped statements (queries via _execute_query_batch, inserts as bulk operations) and aggregating per-statement results. Collection visibility check enhanced for "not found" ValueError case.
Asynchronous Connection and Batch APIs src/qql/async_connection.py	New AsyncConnection class provides async equivalents of all sync APIs plus gRPC configuration. Manages reusable AsyncQdrantClient and AsyncExecutor. Introduces QQLAsyncBatch and AsyncOperationProxy for async deferred result resolution.
Asynchronous Statement Execution src/qql/async_executor.py	New AsyncExecutor class mirrors Executor with async dispatch for all operation types (insert, create, search, recommend, delete, update, etc.) using AsyncQdrantClient. Includes async topology resolution with asyncio.Lock for coordinated collection creation. Batch block execution uses _execute_query_batch with query_batch_points.
Public Module Exports src/qql/__init__.py	Expanded __all__ to re-export sync/async connection classes, batch managers, proxy types, executor classes, and shared config/error/execution helpers.
User Documentation Updates README.md, docs/getting-started.md, docs/programmatic.md, docs/reference.md, docs/scripts.md	Updated to document batching syntax, async/sync APIs, parameterized queries, gRPC transport, connection parameters, result shapes, and comprehensive examples.
Comprehensive Test Coverage tests/test_async_connection.py, tests/test_connection.py, tests/test_executor.py, tests/test_parser.py	New and extended test modules validate batch parsing, async initialization/lifecycle, batch execution, parameterized rendering with escaping, context manager behavior, null handling in filters, and concurrency safety.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 A batch of queries hop in lockstep,
Async awaits their turn with patience,
Parameters dance through templates with care,
gRPC speeds the journey through the wire—
One statement, or many, the executor doesn't care! 🚀

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.39% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'Feat/refractor batch grpc async support' partially describes the changeset but contains a spelling error ('refractor' should be 'refactor') and is somewhat vague about the scope of changes.	Clarify the title by fixing the spelling error to 'refactor' and consider being more specific about the primary feature being added, such as 'Add batch execution, async API, and gRPC support' or 'Add async connection, batch execution, and gRPC transport'.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/refractor-batch-grpc-async-support

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}