@kedem/okdb 1.2.0 → 1.4.0

package/docs/http-api.md

@@ -349,6 +349,8 @@ POST   /api/:env/type/:type/query        → query records
 POST   /api/:env/transaction             → atomic batch writes
 ```
 
+**Hybrid search:** The `options` body field now accepts `fts` and `vector` sub-objects alongside `index`. See the querying guide for full documentation. When `fts` or `vector` is provided, the route automatically awaits the async result.
+
 ```bash
 # Get a record
 curl http://localhost:8080/api/default/type/users/item/alice \

package/docs/querying.md

@@ -192,6 +192,116 @@ const open = okdb.countByIndex('orders', ['status', 'createdAt'], {
 
 ---
 
+## Hybrid queries
+
+`query()` accepts `fts` and `vector` options to combine full-text search, semantic similarity, and index constraints in a single call. All signals compose — the result is a unified ranked list with sift post-filtering applied last.
+
+### FTS signal
+
+```javascript
+// Full-text search — returns results ordered by relevance score
+const results = await okdb.query(
+    'articles',
+    {},
+    {
+        fts: { name: 'articles_fts', query: 'database indexing' },
+        limit: 20,
+    },
+);
+// Each result has: { key, value, ftsScore, numTerms, maxScore }
+```
+
+### FTS + index constraint
+
+The index acts as a **hard constraint** — only documents present in the index range are returned. It does not affect ranking.
+
+```javascript
+// FTS results, but only from published articles
+const results = await okdb.query(
+    'articles',
+    {},
+    {
+        fts: { name: 'articles_fts', query: 'database indexing' },
+        index: { fields: ['status'], prefix: ['published'] },
+        limit: 20,
+    },
+);
+```
+
+### FTS + sift post-filter
+
+Sift filter is always applied last, after FTS and index narrowing:
+
+```javascript
+const results = await okdb.query(
+    'articles',
+    { category: 'tech' },
+    {
+        fts: { name: 'articles_fts', query: 'indexing' },
+        limit: 20,
+    },
+);
+```
+
+### FTS + vector (hybrid semantic + keyword)
+
+When both `fts` and `vector` are provided, candidates from each signal are combined and re-ranked using **Reciprocal Rank Fusion (RRF)**. RRF works across incomparable score scales — no normalization needed.
+
+```javascript
+const results = await okdb.query(
+    'articles',
+    {},
+    {
+        fts: { name: 'articles_fts', query: 'database' },
+        vector: { engine: 'articles_vec', query: 'fast persistent storage', limit: 50 },
+        limit: 20,
+    },
+);
+// Each result has: { key, value, score (RRF), ftsScore?, vectorScore? }
+```
+
+### Signal semantics
+
+| Signal   | Ordering         | Can enumerate all matches | Notes                                 |
+| -------- | ---------------- | ------------------------- | ------------------------------------- |
+| `index`  | Field value      | Yes                       | Hard constraint only — never reorders |
+| `fts`    | Relevance score  | Yes                       | Posting list intersection             |
+| `vector` | Similarity score | No — K-bounded            | ANN search, approximate               |
+
+**Important:** `query()` returns a **Promise** when `fts` or `vector` is present (vector search requires async embedding inference). Without these options, `query()` remains synchronous.
+
+### FTS options
+
+| Option   | Type            | Default              | Description                                   |
+| -------- | --------------- | -------------------- | --------------------------------------------- |
+| `name`   | string          | required             | Registered FTS index name                     |
+| `query`  | string          | `''`                 | Text to search                                |
+| `mode`   | `'and'`\|`'or'` | `'and'`              | AND: all terms required. OR: any term matches |
+| `prefix` | boolean         | false                | Enable prefix matching on last token          |
+| `limit`  | number          | `max(limit×10, 200)` | FTS candidate pool size                       |
+
+### Vector options
+
+| Option   | Type   | Default             | Description               |
+| -------- | ------ | ------------------- | ------------------------- |
+| `engine` | string | required            | Vector search engine name |
+| `query`  | string | required            | Semantic query text       |
+| `limit`  | number | `max(limit×4, 100)` | ANN candidate pool size   |
+
+### Nested index form
+
+The `index` option accepts a nested object for clarity:
+
+```javascript
+// Nested form (preferred for hybrid queries)
+{ index: { fields: ['status'], prefix: ['active'] } }
+
+// Flat form (still works — backward compatible)
+{ index: ['status'], prefix: ['active'] }
+```
+
+---
+
 ## Geo query
 
 OKDB has a built-in geospatial index based on geohash. Register a geo index on a field that stores `{ lat, lon }` (or an `[lat, lon]` array):