feat: add SELECT statement for retrieving a point by ID

Author: srimon12

README.md

@@ -7,7 +7,7 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Tests](https://img.shields.io/badge/tests-405%20passing-brightgreen)](tests/)
 
-Write `INSERT`, `SEARCH`, `SCROLL`, `RECOMMEND`, `DELETE`, and `CREATE COLLECTION` statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, turbo, binary, product), SQL-style `WHERE` filters, script execution, and collection dump/restore.
+Write `INSERT`, `SELECT`, `SEARCH`, `SCROLL`, `RECOMMEND`, `DELETE`, and `CREATE COLLECTION` statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, turbo, binary, product), SQL-style `WHERE` filters, script execution, and collection dump/restore.
 
 ```
 qql> INSERT INTO COLLECTION notes VALUES {'text': 'Qdrant is a vector database', 'author': 'alice', 'year': 2024}
@@ -82,7 +82,7 @@ Full documentation lives in the [`docs/`](docs/) folder and at **[pavanjava.gith
 |---|---|
 | [Getting Started](docs/getting-started.md) | Installation, connecting, first queries |
 | [INSERT / INSERT BULK](docs/insert.md) | Adding documents, batch inserts, payload types |
-| [SEARCH / SCROLL / RECOMMEND / Hybrid / RERANK](docs/search.md) | Semantic search, pagination, hybrid, reranking, recommendations |
+| [SEARCH / SELECT / SCROLL / RECOMMEND / Hybrid / RERANK](docs/search.md) | Semantic search, point retrieval, pagination, hybrid, reranking, recommendations |
 | [WHERE Filters](docs/filters.md) | Full SQL-style filter operators |
 | [Collections & Quantization](docs/collections.md) | CREATE, DROP, QUANTIZE (scalar/turbo/binary/product), CREATE INDEX |
 | [Scripts: EXECUTE / DUMP](docs/scripts.md) | Script files, collection backup/restore |
@@ -113,6 +113,9 @@ SCROLL FROM articles AFTER 'cursor-id' LIMIT 50
 -- Recommend
 RECOMMEND FROM articles POSITIVE IDS (1001, 1002) LIMIT 5
 
+-- Select (retrieve a point by ID)
+SELECT * FROM articles WHERE id = '3f2e1a4b-...'
+
 -- Collections
 CREATE COLLECTION articles
 CREATE COLLECTION articles HYBRID

docs/getting-started.md

@@ -143,14 +143,17 @@ SCROLL FROM notes LIMIT 10
 
 -- List all collections
 SHOW COLLECTIONS
+
+-- Retrieve a point by ID
+SELECT * FROM notes WHERE id = 1
 ```
 
 ---
 
 ## Next Steps
 
 - [INSERT / INSERT BULK](insert.md) — adding documents
-- [SEARCH / SCROLL / RECOMMEND / Hybrid / RERANK](search.md) — querying
+- [SEARCH / SELECT / SCROLL / RECOMMEND / Hybrid / RERANK](search.md) — querying
 - [WHERE Filters](filters.md) — payload filtering
 - [Collections & Quantization](collections.md) — managing collections
 - [Scripts: EXECUTE / DUMP](scripts.md) — automating with script files

docs/index.html

@@ -148,8 +148,8 @@ <h3>INSERT / INSERT BULK</h3>
       <p>Adding documents, batch inserts, payload types</p>
     </a>
     <a class="card" href="search">
-      <h3>SEARCH / SCROLL / RECOMMEND</h3>
-      <p>Semantic search, pagination, hybrid search, reranking, recommendations</p>
+      <h3>SEARCH / SELECT / SCROLL / RECOMMEND</h3>
+      <p>Semantic search, point retrieval, pagination, hybrid search, reranking, recommendations</p>
     </a>
     <a class="card" href="filters">
       <h3>WHERE Filters</h3>

docs/programmatic.md

@@ -67,6 +67,13 @@ result = run_query(
 for hit in result.data:
     print(hit["score"], hit["payload"])
 
+# Retrieve a point by ID
+result = run_query(
+    "SELECT * FROM notes WHERE id = 1",
+    url="http://localhost:6333",
+)
+print(result.data)      # {"id": "1", "payload": {...}}
+
 # Delete by filter
 result = run_query(
     "DELETE FROM notes WHERE year < 2023",
@@ -120,6 +127,7 @@ class ExecutionResult:
 | INSERT (dense) | `{"id": int \| "<uuid>", "collection": "<name>"}` |
 | INSERT (hybrid) | `{"id": int \| "<uuid>", "collection": "<name>"}` |
 | INSERT BULK | `None` (count in `result.message`) |
+| SELECT | `{"id": str, "payload": dict}` or `None` when not found |
 | SEARCH | `[{"id": str, "score": float, "payload": dict}, ...]` |
 | SCROLL | `{"points": [{"id": str, "payload": dict}, ...], "next_offset": str \| None}` |
 | RECOMMEND | `[{"id": str, "score": float, "payload": dict}, ...]` |

docs/reference.md

@@ -174,8 +174,9 @@ Expected output: **405 tests passing**.
 | `Connection failed: ...` | Qdrant unreachable at given URL | Check that Qdrant is running and the URL is correct |
 | `INSERT requires a 'text' field in VALUES` | `text` key missing from the VALUES dict | Add `'text': '...'` to your dict |
 | `Vector dimension mismatch: collection '...' expects X dims, but model produces Y dims` | Model used in INSERT differs from the one used to create the collection | Use `USING MODEL` to specify the same model as the collection was created with |
-| `Collection '...' does not exist` | SEARCH / SCROLL / DROP / DELETE on a non-existent collection | Check name spelling or run `SHOW COLLECTIONS` |
-| `Unexpected token '...'; expected a QQL statement keyword` | Unrecognized statement | Check the query syntax; QQL does not support SQL SELECT |
+| `Collection '...' does not exist` | SEARCH / SCROLL / SELECT / DROP / DELETE on a non-existent collection | Check name spelling or run `SHOW COLLECTIONS` |
+| `Unexpected token '...'; expected a QQL statement keyword` | Unrecognized statement | Check the query syntax and supported statement list |
+| `SELECT requires a string or integer point id, got '...'` | `SELECT` used with a non-ID filter value | Use `SELECT * FROM <collection> WHERE id = '<id>'` or an integer ID |
 | `Unterminated string literal (at position N)` | A string is missing its closing quote | Close the string with a matching `'` or `"` |
 | `Unexpected character '@' (at position N)` | A character not part of QQL syntax | Remove or quote the offending character |
 | `Expected a filter operator after field '...'` | Unknown operator in WHERE clause | Use one of: `=`, `!=`, `>`, `>=`, `<`, `<=`, `IN`, `NOT IN`, `BETWEEN`, `IS NULL`, `IS NOT NULL`, `IS EMPTY`, `IS NOT EMPTY`, `MATCH` |

docs/search.md

@@ -1,4 +1,4 @@
-# SEARCH, SCROLL, RECOMMEND, Hybrid Search & Reranking
+# SEARCH, SELECT, SCROLL, RECOMMEND, Hybrid Search & Reranking
 
 ---
 
@@ -70,6 +70,28 @@ Results are displayed as a table with three columns:
 
 ---
 
+## SELECT — retrieve a point by ID
+
+Fetches a single point payload by exact point ID.
+
+**Syntax:**
+```sql
+SELECT * FROM <collection_name> WHERE id = '<point_id>'
+SELECT * FROM <collection_name> WHERE id = <integer_id>
+```
+
+**Examples:**
+```sql
+SELECT * FROM articles WHERE id = '3f2e1a4b-8c91-4d0e-b123-abc123def456'
+SELECT * FROM articles WHERE id = 42
+```
+
+`SELECT` in this version is intentionally strict:
+- only `*` projection is supported
+- only `WHERE id = ...` is supported
+
+---
+
 ## Query-Time Search Params (`EXACT`, `WITH`)
 
 Use these when you want to debug retrieval quality or tune recall without changing collection-level settings.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qql-cli"
-version = "2.1.0"
+version = "2.2.0"
 description = "QQL is a SQL-like query language and CLI for Qdrant vector database. Write INSERT, SEARCH, RECOMMEND, DELETE, and CREATE COLLECTION statements instead of Python SDK calls. Supports hybrid dense+sparse vector search, cross-encoder reranking, quantization (scalar, turbo, binary, product), WHERE clause filters, script execution, and collection dump/restore."
 readme = "README.md"
 license = { file = "LICENSE" }

src/qql/ast_nodes.py

@@ -180,6 +180,12 @@ class ShowCollectionsStmt:
     pass
 
 
+@dataclass(frozen=True)
+class SelectStmt:
+    collection: str
+    point_id: str | int
+
+
 @dataclass(frozen=True)
 class ScrollStmt:
     collection: str
@@ -234,6 +240,7 @@ class DeleteStmt:
     | CreateIndexStmt
     | DropCollectionStmt
     | ShowCollectionsStmt
+    | SelectStmt
     | ScrollStmt
     | SearchStmt
     | RecommendStmt

src/qql/cli.py

@@ -54,6 +54,9 @@
       Optional: [yellow]WHERE[/yellow] <filter>
       Optional: [yellow]AFTER[/yellow] '<id>'|<int>
 
+  [yellow]SELECT * FROM[/yellow] <name> [yellow]WHERE id =[/yellow] '<id>'|<int>
+      Retrieve a single point by its ID and return its payload.
+
   [yellow]SEARCH[/yellow] <name> [yellow]SIMILAR TO[/yellow] '<text>' [yellow]LIMIT[/yellow] <n>
       Semantic search by vector similarity.
       Optional: [yellow]USING MODEL[/yellow] '<model>'
@@ -419,5 +422,14 @@ def _run_and_print(executor: Executor, query: str) -> None:
             console.print(f"[dim]next_offset: {result.data['next_offset']}[/dim]")
         return
 
+    # Pretty-print SELECT result
+    if isinstance(result.data, dict) and "id" in result.data and "payload" in result.data:
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("ID")
+        table.add_column("Payload")
+        table.add_row(str(result.data["id"]), str(result.data["payload"]))
+        console.print(table)
+        return
+
     # Fallback: print data as-is
     console.print(result.data)

src/qql/executor.py

@@ -76,6 +76,7 @@
     QuantizationConfig,
     QuantizationType,
     RecommendStmt,
+    SelectStmt,
     ScrollStmt,
     SearchStmt,
     SearchWith,
@@ -118,6 +119,8 @@ def execute(self, node: ASTNode) -> ExecutionResult:
             return self._execute_show(node)
         if isinstance(node, ScrollStmt):
             return self._execute_scroll(node)
+        if isinstance(node, SelectStmt):
+            return self._execute_select(node)
         if isinstance(node, SearchStmt):
             return self._execute_search(node)
         if isinstance(node, RecommendStmt):
@@ -447,6 +450,33 @@ def _execute_scroll(self, node: ScrollStmt) -> ExecutionResult:
             data={"points": points, "next_offset": None if next_offset is None else str(next_offset)},
         )
 
+    def _execute_select(self, node: SelectStmt) -> ExecutionResult:
+        if not self._client.collection_exists(node.collection):
+            raise QQLRuntimeError(f"Collection '{node.collection}' does not exist")
+
+        try:
+            records = self._client.retrieve(
+                collection_name=node.collection,
+                ids=[node.point_id],
+                with_payload=True,
+                with_vectors=False,
+            )
+        except UnexpectedResponse as e:
+            raise QQLRuntimeError(f"Qdrant error during SELECT: {e}") from e
+
+        if not records:
+            return ExecutionResult(
+                success=True,
+                message=f"Point '{node.point_id}' not found in '{node.collection}'",
+            )
+
+        record = records[0]
+        return ExecutionResult(
+            success=True,
+            message=f"Retrieved point '{node.point_id}' from '{node.collection}'",
+            data={"id": str(record.id), "payload": record.payload or {}},
+        )
+
     def _execute_search(self, node: SearchStmt) -> ExecutionResult:
         if not self._client.collection_exists(node.collection):
             raise QQLRuntimeError(f"Collection '{node.collection}' does not exist")