Skip to content

Commit e159d6d

Browse files
authored
Added new streaming interface
1 parent 64d09ee commit e159d6d

File tree

1 file changed

+49
-0
lines changed

1 file changed

+49
-0
lines changed

API.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -262,3 +262,52 @@ FROM vector_quantize_scan('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.
262262
```
263263

264264
---
265+
266+
## 🔁 Streaming Interfaces
267+
268+
### `vector_full_scan_stream` and `vector_quantize_scan_stream`
269+
270+
**Returns:** `Virtual Table (rowid, distance)`
271+
272+
**Description:**
273+
These streaming interfaces provide the same functionality as `vector_full_scan` and `vector_quantize_scan`, respectively, but are designed for incremental or filtered processing of results.
274+
Unlike their non-streaming counterparts, these functions **omit the fourth parameter (`k`)** and allow you to use standard SQL clauses such as `WHERE` and `LIMIT` to control filtering and result count.
275+
276+
This makes them ideal for combining vector search with additional query conditions or progressive result consumption in streaming applications.
277+
278+
**Parameters:**
279+
280+
* `table` (TEXT): Name of the target table.
281+
* `column` (TEXT): Column containing vectors.
282+
* `vector` (BLOB or JSON): The query vector.
283+
284+
**Key Differences from Non-Streaming Variants:**
285+
286+
| Function | Equivalent To | Requires `k` | Supports `WHERE` | Supports `LIMIT` |
287+
| ----------------------------- | ---------------------- | ------------ | ---------------- | ---------------- |
288+
| `vector_full_scan_stream` | `vector_full_scan` ||||
289+
| `vector_quantize_scan_stream` | `vector_quantize_scan` ||||
290+
291+
**Examples:**
292+
293+
```sql
294+
-- Perform a filtered full scan
295+
SELECT rowid, distance
296+
FROM vector_full_scan_stream('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]'))
297+
WHERE category = 'science'
298+
LIMIT 5;
299+
```
300+
301+
```sql
302+
-- Perform a filtered approximate scan using quantized data
303+
SELECT rowid, distance
304+
FROM vector_quantize_scan_stream('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]'))
305+
WHERE score > 0.8
306+
LIMIT 10;
307+
```
308+
309+
**Usage Notes:**
310+
311+
* These interfaces return rows progressively and can efficiently combine vector similarity with SQL-level filters.
312+
* The `LIMIT` clause can be used to control how many rows are read or returned.
313+
* The query planner integrates the streaming virtual table into the overall SQL execution plan, enabling hybrid filtering and ranking operations.

0 commit comments

Comments
 (0)