feat: add gRPC support with configurable options for Qdrant connection

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,28 @@ 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
+
     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}")
         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 +294,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 +352,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 +385,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`.
@@ -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 ─────────────────────────────────────────

src/qql/parser.py

@@ -1165,12 +1165,15 @@ def _parse_field_path(self) -> str:
             f"Expected a field name, got '{tok.value}'", tok.pos
         )
 
-    def _parse_literal(self) -> str | int | float | bool:
-        """STRING | INTEGER | FLOAT | boolean"""
+    def _parse_literal(self) -> str | int | float | bool | None:
+        """STRING | INTEGER | FLOAT | boolean | NULL"""
         tok = self._peek()
         if tok.kind == TokenKind.STRING:
             self._advance()
             return tok.value
+        if tok.kind == TokenKind.NULL:
+            self._advance()
+            return None
         if tok.kind == TokenKind.INTEGER:
             self._advance()
             return int(tok.value)
@@ -1186,7 +1189,7 @@ def _parse_literal(self) -> str | int | float | bool:
                 self._advance()
                 return False
         raise QQLSyntaxError(
-            f"Expected a literal value (string, integer, float, or boolean), got '{tok.value}'",
+            f"Expected a literal value (string, integer, float, boolean, or null), got '{tok.value}'",
             tok.pos,
         )
 
@@ -1203,10 +1206,10 @@ def _parse_number(self) -> int | float:
             f"Expected a number, got '{tok.value}'", tok.pos
         )
 
-    def _parse_literal_list(self) -> list[str | int | float | bool]:
+    def _parse_literal_list(self) -> list[str | int | float | bool | None]:
         """'(' literal { ',' literal } [','] ')'  — used by IN / NOT IN."""
         self._expect(TokenKind.LPAREN)
-        items: list[str | int | float | bool] = []
+        items: list[str | int | float | bool | None] = []
         if self._peek().kind == TokenKind.RPAREN:
             self._advance()
             return items

tests/test_connection.py

@@ -44,6 +44,17 @@ def test_custom_ca_bundle_passed_to_qdrant_client(self, mocker):
         )
         assert conn.config.verify == "/etc/ssl/internal-ca.pem"
 
+    def test_grpc_options_passed_to_qdrant_client(self, mocker):
+        mock_client_cls = mocker.patch("qdrant_client.QdrantClient")
+        Connection("http://localhost:6333", prefer_grpc=True, grpc_port=9999)
+        mock_client_cls.assert_called_once_with(
+            url="http://localhost:6333",
+            api_key=None,
+            verify=True,
+            prefer_grpc=True,
+            grpc_port=9999,
+        )
+
     def test_custom_default_model_stored_in_config(self, mocker):
         mocker.patch("qdrant_client.QdrantClient")
         conn = Connection("http://localhost:6333", default_model="BAAI/bge-small-en-v1.5")
@@ -174,7 +185,12 @@ def test_run_query_delegates_to_connection(self, mocker):
         conn_cls = mocker.patch("qql.Connection", return_value=conn_instance)
         run_query("SHOW COLLECTIONS", url="http://localhost:6333")
         conn_cls.assert_called_once_with(
-            url="http://localhost:6333", secret=None, default_model=None, verify=True
+            url="http://localhost:6333",
+            secret=None,
+            default_model=None,
+            verify=True,
+            prefer_grpc=False,
+            grpc_port=6334,
         )
         conn_instance.run_query.assert_called_once_with("SHOW COLLECTIONS")