qql-cli 2.1.0__tar.gz → 2.2.0__tar.gz

{qql_cli-2.1.0 → qql_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qql-cli
-Version: 2.1.0
+Version: 2.2.0
 Summary: 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.
 Project-URL: Homepage, https://github.com/pavanjava/qql
 Project-URL: Repository, https://github.com/pavanjava/qql
@@ -56,9 +56,9 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/qql-cli?color=blue&label=PyPI)](https://pypi.org/project/qql-cli/)
 [![Python 3.12+](https://img.shields.io/pypi/pyversions/qql-cli)](https://pypi.org/project/qql-cli/)
 [![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-375%20passing-brightgreen)](tests/)
+[![Tests](https://img.shields.io/badge/tests-405%20passing-brightgreen)](tests/)
 
-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), 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}
@@ -99,7 +99,7 @@ Your query string
   Qdrant instance
 ```
 
-When you run `INSERT`, the `text` field is automatically converted into a dense vector using [Fastembed](https://github.com/qdrant/fastembed). In **hybrid mode** (`USING HYBRID`), a sparse BM25 vector is also generated alongside the dense vector, and searches use Qdrant's Reciprocal Rank Fusion (RRF) to merge the results of both retrieval methods.
+When you run `INSERT`, the `text` field is automatically converted into a dense vector using [Fastembed](https://github.com/qdrant/fastembed). In **hybrid mode** (`USING HYBRID`), a sparse BM25 vector is also generated alongside the dense vector, and searches use Qdrant's Reciprocal Rank Fusion (RRF) by default to merge the results of both retrieval methods. You can switch hybrid search to DBSF with `FUSION 'dbsf'`.
 
 ---
 
@@ -133,7 +133,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 / RECOMMEND / Hybrid / RERANK](docs/search.md) | Semantic search, 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 |
@@ -153,11 +153,20 @@ INSERT BULK INTO COLLECTION articles VALUES [{'text': '...'}, {'text': '...'}]
 SEARCH articles SIMILAR TO 'query' LIMIT 10
 SEARCH articles SIMILAR TO 'query' LIMIT 10 WHERE year >= 2020
 SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID
+SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID FUSION 'dbsf'
 SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID RERANK
 
+-- Scroll
+SCROLL FROM articles LIMIT 50
+SCROLL FROM articles WHERE year >= 2024 LIMIT 50
+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
@@ -188,7 +197,7 @@ Tests do not require a running Qdrant instance — the Qdrant client is mocked.
 pytest tests/ -v
 ```
 
-Expected: **375 tests passing**.
+Expected: **405 tests passing**.
 
 ---
 

{qql_cli-2.1.0 → qql_cli-2.2.0}/README.md

@@ -5,9 +5,9 @@
 [![PyPI version](https://img.shields.io/pypi/v/qql-cli?color=blue&label=PyPI)](https://pypi.org/project/qql-cli/)
 [![Python 3.12+](https://img.shields.io/pypi/pyversions/qql-cli)](https://pypi.org/project/qql-cli/)
 [![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-375%20passing-brightgreen)](tests/)
+[![Tests](https://img.shields.io/badge/tests-405%20passing-brightgreen)](tests/)
 
-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), 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}
@@ -48,7 +48,7 @@ Your query string
   Qdrant instance
 ```
 
-When you run `INSERT`, the `text` field is automatically converted into a dense vector using [Fastembed](https://github.com/qdrant/fastembed). In **hybrid mode** (`USING HYBRID`), a sparse BM25 vector is also generated alongside the dense vector, and searches use Qdrant's Reciprocal Rank Fusion (RRF) to merge the results of both retrieval methods.
+When you run `INSERT`, the `text` field is automatically converted into a dense vector using [Fastembed](https://github.com/qdrant/fastembed). In **hybrid mode** (`USING HYBRID`), a sparse BM25 vector is also generated alongside the dense vector, and searches use Qdrant's Reciprocal Rank Fusion (RRF) by default to merge the results of both retrieval methods. You can switch hybrid search to DBSF with `FUSION 'dbsf'`.
 
 ---
 
@@ -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 / RECOMMEND / Hybrid / RERANK](docs/search.md) | Semantic search, 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 |
@@ -102,11 +102,20 @@ INSERT BULK INTO COLLECTION articles VALUES [{'text': '...'}, {'text': '...'}]
 SEARCH articles SIMILAR TO 'query' LIMIT 10
 SEARCH articles SIMILAR TO 'query' LIMIT 10 WHERE year >= 2020
 SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID
+SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID FUSION 'dbsf'
 SEARCH articles SIMILAR TO 'query' LIMIT 10 USING HYBRID RERANK
 
+-- Scroll
+SCROLL FROM articles LIMIT 50
+SCROLL FROM articles WHERE year >= 2024 LIMIT 50
+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
@@ -137,7 +146,7 @@ Tests do not require a running Qdrant instance — the Qdrant client is mocked.
 pytest tests/ -v
 ```
 
-Expected: **375 tests passing**.
+Expected: **405 tests passing**.
 
 ---
 

{qql_cli-2.1.0 → qql_cli-2.2.0}/docs/getting-started.md

@@ -24,7 +24,7 @@ Your query string
   Qdrant instance
 ```
 
-When you run `INSERT`, the `text` field is automatically converted into a dense vector using [Fastembed](https://github.com/qdrant/fastembed). In **hybrid mode** (`USING HYBRID`), a sparse BM25 vector is also generated alongside the dense vector, and searches use Qdrant's Reciprocal Rank Fusion (RRF) to merge the results of both retrieval methods.
+When you run `INSERT`, the `text` field is automatically converted into a dense vector using [Fastembed](https://github.com/qdrant/fastembed). In **hybrid mode** (`USING HYBRID`), a sparse BM25 vector is also generated alongside the dense vector, and searches use Qdrant's Reciprocal Rank Fusion (RRF) by default to merge the results of both retrieval methods. You can override that with `FUSION 'dbsf'` on hybrid searches.
 
 ---
 
@@ -138,8 +138,14 @@ SEARCH notes SIMILAR TO 'vector storage engines' LIMIT 3
 -- Filter results
 SEARCH notes SIMILAR TO 'vector databases' LIMIT 5 WHERE year >= 2023
 
+-- Browse with pagination
+SCROLL FROM notes LIMIT 10
+
 -- List all collections
 SHOW COLLECTIONS
+
+-- Retrieve a point by ID
+SELECT * FROM notes WHERE id = 1
 ```
 
 ---
@@ -147,7 +153,7 @@ SHOW COLLECTIONS
 ## Next Steps
 
 - [INSERT / INSERT BULK](insert.md) — adding documents
-- [SEARCH / 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

{qql_cli-2.1.0 → qql_cli-2.2.0}/docs/index.html

@@ -114,7 +114,7 @@
     <a href="https://pypi.org/project/qql-cli/"><img src="https://img.shields.io/pypi/v/qql-cli?color=blue&label=PyPI" alt="PyPI version" /></a>
     <a href="https://pypi.org/project/qql-cli/"><img src="https://img.shields.io/pypi/pyversions/qql-cli" alt="Python versions" /></a>
     <a href="https://github.com/pavanjava/qql/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" /></a>
-    <a href="https://github.com/pavanjava/qql/actions"><img src="https://img.shields.io/badge/tests-375%20passing-brightgreen" alt="375 tests" /></a>
+    <a href="https://github.com/pavanjava/qql/actions"><img src="https://img.shields.io/badge/tests-405%20passing-brightgreen" alt="405 tests" /></a>
   </div>
 
   <pre><span class="cmt"># Install</span>
@@ -148,8 +148,8 @@
       <p>Adding documents, batch inserts, payload types</p>
     </a>
     <a class="card" href="search">
-      <h3>SEARCH / RECOMMEND</h3>
-      <p>Semantic search, 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>

{qql_cli-2.1.0 → qql_cli-2.2.0}/docs/programmatic.md

@@ -40,6 +40,15 @@ result = run_query(
 for hit in result.data:
     print(hit["score"], hit["payload"])
 
+# Scroll / pagination
+result = run_query(
+    "SCROLL FROM notes LIMIT 2",
+    url="http://localhost:6333",
+)
+for point in result.data["points"]:
+    print(point["id"], point["payload"])
+print(result.data["next_offset"])
+
 # Bulk insert (all records embedded and upserted in one call)
 result = run_query(
     """INSERT BULK INTO COLLECTION notes VALUES [
@@ -58,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",
@@ -111,7 +127,9 @@ 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}, ...]` |
 | SHOW COLLECTIONS | `["name1", "name2", ...]` |
 | CREATE COLLECTION | `None` |

{qql_cli-2.1.0 → qql_cli-2.2.0}/docs/reference.md

@@ -36,6 +36,9 @@ SEARCH docs SIMILAR TO 'hello' LIMIT 5 USING MODEL 'BAAI/bge-small-en-v1.5'
 -- Hybrid with custom dense model
 SEARCH docs SIMILAR TO 'hello' LIMIT 5 USING HYBRID DENSE MODEL 'BAAI/bge-base-en-v1.5'
 
+-- Hybrid with explicit fusion strategy
+SEARCH docs SIMILAR TO 'hello' LIMIT 5 USING HYBRID FUSION 'dbsf'
+
 -- Hybrid with both custom
 SEARCH docs SIMILAR TO 'hello' LIMIT 5
   USING HYBRID DENSE MODEL 'BAAI/bge-base-en-v1.5' SPARSE MODEL 'prithivida/Splade_PP_en_v1'
@@ -159,7 +162,7 @@ Tests do not require a running Qdrant instance — the Qdrant client is mocked.
 pytest tests/ -v
 ```
 
-Expected output: **375 tests passing**.
+Expected output: **405 tests passing**.
 
 ---
 
@@ -171,12 +174,14 @@ Expected output: **375 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 / 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` |
 | `Expected ')' ...` | Unclosed parenthesis in WHERE clause | Add the missing `)` to close the group |
 | `Qdrant error during SEARCH: ...` | Hybrid search on a non-hybrid collection, or wrong vector names | Ensure the collection was created with `HYBRID` before using `USING HYBRID` in INSERT/SEARCH |
+| `Qdrant error during SCROLL: ...` | Qdrant rejected scroll request | Verify collection state, filter, and cursor (`AFTER`) value |
 | `Unknown index type '...'` | Invalid schema type in CREATE INDEX | Use one of: `keyword`, `integer`, `float`, `bool`, `text`, `geo`, `datetime` |
 | `Qdrant error during CREATE INDEX: ...` | Qdrant rejected the index creation | Check field name and collection state |

{qql_cli-2.1.0 → qql_cli-2.2.0}/docs/search.md

@@ -1,4 +1,4 @@
-# SEARCH, RECOMMEND, Hybrid Search & Reranking
+# SEARCH, SELECT, SCROLL, RECOMMEND, Hybrid Search & Reranking
 
 ---
 
@@ -14,7 +14,7 @@ SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n>
 SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> USING MODEL '<model_name>'
 SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> [USING MODEL '<model>'] WHERE <filter>
 SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> USING HYBRID
-SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> USING HYBRID [DENSE MODEL '<model>'] [SPARSE MODEL '<model>'] [WHERE <filter>]
+SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> USING HYBRID [FUSION 'rrf|dbsf'] [DENSE MODEL '<model>'] [SPARSE MODEL '<model>'] [WHERE <filter>]
 SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> USING SPARSE [MODEL '<sparse_model>']
 SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> EXACT
 SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> [USING ...] [WHERE <filter>] [RERANK] WITH { hnsw_ef: <n>, exact: true|false, acorn: true|false }
@@ -33,7 +33,7 @@ Search only papers published after 2020:
 SEARCH articles SIMILAR TO 'deep learning' LIMIT 10 WHERE year > 2020
 ```
 
-Hybrid search (combines dense semantic + sparse BM25 keyword retrieval via RRF):
+Hybrid search (combines dense semantic + sparse BM25 keyword retrieval via RRF by default):
 ```sql
 SEARCH articles SIMILAR TO 'attention mechanism' LIMIT 10 USING HYBRID
 ```
@@ -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.
@@ -98,15 +120,41 @@ SEARCH articles SIMILAR TO 'RAG' LIMIT 10 WHERE tag = 'li' WITH { acorn: true }
 
 ---
 
+## SCROLL — pagination / browsing
+
+Use `SCROLL` to iterate through points in a collection page by page.
+
+**Syntax:**
+```sql
+SCROLL FROM <collection_name> LIMIT <n>
+SCROLL FROM <collection_name> WHERE <filter> LIMIT <n>
+SCROLL FROM <collection_name> AFTER '<point_id>' LIMIT <n>
+SCROLL FROM <collection_name> WHERE <filter> AFTER <point_id> LIMIT <n>
+```
+
+**Examples:**
+```sql
+SCROLL FROM articles LIMIT 50
+SCROLL FROM articles WHERE year >= 2024 LIMIT 50
+SCROLL FROM articles AFTER 'cursor-id' LIMIT 50
+```
+
+**Behavior:**
+- Returns points in ID order with payloads.
+- Returns a `next_offset` cursor when more points are available.
+- Use `AFTER <next_offset>` to fetch the next page.
+
+---
+
 ## Hybrid Search (USING HYBRID)
 
-Hybrid search combines **dense semantic vectors** and **sparse BM25 keyword vectors** in a single query and merges the results with Qdrant's **Reciprocal Rank Fusion (RRF)** algorithm. This typically outperforms either method alone.
+Hybrid search combines **dense semantic vectors** and **sparse BM25 keyword vectors** in a single query. By default QQL merges the two result sets with Qdrant's **Reciprocal Rank Fusion (RRF)** algorithm, and you can optionally switch to **DBSF** with a `FUSION` clause.
 
 ### How it works internally
 
 1. Both a dense vector (`TextEmbedding`) and a sparse BM25 vector (`SparseTextEmbedding`) are generated from your query text.
 2. Qdrant fetches the top candidates from each index independently (`prefetch limit = LIMIT × 4`).
-3. The two result lists are merged using RRF — a rank-based fusion that does not require score normalization.
+3. The two result lists are merged using the selected fusion strategy (`RRF` by default, or `DBSF` when requested).
 4. The final top-N results are returned.
 
 ### Step 1: Create a hybrid collection
@@ -139,6 +187,9 @@ SEARCH articles SIMILAR TO 'transformer architecture' LIMIT 10 USING HYBRID
 -- Hybrid search with a WHERE filter
 SEARCH articles SIMILAR TO 'attention' LIMIT 10 USING HYBRID WHERE year >= 2017
 
+-- Hybrid with DBSF fusion
+SEARCH articles SIMILAR TO 'hybrid retrieval' LIMIT 10 USING HYBRID FUSION 'dbsf'
+
 -- Hybrid with custom dense model
 SEARCH articles SIMILAR TO 'embeddings' LIMIT 5
   USING HYBRID DENSE MODEL 'BAAI/bge-base-en-v1.5'
@@ -154,6 +205,7 @@ SEARCH articles SIMILAR TO 'sparse retrieval' LIMIT 5
 |---|---|
 | Dense model | configured default (`sentence-transformers/all-MiniLM-L6-v2`) |
 | Sparse model | `Qdrant/bm25` |
+| Fusion | `rrf` |
 
 ### Dense vs. hybrid — when to use which
 

{qql_cli-2.1.0 → qql_cli-2.2.0}/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" }

{qql_cli-2.1.0 → qql_cli-2.2.0}/src/qql/ast_nodes.py

@@ -180,6 +180,20 @@ class ShowCollectionsStmt:
     pass
 
 
+@dataclass(frozen=True)
+class SelectStmt:
+    collection: str
+    point_id: str | int
+
+
+@dataclass(frozen=True)
+class ScrollStmt:
+    collection: str
+    limit: int
+    query_filter: FilterExpr | None = None
+    after: str | int | None = None
+
+
 @dataclass(frozen=True)
 class SearchStmt:
     collection: str
@@ -187,6 +201,7 @@ class SearchStmt:
     limit: int
     model: str | None               # dense model; None → use config default
     hybrid: bool = False            # if True, use prefetch+RRF hybrid search
+    fusion: str | None = None       # hybrid fusion strategy; None → default rrf
     sparse_only: bool = False       # if True, query only the sparse vector (no dense)
     sparse_model: str | None = None # sparse model for hybrid/sparse-only; None → SparseEmbedder.DEFAULT_MODEL
     query_filter: FilterExpr | None = None  # optional WHERE clause; default keeps existing tests valid
@@ -225,6 +240,8 @@ ASTNode = (
     | CreateIndexStmt
     | DropCollectionStmt
     | ShowCollectionsStmt
+    | SelectStmt
+    | ScrollStmt
     | SearchStmt
     | RecommendStmt
     | DeleteStmt

{qql_cli-2.1.0 → qql_cli-2.2.0}/src/qql/cli.py

@@ -49,10 +49,18 @@ Available statements:
   [yellow]SHOW COLLECTIONS[/yellow]
       List all collections in the connected Qdrant instance.
 
+  [yellow]SCROLL FROM[/yellow] <name> [yellow]LIMIT[/yellow] <n>
+      Paginate points by ID order.
+      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>'
-      Optional: [yellow]USING HYBRID[/yellow] [DENSE MODEL '<model>'] [SPARSE MODEL '<model>']
+      Optional: [yellow]USING HYBRID[/yellow] [FUSION 'rrf|dbsf'] [DENSE MODEL '<model>'] [SPARSE MODEL '<model>']
       Optional: [yellow]USING SPARSE[/yellow] [MODEL '<model>']   sparse-vector-only search
       Optional: [yellow]WHERE[/yellow] <filter>   (e.g. WHERE year > 2020 AND status = 'ok')
       Optional: [yellow]RERANK[/yellow] [MODEL '<model>']   rerank results with a cross-encoder
@@ -400,5 +408,28 @@ def _run_and_print(executor: Executor, query: str) -> None:
         console.print(table)
         return
 
+    # Pretty-print scroll results
+    if isinstance(result.data, dict) and "points" in result.data and "next_offset" in result.data:
+        points = result.data["points"]
+        if points:
+            table = Table(show_header=True, header_style="bold cyan")
+            table.add_column("ID")
+            table.add_column("Payload")
+            for point in points:
+                table.add_row(point["id"], str(point["payload"]))
+            console.print(table)
+        if result.data["next_offset"] is not 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)

{qql_cli-2.1.0 → qql_cli-2.2.0}/src/qql/executor.py

@@ -76,6 +76,8 @@ from .ast_nodes import (
     QuantizationConfig,
     QuantizationType,
     RecommendStmt,
+    SelectStmt,
+    ScrollStmt,
     SearchStmt,
     SearchWith,
     ShowCollectionsStmt,
@@ -115,6 +117,10 @@ class Executor:
             return self._execute_drop(node)
         if isinstance(node, ShowCollectionsStmt):
             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):
@@ -412,6 +418,65 @@ class Executor:
             data=names,
         )
 
+    def _execute_scroll(self, node: ScrollStmt) -> ExecutionResult:
+        if not self._client.collection_exists(node.collection):
+            raise QQLRuntimeError(f"Collection '{node.collection}' does not exist")
+
+        scroll_filter: Filter | None = None
+        if node.query_filter is not None:
+            scroll_filter = self._wrap_as_filter(
+                self._build_qdrant_filter(node.query_filter)
+            )
+
+        try:
+            records, next_offset = self._client.scroll(
+                collection_name=node.collection,
+                scroll_filter=scroll_filter,
+                limit=node.limit,
+                offset=node.after,
+                with_payload=True,
+                with_vectors=False,
+            )
+        except UnexpectedResponse as e:
+            raise QQLRuntimeError(f"Qdrant error during SCROLL: {e}") from e
+
+        points = [
+            {"id": str(rec.id), "payload": rec.payload or {}}
+            for rec in records
+        ]
+        return ExecutionResult(
+            success=True,
+            message=f"Scrolled {len(points)} point(s) from '{node.collection}'",
+            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")
@@ -429,7 +494,7 @@ class Executor:
         # enough material to reorder; only `node.limit` results are returned.
         fetch_limit = node.limit * _RERANK_FETCH_MULTIPLIER if node.rerank else node.limit
 
-        # ── Hybrid SEARCH: prefetch dense+sparse, fuse with RRF ───────────
+        # ── Hybrid SEARCH: prefetch dense+sparse, fuse with the requested strategy ──
         if node.hybrid:
             dense_model = node.model or self._config.default_model
             sparse_model_name = node.sparse_model or SparseEmbedder.DEFAULT_MODEL
@@ -460,7 +525,7 @@ class Executor:
                             params=search_params,
                         ),
                     ],
-                    query=FusionQuery(fusion=Fusion.RRF),
+                    query=FusionQuery(fusion=self._resolve_hybrid_fusion(node.fusion)),
                     limit=fetch_limit,
                     query_filter=qdrant_filter,
                 )
@@ -563,6 +628,15 @@ class Executor:
             data=results,
         )
 
+    def _resolve_hybrid_fusion(self, fusion: str | None) -> Fusion:
+        if fusion is None or fusion == "rrf":
+            return Fusion.RRF
+        if fusion == "dbsf":
+            return Fusion.DBSF
+        raise QQLRuntimeError(
+            f"Unsupported hybrid fusion '{fusion}'; expected 'rrf' or 'dbsf'"
+        )
+
     def _execute_recommend(self, node: RecommendStmt) -> ExecutionResult:
         if not self._client.collection_exists(node.collection):
             raise QQLRuntimeError(f"Collection '{node.collection}' does not exist")

{qql_cli-2.1.0 → qql_cli-2.2.0}/src/qql/lexer.py

@@ -14,6 +14,7 @@ class TokenKind(Enum):
     USING = auto()
     MODEL = auto()
     HYBRID = auto()
+    FUSION = auto()
     DENSE = auto()
     SPARSE = auto()
     RERANK = auto()
@@ -34,7 +35,9 @@ class TokenKind(Enum):
     ON = auto()
     DROP = auto()
     SHOW = auto()
+    SELECT = auto()
     COLLECTIONS = auto()
+    SCROLL = auto()
     SEARCH = auto()
     RECOMMEND = auto()
     POSITIVE = auto()
@@ -47,6 +50,7 @@ class TokenKind(Enum):
     OFFSET = auto()
     SCORE = auto()
     THRESHOLD = auto()
+    AFTER = auto()
     LOOKUP = auto()
     VECTOR = auto()
     DELETE = auto()
@@ -79,6 +83,7 @@ class TokenKind(Enum):
     RBRACKET = auto()
     LPAREN = auto()
     RPAREN = auto()
+    STAR = auto()
     COLON = auto()
     COMMA = auto()
     EQUALS = auto()
@@ -102,6 +107,7 @@ _KEYWORDS: dict[str, TokenKind] = {
     "USING": TokenKind.USING,
     "MODEL": TokenKind.MODEL,
     "HYBRID": TokenKind.HYBRID,
+    "FUSION": TokenKind.FUSION,
     "DENSE": TokenKind.DENSE,
     "SPARSE": TokenKind.SPARSE,
     "RERANK": TokenKind.RERANK,
@@ -122,7 +128,9 @@ _KEYWORDS: dict[str, TokenKind] = {
     "ON": TokenKind.ON,
     "DROP": TokenKind.DROP,
     "SHOW": TokenKind.SHOW,
+    "SELECT": TokenKind.SELECT,
     "COLLECTIONS": TokenKind.COLLECTIONS,
+    "SCROLL": TokenKind.SCROLL,
     "SEARCH": TokenKind.SEARCH,
     "RECOMMEND": TokenKind.RECOMMEND,
     "POSITIVE": TokenKind.POSITIVE,
@@ -135,6 +143,7 @@ _KEYWORDS: dict[str, TokenKind] = {
     "OFFSET": TokenKind.OFFSET,
     "SCORE": TokenKind.SCORE,
     "THRESHOLD": TokenKind.THRESHOLD,
+    "AFTER": TokenKind.AFTER,
     "LOOKUP": TokenKind.LOOKUP,
     "VECTOR": TokenKind.VECTOR,
     "DELETE": TokenKind.DELETE,
@@ -197,6 +206,9 @@ class Lexer:
             elif ch == ")":
                 tokens.append(Token(TokenKind.RPAREN, ")", i))
                 i += 1
+            elif ch == "*":
+                tokens.append(Token(TokenKind.STAR, "*", i))
+                i += 1
             elif ch == ":":
                 tokens.append(Token(TokenKind.COLON, ":", i))
                 i += 1

{qql_cli-2.1.0 → qql_cli-2.2.0}/src/qql/parser.py

@@ -26,6 +26,8 @@ from .ast_nodes import (
     QuantizationConfig,
     QuantizationType,
     RecommendStmt,
+    SelectStmt,
+    ScrollStmt,
     SearchStmt,
     SearchWith,
     ShowCollectionsStmt,
@@ -43,6 +45,8 @@ _CMP_OPS: dict[TokenKind, str] = {
     TokenKind.LTE:        "<=",
 }
 
+_HYBRID_FUSION_VALUES = {"rrf", "dbsf"}
+
 
 class Parser:
     def __init__(self, tokens: list[Token]) -> None:
@@ -61,6 +65,10 @@ class Parser:
             node = self._parse_drop()
         elif tok.kind == TokenKind.SHOW:
             node = self._parse_show()
+        elif tok.kind == TokenKind.SCROLL:
+            node = self._parse_scroll()
+        elif tok.kind == TokenKind.SELECT:
+            node = self._parse_select()
         elif tok.kind == TokenKind.SEARCH:
             node = self._parse_search()
         elif tok.kind == TokenKind.RECOMMEND:
@@ -288,6 +296,43 @@ class Parser:
         self._expect(TokenKind.COLLECTIONS)
         return ShowCollectionsStmt()
 
+    def _parse_scroll(self) -> ScrollStmt:
+        self._expect(TokenKind.SCROLL)
+        self._expect(TokenKind.FROM)
+        collection = self._parse_identifier()
+
+        query_filter: FilterExpr | None = None
+        after: str | int | None = None
+
+        if self._peek().kind == TokenKind.WHERE:
+            self._advance()
+            query_filter = self._parse_filter_expr()
+
+        if self._peek().kind == TokenKind.AFTER:
+            self._advance()
+            after = self._parse_point_id_value("SCROLL AFTER")
+
+        self._expect(TokenKind.LIMIT)
+        limit = int(self._expect(TokenKind.INTEGER).value)
+
+        return ScrollStmt(
+            collection=collection,
+            limit=limit,
+            query_filter=query_filter,
+            after=after,
+        )
+
+    def _parse_select(self) -> SelectStmt:
+        self._expect(TokenKind.SELECT)
+        self._expect(TokenKind.STAR)
+        self._expect(TokenKind.FROM)
+        collection = self._parse_identifier()
+        self._expect(TokenKind.WHERE)
+        self._expect(TokenKind.ID)
+        self._expect(TokenKind.EQUALS)
+        point_id = self._parse_point_id_value("SELECT")
+        return SelectStmt(collection=collection, point_id=point_id)
+
     def _parse_search(self) -> SearchStmt:
         self._expect(TokenKind.SEARCH)
         collection = self._parse_identifier()
@@ -304,6 +349,7 @@ class Parser:
 
         model: str | None = None
         hybrid: bool = False
+        fusion: str | None = None
         sparse_only: bool = False
         sparse_model: str | None = None
         if self._peek().kind == TokenKind.USING:
@@ -311,9 +357,18 @@ class Parser:
             if self._peek().kind == TokenKind.HYBRID:
                 self._advance()  # consume HYBRID
                 hybrid = True
-                # Optional DENSE MODEL and/or SPARSE MODEL sub-clauses, any order
-                while self._peek().kind in (TokenKind.DENSE, TokenKind.SPARSE):
+                # Optional FUSION / DENSE MODEL / SPARSE MODEL sub-clauses, any order.
+                while self._peek().kind in (TokenKind.FUSION, TokenKind.DENSE, TokenKind.SPARSE):
                     sub = self._advance()
+                    if sub.kind == TokenKind.FUSION:
+                        value_tok = self._expect(TokenKind.STRING)
+                        fusion = value_tok.value.lower()
+                        if fusion not in _HYBRID_FUSION_VALUES:
+                            raise QQLSyntaxError(
+                                f"Unsupported hybrid fusion '{value_tok.value}'; expected 'rrf' or 'dbsf'",
+                                value_tok.pos,
+                            )
+                        continue
                     self._expect(TokenKind.MODEL)
                     m = self._expect(TokenKind.STRING).value
                     if sub.kind == TokenKind.DENSE:
@@ -368,6 +423,7 @@ class Parser:
             limit=limit,
             model=model,
             hybrid=hybrid,
+            fusion=fusion,
             sparse_only=sparse_only,
             sparse_model=sparse_model,
             query_filter=query_filter,
@@ -457,17 +513,7 @@ class Parser:
         if self._peek().kind == TokenKind.ID:
             self._advance()
             self._expect(TokenKind.EQUALS)
-            tok = self._peek()
-            if tok.kind == TokenKind.STRING:
-                self._advance()
-                point_id: str | int = tok.value
-            elif tok.kind == TokenKind.INTEGER:
-                self._advance()
-                point_id = int(tok.value)
-            else:
-                raise QQLSyntaxError(
-                    f"Expected string or integer for point id, got '{tok.value}'", tok.pos
-                )
+            point_id = self._parse_point_id_value("DELETE")
             return DeleteStmt(collection=collection, point_id=point_id)
 
         query_filter = self._parse_filter_expr()
@@ -694,6 +740,19 @@ class Parser:
         self._expect(TokenKind.RPAREN)
         return tuple(items)
 
+    def _parse_point_id_value(self, statement: str) -> str | int:
+        tok = self._peek()
+        if tok.kind == TokenKind.STRING:
+            self._advance()
+            return tok.value
+        if tok.kind == TokenKind.INTEGER:
+            self._advance()
+            return int(tok.value)
+        raise QQLSyntaxError(
+            f"{statement} requires a string or integer point id, got '{tok.value}'",
+            tok.pos,
+        )
+
     # ── Dict / value parsers (for INSERT VALUES) ──────────────────────────
 
     def _parse_identifier(self) -> str:

{qql_cli-2.1.0 → qql_cli-2.2.0}/src/qql/script.py

@@ -24,6 +24,8 @@ _STMT_STARTERS = {
     TokenKind.CREATE,
     TokenKind.DROP,
     TokenKind.SHOW,
+    TokenKind.SELECT,
+    TokenKind.SCROLL,
     TokenKind.SEARCH,
     TokenKind.RECOMMEND,
     TokenKind.DELETE,
@@ -54,7 +56,7 @@ def split_statements(tokens: list[Token]) -> list[list[Token]]:
     """Split a flat token list into per-statement chunks.
 
     A new chunk begins whenever a statement-starter keyword (INSERT, CREATE,
-    DROP, SHOW, SEARCH, RECOMMEND, DELETE) is encountered at
+    DROP, SHOW, SCROLL, SELECT, SEARCH, RECOMMEND, DELETE) is encountered at
     brace/bracket/paren depth 0.
     The EOF sentinel is consumed and never included in any chunk.
     """

{qql_cli-2.1.0 → qql_cli-2.2.0}/tests/test_executor.py

@@ -10,6 +10,8 @@ from qql.ast_nodes import (
     QuantizationConfig,
     QuantizationType,
     RecommendStmt,
+    SelectStmt,
+    ScrollStmt,
     SearchStmt,
     SearchWith,
     ShowCollectionsStmt,
@@ -357,6 +359,101 @@ class TestShow:
         assert "docs" in result.data
 
 
+class TestScroll:
+    def test_scroll_returns_points_and_next_offset(self, executor, mock_client, mocker):
+        mock_client.collection_exists.return_value = True
+        rec1 = mocker.MagicMock()
+        rec1.id = "a"
+        rec1.payload = {"text": "first"}
+        rec2 = mocker.MagicMock()
+        rec2.id = 2
+        rec2.payload = {"text": "second"}
+        mock_client.scroll.return_value = ([rec1, rec2], "next-1")
+
+        node = ScrollStmt(collection="notes", limit=2)
+        result = executor.execute(node)
+
+        mock_client.scroll.assert_called_once_with(
+            collection_name="notes",
+            scroll_filter=None,
+            limit=2,
+            offset=None,
+            with_payload=True,
+            with_vectors=False,
+        )
+        assert result.success is True
+        assert result.data == {
+            "points": [
+                {"id": "a", "payload": {"text": "first"}},
+                {"id": "2", "payload": {"text": "second"}},
+            ],
+            "next_offset": "next-1",
+        }
+
+    def test_scroll_with_after_and_filter(self, executor, mock_client, mocker):
+        from qql.ast_nodes import CompareExpr
+        from qdrant_client.models import Filter
+
+        mock_client.collection_exists.return_value = True
+        mock_client.scroll.return_value = ([], None)
+
+        node = ScrollStmt(
+            collection="notes",
+            limit=10,
+            after="cursor-id",
+            query_filter=CompareExpr(field="year", op=">=", value=2024),
+        )
+        executor.execute(node)
+
+        kwargs = mock_client.scroll.call_args.kwargs
+        assert kwargs["offset"] == "cursor-id"
+        assert isinstance(kwargs["scroll_filter"], Filter)
+
+    def test_scroll_nonexistent_collection_raises(self, executor, mock_client):
+        mock_client.collection_exists.return_value = False
+        node = ScrollStmt(collection="ghost", limit=5)
+        with pytest.raises(QQLRuntimeError, match="does not exist"):
+            executor.execute(node)
+
+
+class TestSelect:
+    def test_select_by_id_returns_payload(self, executor, mock_client, mocker):
+        mock_client.collection_exists.return_value = True
+        rec = mocker.MagicMock()
+        rec.id = "abc-123"
+        rec.payload = {"text": "hello", "year": 2024}
+        mock_client.retrieve.return_value = [rec]
+
+        node = SelectStmt(collection="notes", point_id="abc-123")
+        result = executor.execute(node)
+
+        mock_client.retrieve.assert_called_once_with(
+            collection_name="notes",
+            ids=["abc-123"],
+            with_payload=True,
+            with_vectors=False,
+        )
+        assert result.success is True
+        assert result.data == {"id": "abc-123", "payload": {"text": "hello", "year": 2024}}
+
+    def test_select_not_found(self, executor, mock_client):
+        mock_client.collection_exists.return_value = True
+        mock_client.retrieve.return_value = []
+
+        node = SelectStmt(collection="notes", point_id=7)
+        result = executor.execute(node)
+
+        assert result.success is True
+        assert "not found" in result.message
+        assert result.data is None
+
+    def test_select_nonexistent_collection_raises(self, executor, mock_client):
+        mock_client.collection_exists.return_value = False
+        node = SelectStmt(collection="ghost", point_id="x")
+        with pytest.raises(QQLRuntimeError, match="does not exist"):
+            executor.execute(node)
+
+
 class TestSearch:
     def test_search_calls_qdrant_query_points(self, executor, mock_client, mocker):
         mock_client.collection_exists.return_value = True
@@ -1063,6 +1160,29 @@ class TestHybridSearch:
         assert isinstance(kw["query"], FusionQuery)
         assert kw["query"].fusion == Fusion.RRF
 
+    def test_hybrid_search_uses_dbsf_fusion(
+        self, executor, mock_client, mock_sparse_embedder, mocker
+    ):
+        from qdrant_client.models import Fusion, FusionQuery
+
+        mock_client.collection_exists.return_value = True
+        mock_resp = mocker.MagicMock()
+        mock_resp.points = []
+        mock_client.query_points.return_value = mock_resp
+
+        node = SearchStmt(
+            collection="col",
+            query_text="q",
+            limit=5,
+            model=None,
+            hybrid=True,
+            fusion="dbsf",
+        )
+        executor.execute(node)
+        kw = mock_client.query_points.call_args.kwargs
+        assert isinstance(kw["query"], FusionQuery)
+        assert kw["query"].fusion == Fusion.DBSF
+
     def test_hybrid_search_prefetch_limit_is_4x(
         self, executor, mock_client, mock_sparse_embedder, mocker
     ):

{qql_cli-2.1.0 → qql_cli-2.2.0}/tests/test_lexer.py

@@ -39,6 +39,20 @@ class TestKeywords:
         assert ks[3] == TokenKind.TO
         assert ks[5] == TokenKind.LIMIT
 
+    def test_scroll_keywords(self):
+        ks = kinds("SCROLL FROM docs AFTER 'cursor-id' LIMIT 50")
+        assert ks[0] == TokenKind.SCROLL
+        assert ks[1] == TokenKind.FROM
+        assert TokenKind.AFTER in ks
+        assert TokenKind.LIMIT in ks
+
+    def test_select_keywords(self):
+        ks = kinds("SELECT * FROM notes WHERE id = 'abc'")
+        assert ks[0] == TokenKind.SELECT
+        assert ks[1] == TokenKind.STAR
+        assert ks[2] == TokenKind.FROM
+        assert ks[4] == TokenKind.WHERE
+
     def test_delete_keywords(self):
         ks = kinds("DELETE FROM foo WHERE id = 'abc'")
         assert ks[:4] == [TokenKind.DELETE, TokenKind.FROM, TokenKind.IDENTIFIER, TokenKind.WHERE]
@@ -89,6 +103,10 @@ class TestPunctuation:
         assert ks[0] == TokenKind.LBRACKET
         assert ks[-2] == TokenKind.RBRACKET
 
+    def test_star(self):
+        ks = kinds("*")
+        assert ks[0] == TokenKind.STAR
+
 
 class TestErrors:
     def test_unterminated_string(self):
@@ -212,6 +230,10 @@ class TestHybridKeyword:
         ks = kinds("sparse")
         assert ks[0] == TokenKind.SPARSE
 
+    def test_fusion_keyword(self):
+        ks = kinds("FUSION")
+        assert ks[0] == TokenKind.FUSION
+
     def test_hybrid_in_create_statement(self):
         ks = kinds("CREATE COLLECTION articles HYBRID")
         assert ks[3] == TokenKind.HYBRID

{qql_cli-2.1.0 → qql_cli-2.2.0}/tests/test_parser.py

@@ -24,6 +24,8 @@ from qql.ast_nodes import (
     QuantizationConfig,
     QuantizationType,
     RecommendStmt,
+    SelectStmt,
+    ScrollStmt,
     SearchStmt,
     SearchWith,
     ShowCollectionsStmt,
@@ -189,6 +191,51 @@ class TestShow:
         assert isinstance(node, ShowCollectionsStmt)
 
 
+class TestScroll:
+    def test_scroll_basic(self):
+        node = parse("SCROLL FROM docs LIMIT 50")
+        assert isinstance(node, ScrollStmt)
+        assert node.collection == "docs"
+        assert node.limit == 50
+        assert node.query_filter is None
+        assert node.after is None
+
+    def test_scroll_with_where(self):
+        node = parse("SCROLL FROM docs WHERE year >= 2024 LIMIT 50")
+        assert isinstance(node, ScrollStmt)
+        assert isinstance(node.query_filter, CompareExpr)
+        assert node.query_filter.field == "year"
+        assert node.after is None
+
+    def test_scroll_with_after(self):
+        node = parse("SCROLL FROM docs AFTER 'cursor-id' LIMIT 50")
+        assert isinstance(node, ScrollStmt)
+        assert node.after == "cursor-id"
+
+    def test_scroll_with_where_and_after(self):
+        node = parse("SCROLL FROM docs WHERE year >= 2024 AFTER 42 LIMIT 50")
+        assert isinstance(node, ScrollStmt)
+        assert node.after == 42
+        assert isinstance(node.query_filter, CompareExpr)
+
+
+class TestSelect:
+    def test_select_by_string_id(self):
+        node = parse("SELECT * FROM notes WHERE id = 'abc-123'")
+        assert isinstance(node, SelectStmt)
+        assert node.collection == "notes"
+        assert node.point_id == "abc-123"
+
+    def test_select_by_integer_id(self):
+        node = parse("SELECT * FROM notes WHERE id = 42")
+        assert isinstance(node, SelectStmt)
+        assert node.point_id == 42
+
+    def test_select_requires_id_filter(self):
+        with pytest.raises(QQLSyntaxError):
+            parse("SELECT * FROM notes WHERE year = 2024")
+
+
 class TestSearch:
     def test_basic_search(self):
         node = parse("SEARCH notes SIMILAR TO 'hello world' LIMIT 5")
@@ -334,7 +381,7 @@ class TestRecommend:
 class TestErrors:
     def test_unknown_keyword(self):
         with pytest.raises(QQLSyntaxError):
-            parse("SELECT * FROM foo")
+            parse("UPSERT INTO foo VALUES {'text': 'x'}")
 
     def test_missing_collection_name(self):
         with pytest.raises(QQLSyntaxError):
@@ -704,6 +751,24 @@ class TestHybridSearch:
         assert isinstance(node.query_filter, CompareExpr)
         assert node.query_filter.field == "year"
 
+    def test_search_hybrid_with_dbsf_fusion(self):
+        node = parse(
+            "SEARCH docs SIMILAR TO 'q' LIMIT 10 USING HYBRID FUSION 'dbsf'"
+        )
+        assert node.hybrid is True
+        assert node.fusion == "dbsf"
+
+    def test_search_hybrid_with_fusion_and_models(self):
+        node = parse(
+            "SEARCH docs SIMILAR TO 'q' LIMIT 10 "
+            "USING HYBRID FUSION 'rrf' SPARSE MODEL 'Qdrant/bm25' "
+            "DENSE MODEL 'BAAI/bge-base-en-v1.5'"
+        )
+        assert node.hybrid is True
+        assert node.fusion == "rrf"
+        assert node.sparse_model == "Qdrant/bm25"
+        assert node.model == "BAAI/bge-base-en-v1.5"
+
     def test_search_hybrid_dense_model_and_where(self):
         node = parse(
             "SEARCH articles SIMILAR TO 'ml' LIMIT 10 "
@@ -713,6 +778,10 @@ class TestHybridSearch:
         assert node.model == "BAAI/bge-small-en-v1.5"
         assert isinstance(node.query_filter, CompareExpr)
 
+    def test_search_hybrid_rejects_unknown_fusion(self):
+        with pytest.raises(QQLSyntaxError, match="Unsupported hybrid fusion"):
+            parse("SEARCH docs SIMILAR TO 'q' LIMIT 10 USING HYBRID FUSION 'x'")
+
     def test_search_hybrid_limit_preserved(self):
         node = parse("SEARCH col SIMILAR TO 'q' LIMIT 7 USING HYBRID")
         assert node.limit == 7

{qql_cli-2.1.0 → qql_cli-2.2.0}/tests/test_script.py

@@ -111,6 +111,30 @@ class TestSplitStatements:
         assert len(chunks) == 3
         assert chunks[1][0].kind == TokenKind.RECOMMEND
 
+    def test_scroll_starts_new_top_level_statement(self):
+        from qql.lexer import TokenKind
+
+        tokens = tokenize(
+            "SHOW COLLECTIONS\n"
+            "SCROLL FROM x LIMIT 10\n"
+            "DROP COLLECTION x"
+        )
+        chunks = split_statements(tokens)
+        assert len(chunks) == 3
+        assert chunks[1][0].kind == TokenKind.SCROLL
+
+    def test_select_starts_new_top_level_statement(self):
+        from qql.lexer import TokenKind
+
+        tokens = tokenize(
+            "SHOW COLLECTIONS\n"
+            "SELECT * FROM x WHERE id = 'id-1'\n"
+            "DROP COLLECTION x"
+        )
+        chunks = split_statements(tokens)
+        assert len(chunks) == 3
+        assert chunks[1][0].kind == TokenKind.SELECT
+
 
 # ── run_script ────────────────────────────────────────────────────────────────