feat: add RECOMMEND statement for point recommendations

- Introduced the RECOMMEND statement to allow users to find similar points based on known examples.
- Implemented parsing, execution, and filtering logic for the RECOMMEND statement in the QQL parser and executor.
- Updated the CLI to include documentation for the new RECOMMEND statement.
- Enhanced the executor to handle positive and negative IDs, as well as optional query filters and strategies.
- Added tests for the RECOMMEND statement to ensure correct functionality and error handling.
- Updated the sample QQL script to demonstrate the usage of the RECOMMEND statement.

Author: srimon12

README.md

@@ -37,6 +37,7 @@ qql> SEARCH notes SIMILAR TO 'vector databases' LIMIT 5 USING HYBRID RERANK
   - [INSERT — add a point](#insert--add-a-point)
   - [INSERT BULK — batch insert](#insert-bulk--batch-insert-multiple-points)
   - [SEARCH — find similar points](#search--find-similar-points)
+  - [RECOMMEND — retrieve by example IDs](#recommend--retrieve-by-example-ids)
   - [Query-Time Search Params (`EXACT`, `WITH`)](#query-time-search-params-exact-with)
   - [WHERE Clause Filters](#where-clause-filters)
   - [Hybrid Search (USING HYBRID)](#hybrid-search-using-hybrid)
@@ -186,6 +187,8 @@ Inserts a new document into a collection. The `text` field is **mandatory** —
 
 If the collection does not exist yet, it is **created automatically** with the correct vector dimensions.
 
+If you include an `id` field in `VALUES`, QQL uses it as the Qdrant point ID. Supported explicit IDs are unsigned integers or UUID strings. If you omit `id`, QQL generates a UUID automatically.
+
 **Syntax:**
 ```
 INSERT INTO COLLECTION <collection_name> VALUES {<dict>}
@@ -204,6 +207,7 @@ INSERT INTO COLLECTION articles VALUES {'text': 'Qdrant supports cosine similari
 Insert with metadata:
 ```sql
 INSERT INTO COLLECTION articles VALUES {
+  'id': 1001,
   'text': 'Neural networks learn representations from data',
   'author': 'alice',
   'category': 'ml',
@@ -231,13 +235,13 @@ INSERT INTO COLLECTION articles VALUES {'text': 'hello world'}
 **What happens internally:**
 1. The `text` value is embedded into a dense vector using the configured model.
 2. In hybrid mode, a sparse BM25 vector is also generated.
-3. A UUID is auto-generated as the point ID.
-4. All fields (including `text`) are stored in the payload.
+3. If `id` is provided, it is used as the point ID; otherwise a UUID is auto-generated.
+4. All fields except `id` are stored in the payload.
 5. The point is upserted into Qdrant.
 
 **Rules:**
 - `text` is always required. Omitting it raises an error.
-- A point ID (UUID) is generated automatically — you do not provide one.
+- `id`, when provided, must be an unsigned integer or UUID string.
 - If the collection already exists with a different vector size (from a different model), an error is raised with a clear message.
 - Hybrid inserts require a hybrid collection (created with `CREATE COLLECTION ... HYBRID` or auto-created on first `USING HYBRID` insert).
 
@@ -249,6 +253,8 @@ Inserts multiple documents in a single statement. Each item in the array must co
 
 If the collection does not exist yet, it is **created automatically** on the first bulk insert.
 
+Each record may optionally include an `id` field. This is the preferred way to keep seed data deterministic and to make follow-up operations like `RECOMMEND` or `DELETE` reproducible.
+
 **Syntax:**
 ```
 INSERT BULK INTO COLLECTION <collection_name> VALUES [<dict>, <dict>, ...]
@@ -271,9 +277,9 @@ INSERT BULK INTO COLLECTION articles VALUES [
 Bulk insert with metadata:
 ```sql
 INSERT BULK INTO COLLECTION articles VALUES [
-  {'text': 'Attention is all you need', 'author': 'vaswani', 'year': 2017},
-  {'text': 'BERT: Pre-training of deep bidirectional transformers', 'author': 'devlin', 'year': 2018},
-  {'text': 'Language models are few-shot learners', 'author': 'brown', 'year': 2020}
+  {'id': 1001, 'text': 'Attention is all you need', 'author': 'vaswani', 'year': 2017},
+  {'id': 1002, 'text': 'BERT: Pre-training of deep bidirectional transformers', 'author': 'devlin', 'year': 2018},
+  {'id': 1003, 'text': 'Language models are few-shot learners', 'author': 'brown', 'year': 2020}
 ]
 ```
 
@@ -288,7 +294,7 @@ INSERT BULK INTO COLLECTION articles VALUES [
 **Rules:**
 - Every dict in the array must contain a `"text"` key. Missing `text` on any item raises an error with the offending index.
 - An empty array `[]` raises an error.
-- A UUID is auto-generated for each point — you do not provide IDs.
+- `id`, when provided, must be an unsigned integer or UUID string.
 - Supports all the same `USING` clauses as single `INSERT`.
 
 ---
@@ -371,13 +377,57 @@ Results are displayed as a table with three columns:
 ```
 
 - **Score** — similarity score. Higher is more relevant.
-- **ID** — the UUID of the matching point.
+- **ID** — the point ID returned by Qdrant. This may be an integer or a UUID string.
 - **Payload** — all fields stored alongside the vector.
 
 **Important:** Use the same model for SEARCH as you used for INSERT. Mixing models produces meaningless scores because the vectors live in different spaces.
 
 ---
 
+### RECOMMEND — retrieve by example IDs
+
+Performs a Qdrant recommendation query using existing point IDs as positive and optional negative examples.
+
+This is useful when you already know which stored points represent the kind of result you want. Qdrant uses those examples to retrieve nearby points, and QQL automatically excludes the seed IDs from the results.
+
+**Syntax:**
+```sql
+RECOMMEND FROM <collection_name> POSITIVE IDS (1001, 1002) LIMIT <n>
+RECOMMEND FROM <collection_name> POSITIVE IDS (1001, 1002) NEGATIVE IDS (1003) LIMIT <n>
+RECOMMEND FROM <collection_name> POSITIVE IDS (1001) STRATEGY 'best_score' LIMIT <n>
+RECOMMEND FROM <collection_name> POSITIVE IDS (1001) LIMIT <n> WHERE <filter>
+```
+
+**Examples:**
+
+Recommend more results like two known articles:
+```sql
+RECOMMEND FROM articles POSITIVE IDS (1001, 1002) LIMIT 5
+```
+
+Recommend similar results while steering away from one bad example:
+```sql
+RECOMMEND FROM articles POSITIVE IDS (1001, 1002) NEGATIVE IDS (1009) LIMIT 5
+```
+
+Use Qdrant's `best_score` recommendation strategy:
+```sql
+RECOMMEND FROM articles POSITIVE IDS (1001) STRATEGY 'best_score' LIMIT 10
+```
+
+Recommend only within a filtered subset:
+```sql
+RECOMMEND FROM articles POSITIVE IDS (1001) LIMIT 5 WHERE year >= 2020 AND status = 'published'
+```
+
+**Supported strategies:**
+
+- `average_vector`
+- `best_score`
+- `sum_scores`
+
+---
+
 ### Query-Time Search Params (`EXACT`, `WITH`)
 
 QQL supports a small set of Qdrant query-time search parameters on `SEARCH` statements.
@@ -818,7 +868,7 @@ Raises an error if the collection does not exist.
 
 ### DELETE — remove a point
 
-Deletes a single point from a collection by its ID. The point ID is the UUID returned by INSERT.
+Deletes a single point from a collection by its ID. The ID may be an integer or a UUID string, either generated by QQL or supplied explicitly on INSERT.
 
 **Syntax:**
 ```
@@ -890,9 +940,14 @@ SHOW COLLECTIONS
 **Rules:**
 - `--` to end-of-line is a comment and is ignored (inline or full-line)
 - Statements can span multiple lines (e.g. `INSERT BULK ... VALUES [...]`)
+- `RECOMMEND` statements work in `.qql` files the same way they do in the REPL
 - Blank lines between statements are ignored
 - By default all statements run even if one fails; use `--stop-on-error` to halt early
 
+**Included examples:**
+- [`resources/sample.qql`](resources/sample.qql) seeds the demo medical dataset
+- [`resources/sample_v2.qql`](resources/sample_v2.qql) is a compact end-to-end example with explicit IDs and runnable `RECOMMEND` statements
+
 **Example output:**
 ```
 Executing: /path/to/script.qql
@@ -1165,15 +1220,15 @@ result = run_query(
     "INSERT INTO COLLECTION notes VALUES {'text': 'hello world', 'author': 'alice', 'year': 2024}",
     url="http://localhost:6333",
 )
-print(result.message)   # "Inserted 1 point [<uuid>]"
-print(result.data)      # {"id": "...", "collection": "notes"}
+print(result.message)   # "Inserted 1 point [<id>]"
+print(result.data)      # {"id": 1001 or "<uuid>", "collection": "notes"}
 
 # Insert with hybrid vectors
 result = run_query(
     "INSERT INTO COLLECTION notes VALUES {'text': 'hello world'} USING HYBRID",
     url="http://localhost:6333",
 )
-print(result.message)   # "Inserted 1 point [<uuid>] (hybrid)"
+print(result.message)   # "Inserted 1 point [<id>] (hybrid)"
 
 # Dense search with WHERE filter
 result = run_query(
@@ -1228,9 +1283,10 @@ class ExecutionResult:
 
 | Operation | `result.data` type |
 |---|---|
-| INSERT (dense) | `{"id": "<uuid>", "collection": "<name>"}` |
-| INSERT (hybrid) | `{"id": "<uuid>", "collection": "<name>"}` |
+| INSERT (dense) | `{"id": int | "<uuid>", "collection": "<name>"}` |
+| INSERT (hybrid) | `{"id": int | "<uuid>", "collection": "<name>"}` |
 | SEARCH | `[{"id": str, "score": float, "payload": dict}, ...]` |
+| RECOMMEND | `[{"id": str, "score": float, "payload": dict}, ...]` |
 | SHOW COLLECTIONS | `["name1", "name2", ...]` |
 | CREATE COLLECTION | `None` |
 | DROP COLLECTION | `None` |

resources/sample_v2.qql

@@ -0,0 +1,105 @@
+-- QQL sample v2
+-- Compact end-to-end showcase for deterministic inserts, search, query-time
+-- params, recommendation, and hybrid retrieval.
+
+SHOW COLLECTIONS
+
+-- Dense collection
+CREATE COLLECTION qql_sample_v2
+
+INSERT BULK INTO COLLECTION qql_sample_v2 VALUES [
+  {
+    'id': 1001,
+    'text': 'STEMI requires emergent revascularization with primary PCI and dual antiplatelet therapy.',
+    'department': 'cardiology',
+    'topic': 'acute_coronary_syndrome',
+    'year': 2024
+  },
+  {
+    'id': 1002,
+    'text': 'Heart failure with reduced ejection fraction is treated with ARNI, beta-blocker, MRA, and SGLT2 inhibitor therapy.',
+    'department': 'cardiology',
+    'topic': 'heart_failure',
+    'year': 2024
+  },
+  {
+    'id': 2001,
+    'text': 'Acute ischemic stroke management includes rapid imaging, alteplase within the treatment window, and thrombectomy in selected patients.',
+    'department': 'neurology',
+    'topic': 'stroke',
+    'year': 2024
+  },
+  {
+    'id': 2002,
+    'text': 'Transient ischemic attack requires urgent secondary prevention and vascular risk stratification.',
+    'department': 'neurology',
+    'topic': 'stroke',
+    'year': 2023
+  },
+  {
+    'id': 2003,
+    'text': 'Secondary stroke prevention includes antiplatelet therapy, statins, blood pressure control, and carotid evaluation when indicated.',
+    'department': 'neurology',
+    'topic': 'stroke_prevention',
+    'year': 2024
+  },
+  {
+    'id': 3001,
+    'text': 'COPD exacerbations are managed with bronchodilators, corticosteroids, and antibiotics when indicated.',
+    'department': 'pulmonology',
+    'topic': 'copd',
+    'year': 2024
+  }
+]
+
+-- Basic dense search
+SEARCH qql_sample_v2 SIMILAR TO 'stroke thrombolysis and thrombectomy' LIMIT 3
+
+-- Dense search with filter
+SEARCH qql_sample_v2 SIMILAR TO 'secondary stroke prevention' LIMIT 3 WHERE department = 'neurology'
+
+-- Query-time search params
+SEARCH qql_sample_v2 SIMILAR TO 'acute coronary syndrome' LIMIT 3 EXACT
+SEARCH qql_sample_v2 SIMILAR TO 'stroke prevention' LIMIT 3 WITH { hnsw_ef: 128 }
+
+-- Recommendation from known example IDs
+RECOMMEND FROM qql_sample_v2
+  POSITIVE IDS (2001)
+  LIMIT 3
+
+RECOMMEND FROM qql_sample_v2
+  POSITIVE IDS (2001, 2002)
+  NEGATIVE IDS (1001)
+  STRATEGY 'best_score'
+  LIMIT 3
+  WHERE department = 'neurology'
+
+-- Hybrid collection
+CREATE COLLECTION qql_sample_v2_hybrid HYBRID
+
+INSERT BULK INTO COLLECTION qql_sample_v2_hybrid VALUES [
+  {
+    'id': 4001,
+    'text': 'Transformer attention mechanisms improve long-context sequence modeling and retrieval quality.',
+    'domain': 'ml',
+    'year': 2024
+  },
+  {
+    'id': 4002,
+    'text': 'Sparse retrieval with BM25 remains strong for exact terminology and keyword-heavy document search.',
+    'domain': 'ir',
+    'year': 2023
+  },
+  {
+    'id': 4003,
+    'text': 'Hybrid retrieval combines dense semantic matching with sparse keyword search using reciprocal rank fusion.',
+    'domain': 'ir',
+    'year': 2024
+  }
+] USING HYBRID
+
+-- Hybrid and sparse-only search
+SEARCH qql_sample_v2_hybrid SIMILAR TO 'keyword retrieval and bm25' LIMIT 3 USING HYBRID
+SEARCH qql_sample_v2_hybrid SIMILAR TO 'keyword retrieval and bm25' LIMIT 3 USING SPARSE
+
+SHOW COLLECTIONS

src/qql/ast_nodes.py

@@ -169,6 +169,17 @@ class SearchStmt:
     rerank_model: str | None = None         # cross-encoder model; None → CrossEncoderEmbedder.DEFAULT_MODEL
     with_clause: SearchWith | None = None
 
+
+@dataclass(frozen=True)
+class RecommendStmt:
+    collection: str
+    positive_ids: tuple[str | int, ...]
+    negative_ids: tuple[str | int, ...] = ()
+    limit: int = 10
+    strategy: str | None = None
+    query_filter: FilterExpr | None = None
+
+
 @dataclass(frozen=True)
 class DeleteStmt:
     collection: str
@@ -183,5 +194,6 @@ class DeleteStmt:
     | DropCollectionStmt
     | ShowCollectionsStmt
     | SearchStmt
+    | RecommendStmt
     | DeleteStmt
 )

src/qql/cli.py

@@ -25,11 +25,13 @@
 
   [yellow]INSERT INTO COLLECTION[/yellow] <name> [yellow]VALUES[/yellow] {[yellow]'text'[/yellow]: '...', ...}
       Insert a point. 'text' is required and auto-vectorized.
+      Optional: include [yellow]'id'[/yellow] in VALUES as an integer or UUID
       Optional: [yellow]USING MODEL[/yellow] '<model>'
       Optional: [yellow]USING HYBRID[/yellow] [DENSE MODEL '<model>'] [SPARSE MODEL '<model>']
 
   [yellow]INSERT BULK INTO COLLECTION[/yellow] <name> [yellow]VALUES[/yellow] [{[yellow]'text'[/yellow]: '...', ...}, ...]
       Batch insert multiple points in a single call. Each dict must contain 'text'.
+      Optional: each dict may include [yellow]'id'[/yellow] as an integer or UUID.
       Supports the same [yellow]USING[/yellow] clauses as INSERT.
 
   [yellow]CREATE COLLECTION[/yellow] <name> [[yellow]HYBRID[/yellow]]
@@ -53,6 +55,13 @@
       Optional: [yellow]EXACT[/yellow]   bypass HNSW and perform exact search
       Optional: [yellow]WITH[/yellow] { hnsw_ef: <int>, exact: <bool>, acorn: <bool> }   search parameters
 
+  [yellow]RECOMMEND FROM[/yellow] <name> [yellow]POSITIVE IDS[/yellow] (<id>, ...)
+      Find points similar to known examples.
+      Optional: [yellow]NEGATIVE IDS[/yellow] (<id>, ...)
+      Optional: [yellow]STRATEGY[/yellow] 'average_vector|best_score|sum_scores'
+      Optional: [yellow]WHERE[/yellow] <filter>
+      Requires: [yellow]LIMIT[/yellow] <n>
+
   [yellow]DELETE FROM[/yellow] <name> [yellow]WHERE id =[/yellow] '<id>'
       Delete a point by its ID.
 
@@ -66,8 +75,8 @@
       The file can be re-imported with EXECUTE.
 
 Keyboard shortcuts:
-  ← → arrows   move cursor within the current line
-  ↑ ↓ arrows   scroll through command history
+  Left/Right arrows   move cursor within the current line
+  Up/Down arrows   scroll through command history
   Ctrl-A / Ctrl-E   jump to beginning / end of line
   Ctrl-C   cancel current input
   Ctrl-D   exit shell
@@ -215,7 +224,7 @@ def dump(collection: str, output: str) -> None:
     from .dumper import dump_collection
 
     console.print(
-        f"[bold cyan]Dumping:[/bold cyan] '{collection}'  →  {output}\n"
+        f"[bold cyan]Dumping:[/bold cyan] '{collection}'  ->  {output}\n"
     )
     written, skipped = dump_collection(collection, output, client, console, err_console)
 
@@ -315,7 +324,7 @@ def _launch_repl(cfg: QQLConfig) -> None:
                 coll_name, out_path = parts[1], parts[2]
             from .dumper import dump_collection
             console.print(
-                f"[bold cyan]Dumping:[/bold cyan] '{coll_name}'  →  {out_path}\n"
+                f"[bold cyan]Dumping:[/bold cyan] '{coll_name}'  ->  {out_path}\n"
             )
             written, skipped = dump_collection(
                 coll_name, out_path, client, console, err_console
@@ -348,7 +357,7 @@ def _run_and_print(executor: Executor, query: str) -> None:
         err_console.print(f"[bold red]Failed:[/bold red] {result.message}")
         return
 
-    console.print(f"[bold green]✓[/bold green] {result.message}")
+    console.print(f"[bold green]OK[/bold green] {result.message}")
 
     if result.data is None:
         return

src/qql/dumper.py

@@ -160,7 +160,9 @@ def dump_collection(
                 if "text" not in payload:
                     skipped += 1
                     continue
-                valid.append(payload)
+                dump_payload = dict(payload)
+                dump_payload["id"] = rec.id
+                valid.append(dump_payload)
 
             if valid:
                 f.write(