feat: add gRPC support with configurable options for Qdrant connection (#51)

* feat: add gRPC support with configurable options for Qdrant connection

* feat: improve error handling and parameter validation in Qdrant connection and executor

Author: srimon12

src/qql/__init__.py

@@ -43,6 +43,8 @@ def run_query(
     secret: str | None = None,
     default_model: str | None = None,
     verify: bool | str = True,
+    prefer_grpc: bool = False,
+    grpc_port: int = 6334,
 ) -> ExecutionResult:
     """One-shot convenience function kept for backward compatibility.
 
@@ -61,5 +63,7 @@ def run_query(
         secret=secret,
         default_model=default_model,
         verify=verify,
+        prefer_grpc=prefer_grpc,
+        grpc_port=grpc_port,
     ) as conn:
         return conn.run_query(query)

src/qql/ast_nodes.py

@@ -25,9 +25,9 @@ class QuantizationConfig:
 class SearchWith:
     """Query-time search params supported by Qdrant SearchParams."""
     hnsw_ef: int | None = None
-    exact: bool = False
-    acorn: bool = False
-    indexed_only: bool = False
+    exact: bool | None = None
+    acorn: bool | None = None
+    indexed_only: bool | None = None
     quantization: "QuantizationSearchWith | None" = None
     mmr_diversity: float | None = None
     mmr_candidates: int | None = None
@@ -99,7 +99,7 @@ class CompareExpr:
     """field op literal  — covers =, !=, >, >=, <, <="""
     field: str
     op: str   # one of: "=", "!=", ">", ">=", "<", "<="
-    value: str | int | float | bool
+    value: str | int | float | bool | None
 
 
 @dataclass(frozen=True)
@@ -114,14 +114,14 @@ class BetweenExpr:
 class InExpr:
     """field IN (v1, v2, ...)"""
     field: str
-    values: tuple[str | int | float | bool, ...]
+    values: tuple[str | int | float | bool | None, ...]
 
 
 @dataclass(frozen=True)
 class NotInExpr:
     """field NOT IN (v1, v2, ...)"""
     field: str
-    values: tuple[str | int | float | bool, ...]
+    values: tuple[str | int | float | bool | None, ...]
 
 
 @dataclass(frozen=True)

src/qql/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import sys
+from typing import Any
 
 import click
 from prompt_toolkit import PromptSession
@@ -18,6 +19,20 @@
 console = Console()
 err_console = Console(stderr=True)
 
+
+def _client_kwargs_from_cfg(cfg: QQLConfig) -> dict[str, Any]:
+    """Build QdrantClient keyword arguments from a QQLConfig."""
+    kwargs: dict[str, Any] = {
+        "url": cfg.url,
+        "api_key": cfg.secret,
+        "verify": cfg.verify,
+    }
+    if cfg.prefer_grpc:
+        kwargs["prefer_grpc"] = True
+        kwargs["grpc_port"] = cfg.grpc_port
+    return kwargs
+
+
 HELP_TEXT = """
 [bold cyan]QQL — Qdrant Query Language[/bold cyan]
 
@@ -185,11 +200,26 @@ def main(ctx: click.Context) -> None:
     type=click.Path(exists=True, readable=True, dir_okay=False, resolve_path=True),
     help="Path to a custom CA certificate bundle (PEM).",
 )
+@click.option(
+    "--prefer-grpc",
+    is_flag=True,
+    default=False,
+    help="Connect via gRPC transport instead of HTTP.",
+)
+@click.option(
+    "--grpc-port",
+    type=int,
+    default=6334,
+    show_default=True,
+    help="gRPC port of the Qdrant instance.",
+)
 def connect(
     url: str,
     secret: str | None,
     verify: bool,
     ca_cert: str | None,
+    prefer_grpc: bool,
+    grpc_port: int,
 ) -> None:
     """Connect to a Qdrant instance and launch the QQL shell."""
     from qdrant_client import QdrantClient
@@ -201,16 +231,31 @@ def connect(
 
     console.print(f"Connecting to [bold]{url}[/bold]...")
 
+    client_kwargs: dict[str, Any] = {
+        "url": url,
+        "api_key": secret,
+        "verify": verify_val,
+    }
+    if prefer_grpc:
+        client_kwargs["prefer_grpc"] = True
+        client_kwargs["grpc_port"] = grpc_port
+
+    client = None
     try:
-        client = QdrantClient(url=url, api_key=secret, verify=verify_val)
+        client = QdrantClient(**client_kwargs)
         client.get_collections()
     except Exception as e:
         err_console.print(f"[bold red]Connection failed:[/bold red] {e}")
+        if client is not None:
+            client.close()
         sys.exit(1)
     else:
         client.close()
 
-    cfg = QQLConfig(url=url, secret=secret, verify=verify_val)
+    cfg = QQLConfig(
+        url=url, secret=secret, verify=verify_val,
+        prefer_grpc=prefer_grpc, grpc_port=grpc_port,
+    )
     save_config(cfg)
     console.print("[bold green]Connected.[/bold green] Config saved to ~/.qql/config.json\n")
     _launch_repl(cfg)
@@ -252,7 +297,7 @@ def execute(file: str, stop_on_error: bool) -> None:
         sys.exit(1)
 
     try:
-        client = QdrantClient(url=cfg.url, api_key=cfg.secret, verify=cfg.verify)
+        client = QdrantClient(**_client_kwargs_from_cfg(cfg))
         client.get_collections()
     except Exception as e:
         err_console.print(f"[bold red]Connection failed:[/bold red] {e}")
@@ -310,7 +355,7 @@ def dump(collection: str, output: str, batch_size: int) -> None:
         sys.exit(1)
 
     try:
-        client = QdrantClient(url=cfg.url, api_key=cfg.secret, verify=cfg.verify)
+        client = QdrantClient(**_client_kwargs_from_cfg(cfg))
         client.get_collections()
     except Exception as e:
         err_console.print(f"[bold red]Connection failed:[/bold red] {e}")
@@ -343,7 +388,7 @@ def _launch_repl(cfg: QQLConfig) -> None:
     from qdrant_client import QdrantClient
 
     try:
-        client = QdrantClient(url=cfg.url, api_key=cfg.secret, verify=cfg.verify)
+        client = QdrantClient(**_client_kwargs_from_cfg(cfg))
         client.get_collections()
     except Exception as e:
         err_console.print(f"[bold red]Could not connect to {cfg.url}:[/bold red] {e}")

src/qql/config.py

@@ -20,6 +20,8 @@ class QQLConfig:
     default_dense_vector_name: str = DEFAULT_DENSE_VECTOR_NAME
     default_sparse_vector_name: str = DEFAULT_SPARSE_VECTOR_NAME
     verify: bool | str = True
+    prefer_grpc: bool = False
+    grpc_port: int = 6334
 
 
 def save_config(cfg: QQLConfig) -> None:
@@ -45,6 +47,8 @@ def load_config() -> QQLConfig | None:
             "default_sparse_vector_name", DEFAULT_SPARSE_VECTOR_NAME
         ),
         verify=data.get("verify", True),
+        prefer_grpc=data.get("prefer_grpc", False),
+        grpc_port=data.get("grpc_port", 6334),
     )
 
 

src/qql/connection.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import Any
+
 from .config import DEFAULT_MODEL, QQLConfig
 from .executor import Executor, ExecutionResult
 from .lexer import Lexer
@@ -52,6 +54,8 @@ def __init__(
         secret: str | None = None,
         default_model: str | None = None,
         verify: bool | str = True,
+        prefer_grpc: bool = False,
+        grpc_port: int = 6334,
     ) -> None:
         """Create a connection to a Qdrant instance.
 
@@ -64,6 +68,8 @@ def __init__(
             verify: SSL certificate verification. Set to ``False`` to skip
                 verification for self-signed/internal certificates, or pass
                 a path to a custom CA bundle (default: ``True``).
+            prefer_grpc: Whether to connect via fast gRPC transport.
+            grpc_port: The gRPC port of Qdrant instance (default: 6334).
         """
         from qdrant_client import QdrantClient
 
@@ -72,8 +78,18 @@ def __init__(
             secret=secret,
             default_model=default_model or DEFAULT_MODEL,
             verify=verify,
+            prefer_grpc=prefer_grpc,
+            grpc_port=grpc_port,
         )
-        self._client = QdrantClient(url=url, api_key=secret, verify=verify)
+        client_kwargs: dict[str, Any] = {
+            "url": url,
+            "api_key": secret,
+            "verify": verify,
+        }
+        if prefer_grpc:
+            client_kwargs["prefer_grpc"] = True
+            client_kwargs["grpc_port"] = grpc_port
+        self._client = QdrantClient(**client_kwargs)
         self._executor = Executor(self._client, self._config)
 
     # ── Public API ────────────────────────────────────────────────────────

src/qql/executor.py

@@ -240,12 +240,18 @@ def execute(self, node: ASTNode) -> ExecutionResult:
 
     # ── Statement executors ───────────────────────────────────────────────
 
+    @staticmethod
+    def _is_grpc_not_found_error(error: BaseException) -> bool:
+        """Return True if *error* is a gRPC NOT_FOUND status."""
+        from grpc import RpcError, StatusCode
+        return isinstance(error, RpcError) and error.code() == StatusCode.NOT_FOUND
+
     def _fetch_collection_info(self, name: str):
         """Fetch full CollectionInfo for *name* in a single API call.
 
         Returns the CollectionInfo object when the collection exists, or
-        ``None`` when the collection is not found (HTTP 404).  Any other
-        Qdrant error is re-raised as :class:`QQLRuntimeError`.
+        ``None`` when the collection is not found (HTTP 404 or gRPC NOT_FOUND).
+        Any other Qdrant error is re-raised as :class:`QQLRuntimeError`.
         """
         try:
             return self._client.get_collection(name)
@@ -255,6 +261,18 @@ def _fetch_collection_info(self, name: str):
             raise QQLRuntimeError(
                 f"Qdrant error fetching collection '{name}': {e}"
             ) from e
+        except ValueError as e:
+            if f"Collection {name} not found" in str(e):
+                return None
+            raise QQLRuntimeError(
+                f"Qdrant error fetching collection '{name}': {e}"
+            ) from e
+        except Exception as e:
+            if self._is_grpc_not_found_error(e):
+                return None
+            raise QQLRuntimeError(
+                f"Qdrant error fetching collection '{name}': {e}"
+            ) from e
 
     def _topology_from_collection_info(self, info: Any) -> CollectionTopology:
         """Parse a CollectionInfo object into a :class:`CollectionTopology`.
@@ -1333,8 +1351,8 @@ def _build_search_params(self, with_clause: SearchWith | None) -> SearchParams |
             hnsw_ef=with_clause.hnsw_ef,
             exact=with_clause.exact,
             quantization=quantization,
-            indexed_only=True if with_clause.indexed_only else None,
-            acorn=AcornSearchParams(enable=True) if with_clause.acorn else None,
+            indexed_only=with_clause.indexed_only if with_clause.indexed_only is not None else None,
+            acorn=AcornSearchParams(enable=with_clause.acorn) if with_clause.acorn is not None else None,
         )
 
     def _build_hnsw_config(self, config: CollectionConfig | None) -> HnswConfigDiff | None:
@@ -1835,6 +1853,15 @@ def _build_qdrant_filter(self, expr: FilterExpr) -> Any:
 
         # ── Comparison ────────────────────────────────────────────────────
         if isinstance(expr, CompareExpr):
+            if expr.value is None:
+                null_condition = IsNullCondition(is_null=PayloadField(key=expr.field))
+                if expr.op == "=":
+                    return null_condition
+                if expr.op == "!=":
+                    return Filter(must_not=[null_condition])
+                raise QQLRuntimeError(
+                    f"Cannot use operator '{expr.op}' with null for field '{expr.field}'"
+                )
             if expr.op == "=":
                 return FieldCondition(
                     key=expr.field, match=MatchValue(value=expr.value)
@@ -1858,14 +1885,34 @@ def _build_qdrant_filter(self, expr: FilterExpr) -> Any:
 
         # ── IN / NOT IN ───────────────────────────────────────────────────
         if isinstance(expr, InExpr):
-            return FieldCondition(
-                key=expr.field, match=MatchAny(any=list(expr.values))
+            non_nulls = [v for v in expr.values if v is not None]
+            if len(non_nulls) == len(expr.values):
+                return FieldCondition(
+                    key=expr.field, match=MatchAny(any=non_nulls)
+                )
+            null_condition = IsNullCondition(is_null=PayloadField(key=expr.field))
+            if not non_nulls:
+                return null_condition
+            return Filter(
+                should=[
+                    null_condition,
+                    FieldCondition(key=expr.field, match=MatchAny(any=non_nulls)),
+                ]
             )
 
         if isinstance(expr, NotInExpr):
+            non_nulls = [v for v in expr.values if v is not None]
+            null_condition = IsNullCondition(is_null=PayloadField(key=expr.field))
+            if len(non_nulls) != len(expr.values):
+                must_not = [null_condition]
+                if non_nulls:
+                    must_not.append(
+                        FieldCondition(key=expr.field, match=MatchAny(any=non_nulls))
+                    )
+                return Filter(must_not=must_not)
             return FieldCondition(
                 key=expr.field,
-                match=MatchExcept(**{"except": list(expr.values)}),
+                match=MatchExcept(**{"except": non_nulls}),
             )
 
         # ── IS NULL / IS NOT NULL ─────────────────────────────────────────