Added clamping and unified stream/non-stream modules. Several other improvements and issues fixed.

Author: marcobambini

.gitignore

@@ -43,4 +43,5 @@ packages/node/test-platform-packages/
 
 # System
 .DS_Store
-Thumbs.db
+Thumbs.db
+CLAUDE.md

API.md

@@ -219,7 +219,7 @@ INSERT INTO compressed_vectors(embedding) VALUES(vector_as_u8(X'010203'));
 
 ---
 
-## 🔍 `vector_full_scan(table, column, vector, k)`
+## 🔍 `vector_full_scan(table, column, vector [, k])`
 
 **Returns:** `Virtual Table (rowid, distance)`
 
@@ -232,18 +232,38 @@ Since this interface only returns rowid and distance, if you need to access addi
 * `table` (TEXT): Name of the target table.
 * `column` (TEXT): Column containing vectors.
 * `vector` (BLOB or JSON): The query vector.
-* `k` (INTEGER): Number of nearest neighbors to return.
+* `k` (INTEGER, optional): Number of nearest neighbors to return. When provided, the module collects the top-k results sorted by distance. When omitted, the module operates in **streaming mode** — rows are returned progressively as they are scanned, enabling standard SQL clauses such as `WHERE` and `LIMIT` to control filtering and result count.
 
-**Example:**
+**Examples:**
 
 ```sql
+-- Top-k mode: return the 5 nearest neighbors, sorted by distance
 SELECT rowid, distance
 FROM vector_full_scan('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]'), 5);
 ```
 
+```sql
+-- Streaming mode: progressively scan all rows, apply SQL filters
+SELECT rowid, distance
+FROM vector_full_scan('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]'))
+LIMIT 5;
+```
+
+```sql
+-- Streaming mode with JOIN and filtering
+SELECT
+    v.rowid,
+    row_number() OVER (ORDER BY v.distance) AS rank_number,
+    v.distance
+FROM vector_full_scan('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]')) AS v
+    JOIN documents ON documents.rowid = v.rowid
+WHERE documents.category = 'science'
+LIMIT 10;
+```
+
 ---
 
-## ⚡ `vector_quantize_scan(table, column, vector, k)`
+## ⚡ `vector_quantize_scan(table, column, vector [, k])`
 
 **Returns:** `Virtual Table (rowid, distance)`
 
@@ -257,81 +277,31 @@ You **must run `vector_quantize()`** before using `vector_quantize_scan()` and w
 * `table` (TEXT): Name of the target table.
 * `column` (TEXT): Column containing vectors.
 * `vector` (BLOB or JSON): The query vector.
-* `k` (INTEGER): Number of nearest neighbors to return.
+* `k` (INTEGER, optional): Number of nearest neighbors to return. When provided, the module collects the top-k results sorted by distance. When omitted, the module operates in **streaming mode** — rows are returned progressively, enabling standard SQL clauses such as `WHERE` and `LIMIT`.
 
 **Performance Highlights:**
 
 * Handles **1M vectors** of dimension 768 in a few milliseconds.
 * Uses **<50MB** of RAM.
 * Achieves **>0.95 recall**.
 
-**Example:**
-
-```sql
-SELECT rowid, distance
-FROM vector_quantize_scan('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]'), 10);
-```
-
----
-
-## 🔁 Streaming Interfaces
-
-### `vector_full_scan_stream` and `vector_quantize_scan_stream`
-
-**Returns:** `Virtual Table (rowid, distance)`
-
-**Description:**
-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.
-
-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. Since this interface only returns rowid and distance, if you need to access additional columns from the original table, you must use a SELF JOIN.
-
-This makes them ideal for combining vector search with additional query conditions or progressive result consumption in streaming applications.
-
-**Parameters:**
-
-* `table` (TEXT): Name of the target table.
-* `column` (TEXT): Column containing vectors.
-* `vector` (BLOB or JSON): The query vector.
-
-**Key Differences from Non-Streaming Variants:**
-
-| Function                      | Equivalent To          | Requires `k` | Supports `WHERE` | Supports `LIMIT` |
-| ----------------------------- | ---------------------- | ------------ | ---------------- | ---------------- |
-| `vector_full_scan_stream`     | `vector_full_scan`     | ❌            | ✅                | ✅                |
-| `vector_quantize_scan_stream` | `vector_quantize_scan` | ❌            | ✅                | ✅                |
-
 **Examples:**
 
 ```sql
--- Perform a filtered full scan
+-- Top-k mode: return the 10 nearest neighbors, sorted by distance
 SELECT rowid, distance
-FROM vector_full_scan_stream('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]'))
-LIMIT 5;
+FROM vector_quantize_scan('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]'), 10);
 ```
 
 ```sql
--- Perform a filtered approximate scan using quantized data
+-- Streaming mode: progressively scan using quantized data
 SELECT rowid, distance
-FROM vector_quantize_scan_stream('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]'))
-LIMIT 10;
-```
-
-**Accessing Additional Columns:**
-
-```sql
--- Perform a filtered full scan with additional columns
-SELECT
-    v.rowid,
-    row_number() OVER (ORDER BY v.distance) AS rank_number,
-    v.distance
-FROM vector_full_scan_stream('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]')) AS v
-    JOIN documents ON documents.rowid = v.rowid
-WHERE documents.category = 'science'
+FROM vector_quantize_scan('documents', 'embedding', vector_as_f32('[0.1, 0.2, 0.3]'))
 LIMIT 10;
 ```
 
 **Usage Notes:**
 
-* These interfaces return rows progressively and can efficiently combine vector similarity with SQL-level filters.
-* The `LIMIT` clause can be used to control how many rows are read or returned.
-* The query planner integrates the streaming virtual table into the overall SQL execution plan, enabling hybrid filtering and ranking operations.
+* In **top-k mode** (with `k`), results are sorted by distance. The query planner knows the output is pre-sorted, so no additional `ORDER BY` is needed.
+* In **streaming mode** (without `k`), rows are returned in scan order. Use `ORDER BY distance` and `LIMIT` as needed.
+* Streaming mode is ideal for combining vector similarity with additional SQL-level filters or progressive result consumption.

README.md

@@ -74,7 +74,7 @@ INSERT INTO images (embedding, label) VALUES (vector_as_f32('[0.3, 1.0, 0.9, 3.2
 
 -- Initialize the vector. By default, the distance function is L2.
 -- To use a different metric, specify one of the following options:
--- distance=L1, distance=COSINE, distance=DOT, or distance=SQUARED_L2.
+-- distance=L1, distance=COSINE, distance=DOT, distance=SQUARED_L2, or distance=HAMMING.
 SELECT vector_init('images', 'embedding', 'type=FLOAT32,dimension=384');
 
 -- Quantize vector
@@ -87,6 +87,13 @@ SELECT vector_quantize_preload('images', 'embedding');
 SELECT e.id, v.distance FROM images AS e
    JOIN vector_quantize_scan('images', 'embedding', ?, 20) AS v
    ON e.id = v.rowid;
+
+-- Streaming mode: omit k to get rows progressively, use SQL to filter and limit
+SELECT e.id, v.distance FROM images AS e
+   JOIN vector_quantize_scan('images', 'embedding', ?) AS v
+   ON e.id = v.rowid
+   WHERE e.label = 'cat'
+   LIMIT 10;
 ```
 
 ### Swift Package
@@ -117,7 +124,7 @@ sqlite3_close(db)
 Add the [following](https://central.sonatype.com/artifact/ai.sqlite/vector) to your Gradle dependencies:
 
 ```gradle
-implementation 'ai.sqlite:vector:0.9.34'
+implementation 'ai.sqlite:vector:0.9.80'
 ```
 
 Here's an example of how to use the package:

src/distance-avx2.c

@@ -14,7 +14,7 @@
 #include <math.h>
 
 extern distance_function_t dispatch_distance_table[VECTOR_DISTANCE_MAX][VECTOR_TYPE_MAX];
-extern char *distance_backend_name;
+extern const char *distance_backend_name;
 
 #define _mm256_abs_ps(x) _mm256_andnot_ps(_mm256_set1_ps(-0.0f), (x))
 
@@ -158,6 +158,8 @@ float float32_distance_cosine_avx2 (const void *a, const void *b, int n) {
     if (norm_a == 0.0f || norm_b == 0.0f) return 1.0f;
 
     float cosine_similarity = dot / (norm_a * norm_b);
+    if (cosine_similarity > 1.0f) cosine_similarity = 1.0f;
+    if (cosine_similarity < -1.0f) cosine_similarity = -1.0f;
     return 1.0f - cosine_similarity;
 }
 
@@ -749,6 +751,8 @@ float uint8_distance_cosine_avx2 (const void *a, const void *b, int n) {
     if (norm_a == 0.0f || norm_b == 0.0f) return 1.0f;
 
     float cosine_similarity = dot / (norm_a * norm_b);
+    if (cosine_similarity > 1.0f) cosine_similarity = 1.0f;
+    if (cosine_similarity < -1.0f) cosine_similarity = -1.0f;
     return 1.0f - cosine_similarity;
 }
 
@@ -946,6 +950,8 @@ float int8_distance_cosine_avx2 (const void *a, const void *b, int n) {
     if (norm_a == 0.0f || norm_b == 0.0f) return 1.0f;
 
     float cosine_similarity = dot / (norm_a * norm_b);
+    if (cosine_similarity > 1.0f) cosine_similarity = 1.0f;
+    if (cosine_similarity < -1.0f) cosine_similarity = -1.0f;
     return 1.0f - cosine_similarity;
 }
 

src/distance-avx512.c

@@ -15,7 +15,7 @@
 #include <math.h>
 
 extern distance_function_t dispatch_distance_table[VECTOR_DISTANCE_MAX][VECTOR_TYPE_MAX];
-extern char* distance_backend_name;
+extern const char *distance_backend_name;
 
 // Abs for f32 (AVX512F has native abs)
 #define _mm512_abs_ps(x) _mm512_abs_ps(x)
@@ -159,6 +159,8 @@ float float32_distance_cosine_avx512(const void* a, const void* b, int n) {
     if (norm_a == 0.0f || norm_b == 0.0f) return 1.0f;
 
     float cosine_similarity = dot / (norm_a * norm_b);
+    if (cosine_similarity > 1.0f) cosine_similarity = 1.0f;
+    if (cosine_similarity < -1.0f) cosine_similarity = -1.0f;
     return 1.0f - cosine_similarity;
 }
 
@@ -712,6 +714,8 @@ float uint8_distance_cosine_avx512(const void* a, const void* b, int n) {
     if (norm_a == 0.0f || norm_b == 0.0f) return 1.0f;
 
     float cosine_similarity = dot / (norm_a * norm_b);
+    if (cosine_similarity > 1.0f) cosine_similarity = 1.0f;
+    if (cosine_similarity < -1.0f) cosine_similarity = -1.0f;
     return 1.0f - cosine_similarity;
 }
 
@@ -843,6 +847,8 @@ float int8_distance_cosine_avx512(const void* a, const void* b, int n) {
     if (norm_a == 0.0f || norm_b == 0.0f) return 1.0f;
 
     float cosine_similarity = dot / (norm_a * norm_b);
+    if (cosine_similarity > 1.0f) cosine_similarity = 1.0f;
+    if (cosine_similarity < -1.0f) cosine_similarity = -1.0f;
     return 1.0f - cosine_similarity;
 }
 

src/distance-cpu.c

@@ -18,7 +18,7 @@
 #include "distance-avx2.h"
 #include "distance-avx512.h"
 
-char *distance_backend_name = "CPU";
+const char *distance_backend_name = "CPU";
 distance_function_t dispatch_distance_table[VECTOR_DISTANCE_MAX][VECTOR_TYPE_MAX] = {0};
 
 #define LASSQ_UPDATE(ad_) do {                            \
@@ -106,8 +106,11 @@ float float32_distance_cosine_cpu (const void *v1, const void *v2, int n) {
     if (norm_x == 0.0f || norm_y == 0.0f) {
         return 1.0f;
     }
-    
-    return 1.0f - (dot / (sqrtf(norm_x) * sqrtf(norm_y)));
+
+    float cosine_similarity = dot / (sqrtf(norm_x) * sqrtf(norm_y));
+    if (cosine_similarity > 1.0f) cosine_similarity = 1.0f;
+    if (cosine_similarity < -1.0f) cosine_similarity = -1.0f;
+    return 1.0f - cosine_similarity;
 }
 
 float float32_distance_dot_cpu (const void *v1, const void *v2, int n) {
@@ -250,7 +253,10 @@ float bfloat16_distance_cosine_cpu(const void *v1, const void *v2, int n) {
         return 1.0f;
     }
 
-    return 1.0f - (dot / (sqrtf(norm_x) * sqrtf(norm_y)));
+    float cosine_similarity = dot / (sqrtf(norm_x) * sqrtf(norm_y));
+    if (cosine_similarity > 1.0f) cosine_similarity = 1.0f;
+    if (cosine_similarity < -1.0f) cosine_similarity = -1.0f;
+    return 1.0f - cosine_similarity;
 }
 
 float bfloat16_distance_dot_cpu (const void *v1, const void *v2, int n) {
@@ -536,6 +542,8 @@ float uint8_distance_cosine_cpu (const void *v1, const void *v2, int n) {
     }
 
     float cosine_similarity = dot / (sqrtf((float)norm_a2) * sqrtf((float)norm_b2));
+    if (cosine_similarity > 1.0f) cosine_similarity = 1.0f;
+    if (cosine_similarity < -1.0f) cosine_similarity = -1.0f;
     return 1.0f - cosine_similarity;
 }
 
@@ -648,6 +656,8 @@ float int8_distance_cosine_cpu (const void *v1, const void *v2, int n) {
     }
 
     float cosine_similarity = dot / (sqrtf((float)norm_a2) * sqrtf((float)norm_b2));
+    if (cosine_similarity > 1.0f) cosine_similarity = 1.0f;
+    if (cosine_similarity < -1.0f) cosine_similarity = -1.0f;
     return 1.0f - cosine_similarity;
 }
 
@@ -716,8 +726,9 @@ float bit1_distance_hamming_cpu (const void *v1, const void *v2, int n) {
 
     // process 8 bytes at a time
     for (; i + 8 <= n; i += 8) {
-        uint64_t xa = *(const uint64_t *)(a + i);
-        uint64_t xb = *(const uint64_t *)(b + i);
+        uint64_t xa, xb;
+        memcpy(&xa, a + i, sizeof(uint64_t));
+        memcpy(&xb, b + i, sizeof(uint64_t));
         distance += popcount64(xa ^ xb);
     }