docs: add use-cases section and clarify SQL reference pages

Add seven industry-specific use-case pages (AI/LLM, fintech, healthcare,
geospatial, gaming, IoT/edge, e-commerce) covering how each engine
combination maps to real product requirements.

Expand the time_bucket interval description in the functions reference to
cover Postgres-style long-form strings and bare-integer milliseconds.

Clarify the multi-vector-column section in the vector search reference:
rename "Multi-Vector" to "Multiple vector columns per collection", show
the correct column-name syntax for CREATE VECTOR INDEX and ORDER BY, and
document the default-field fallback for single-embedding collections.

Author: farhan-syah

docs/sql/functions.rdx

@@ -24,7 +24,7 @@ description: Built-in scalar, aggregate, and engine-specific SQL functions.
 | `DATE_FORMAT(ts, fmt)`          | Format timestamp as string             |
 | `time_bucket(interval, ts)`     | Truncate to interval boundary          |
 
-`time_bucket` accepts: `'1s'`, `'5m'`, `'15m'`, `'1h'`, `'6h'`, `'1d'`, `'1w'`, or ISO 8601 (`'PT5M'`, `'P1D'`).
+`time_bucket` accepts the interval as a string in any of these forms: short (`'1s'`, `'5m'`, `'15m'`, `'1h'`, `'6h'`, `'1d'`, `'1w'`), long / Postgres-style (`'30 seconds'`, `'5 minutes'`, `'1 hour'`, `'2 hours 30 minutes'`, optionally with an `INTERVAL` prefix), ISO 8601 (`'PT5M'`, `'P1D'`), or a bare integer (milliseconds).
 
 ## Type Functions
 

docs/sql/vector-search.rdx

@@ -150,11 +150,22 @@ LIMIT 10;
 
 Reciprocal Rank Fusion merges BM25 text results with vector similarity in a single pass.
 
-## Multi-Vector
+## Multiple vector columns per collection
 
-Collections can have multiple vector indexes on different embedding columns:
+A collection can carry several vector indexes, one per embedding column — name
+the column in parentheses after the collection. Each index gets its own metric
+and parameters; queries pick the column they search:
 
 ```sql
-CREATE VECTOR INDEX idx_text ON products METRIC cosine DIM 384;
-CREATE VECTOR INDEX idx_image ON products METRIC cosine DIM 512;
+CREATE VECTOR INDEX idx_text  ON products (text_embedding)  METRIC cosine DIM 384;
+CREATE VECTOR INDEX idx_image  ON products (image_embedding) METRIC cosine DIM 512;
+
+-- Search the text-embedding index:
+SELECT id FROM products ORDER BY text_embedding  <=> $text_vec  LIMIT 10;
+-- ...or the image-embedding index:
+SELECT id FROM products ORDER BY image_embedding <-> $image_vec LIMIT 10;
 ```
+
+Omitting `(<column>)` targets the collection's default (unnamed) vector field —
+fine when there's only one embedding column (as in the `CREATE VECTOR INDEX
+idx_embed ON articles ...` examples above).

use-cases/ai-llm.rdx

@@ -0,0 +1,134 @@
+---
+title: AI & LLM Applications
+description: Build RAG pipelines, agent memory stores, and hybrid semantic search on NodeDB — vector, graph, full-text, and document engines in one query.
+---
+
+Modern AI applications need at least three databases to function: a vector store for embeddings, a graph database for entity relationships, and a search index for keyword recall. NodeDB collapses all three into one, with a fourth engine — schemaless Document — for storing raw LLM outputs and conversation history.
+
+## Engines used
+
+| Engine | Role |
+|---|---|
+| **Vector** | HNSW similarity search, filtered ANN, multivec MaxSim |
+| **Full-Text Search** | BM25 keyword recall, 27-language analyzers |
+| **Graph** | Entity relationships, GraphRAG context expansion |
+| **Document (schemaless)** | Conversation history, LLM outputs, agent state |
+
+## Hybrid RAG retrieval
+
+A basic RAG retrieval combines vector similarity with BM25 keyword recall, then fuses the two ranked lists with Reciprocal Rank Fusion. `rrf_score(...)` does the fusion inside the planner — one statement, no application-side merge loop.
+
+```sql
+-- Hybrid search: vector ANN + BM25, fused with RRF
+SELECT
+  id,
+  content,
+  metadata,
+  rrf_score(
+    vector_distance(embedding, $query_vec),
+    bm25_score(content, $query_text)
+  ) AS score
+FROM documents
+WHERE metadata ->> 'source' = 'internal'
+ORDER BY score DESC
+LIMIT 10;
+```
+
+## GraphRAG: expand context through entity relationships
+
+Entities and their relationships are graph edges layered on the same `documents` collection — graph is an overlay, not a separate store. After vector search finds seed chunks, the fusion DSL walks those edges and merges the rankings:
+
+```sql
+-- Wire entities as edges on the documents collection
+GRAPH INSERT EDGE IN 'documents' FROM $chunk_id  TO $entity_id TYPE 'mentions';
+GRAPH INSERT EDGE IN 'documents' FROM $entity_a  TO $entity_b  TYPE 'related_to' PROPERTIES { weight: 0.8 };
+
+-- Vector search seeds → BFS along 'related_to' → RRF merge of vector rank + hop distance
+GRAPH RAG FUSION ON documents
+  QUERY $query_vec
+  VECTOR_FIELD 'embedding'
+  VECTOR_TOP_K 50
+  EXPANSION_DEPTH 2
+  EDGE_LABEL 'related_to'
+  FINAL_TOP_K 10
+  RRF_K (60.0, 35.0);
+```
+
+Need keyword relevance in the same pass? Add the `BM25` leg and the `RRF_K` tuple becomes a triple — vector, graph expansion, and BM25 all fused in one plan:
+
+```sql
+GRAPH RAG FUSION ON documents
+  QUERY $query_vec VECTOR_FIELD 'embedding' VECTOR_TOP_K 50
+  BM25 $query_text ON 'content'
+  EXPANSION_DEPTH 2 EDGE_LABEL 'related_to' FINAL_TOP_K 10
+  RRF_K (60.0, 35.0, 50.0);
+```
+
+You can also walk the entity graph directly with a Cypher-subset `MATCH`:
+
+```sql
+MATCH (c:Chunk)-[:mentions]->(e:Entity)-[:related_to*1..2]->(related:Entity)
+WHERE c.id = $chunk_id
+RETURN DISTINCT related.id
+LIMIT 20;
+```
+
+## Agent memory store
+
+Long-running agents need persistent, queryable memory. A schemaless Document collection stores arbitrary turn payloads; a vector index makes semantic recall fast.
+
+```sql
+CREATE COLLECTION agent_memory;
+CREATE VECTOR INDEX idx_mem ON agent_memory METRIC cosine DIM 1536;
+
+-- Store a turn (object-literal insert on a schemaless collection)
+INSERT INTO agent_memory
+  { session_id: $sid, turn: $n, role: $role, content: $text, embedding: $vec, created_at: now() };
+
+-- Recall: recent turns from this session + semantically similar turns from any session
+(SELECT content, role, created_at
+ FROM agent_memory
+ WHERE session_id = $sid
+ ORDER BY turn DESC
+ LIMIT 10)
+UNION ALL
+(SELECT content, role, created_at
+ FROM agent_memory
+ WHERE session_id <> $sid
+ ORDER BY embedding <=> $query_vec
+ LIMIT 5)
+ORDER BY created_at;
+```
+
+## Filtered vector search
+
+Production vector workloads almost always filter by metadata before ranking. NodeDB's NaviX adaptive-local traversal keeps ANN recall high even with tight filters — the planner builds a roaring bitmap of matching IDs and picks pre-filter, post-filter, or brute-force based on selectivity.
+
+```sql
+-- Similar products, restricted to in-stock items in the user's region
+SELECT id, name, price, embedding <=> $query_vec AS distance
+FROM products
+WHERE in_stock = true
+  AND region = $region
+  AND category_id = ANY($category_ids)
+ORDER BY embedding <=> $query_vec
+LIMIT 20;
+```
+
+<Callout kind="tip" title="Matryoshka adaptive dimensions">
+Store full-precision embeddings and rank on the first N dimensions for a fast first pass via the `query_dim` tuning argument — then re-rank the top candidates at full precision. No reindexing:
+
+```sql
+SELECT id, vector_distance(embedding, $query_vec, query_dim => 256) AS distance
+FROM products
+WHERE in_stock = true
+ORDER BY distance
+LIMIT 100;
+```
+</Callout>
+
+## Why not a dedicated vector database?
+
+Dedicated vector databases force you to maintain a separate store for every non-vector data shape. When your RAG pipeline needs keyword fallback, entity relationships, and conversation history, you end up with four systems, four consistency boundaries, and cross-system joins that travel over the network.
+
+NodeDB keeps everything in one process with a single shared snapshot. A hybrid search + graph expansion + memory recall query is one SQL statement with zero inter-process calls.

use-cases/ecommerce-search.rdx

@@ -0,0 +1,177 @@
+---
+title: E-commerce & Search
+description: Hybrid BM25 + vector product search, RRF fusion ranking, recommendation graphs, and real-time inventory analytics — without Elasticsearch, a vector database, or a separate OLAP cluster.
+---
+
+E-commerce search stacks are notoriously complex: Elasticsearch for keyword search, a vector database for semantic similarity, a recommendation engine backed by a graph database, and a data warehouse for sales analytics. NodeDB provides all four as peer engines (plus Graph and FTS overlays) sharing one storage core, one query planner, and one operational surface.
+
+## Engines used
+
+| Engine | Role |
+|---|---|
+| **Full-Text Search** | BM25 keyword search, faceted filtering, autocomplete |
+| **Vector** | Semantic product search, visual similarity, embedding-based recommendations |
+| **Graph** | "Customers also bought", category navigation, brand-product relationships |
+| **Document (schemaless)** | Product catalog, flexible attributes, variant metadata |
+| **Columnar** | Sales analytics, inventory reporting, cohort analysis |
+
+## Hybrid product search
+
+The strongest e-commerce search combines keyword precision with semantic recall, then fuses the ranked lists. `rrf_score(...)` does the fusion in the planner — no application-side merge, no Elasticsearch + Pinecone glue code.
+
+```sql
+CREATE COLLECTION products;
+CREATE SEARCH INDEX ON products FIELDS title, description ANALYZER 'english' FUZZY true;
+-- One vector index per embedding column on the same collection.
+CREATE VECTOR INDEX idx_text  ON products (text_embedding)  METRIC cosine DIM 384;
+CREATE VECTOR INDEX idx_image ON products (image_embedding) METRIC cosine DIM 512;
+
+-- Hybrid search: BM25 keyword + vector semantic, fused with RRF
+SELECT
+  id,
+  title,
+  price,
+  brand,
+  rrf_score(
+    vector_distance(text_embedding, $query_vec),
+    bm25_score(description, $query_text)
+  ) AS relevance
+FROM products
+WHERE in_stock     = true
+  AND price        BETWEEN $min_price AND $max_price
+  AND category_id  = ANY($category_ids)
+ORDER BY relevance DESC
+LIMIT 20;
+```
+
+## Autocomplete and faceted filtering
+
+```sql
+-- Autocomplete: fuzzy title match, ranked by popularity
+SELECT DISTINCT id, title
+FROM products
+WHERE text_match(title, $prefix, { fuzzy: true, distance: 1 })
+ORDER BY popularity_score DESC
+LIMIT 8;
+
+-- Facet counts: products per brand in the current keyword result set
+SELECT brand, count(*) AS count
+FROM products
+WHERE text_match(description, $query_text)
+  AND in_stock = true
+GROUP BY brand
+ORDER BY count DESC
+LIMIT 15;
+```
+
+## Visual similarity search
+
+For fashion, furniture, and home goods, image-embedding similarity lets shoppers find products that look alike — searching the `image_embedding` index created above, right alongside the catalog row:
+
+```sql
+-- "Shop similar items" — products whose image embedding is closest to the
+-- viewed one, restricted to the same in-stock category.
+SELECT id, title, price, image_url,
+       image_embedding <=> $viewed_vec AS visual_distance
+FROM products
+WHERE category_id = $category_id
+  AND in_stock = true
+  AND id <> $viewed_product_id
+ORDER BY image_embedding <=> $viewed_vec
+LIMIT 12;
+```
+
+## Recommendation graph — "Customers also bought"
+
+Co-purchase relationships are graph edges layered on the `products` collection — graph is an overlay, you don't create a separate "graph collection." Traversal-based recommendations run alongside the catalog.
+
+```sql
+-- A batch job recomputes co-purchase counts and (re)writes the edge with the
+-- current weight — DELETE then INSERT, since GRAPH INSERT EDGE is insert-only.
+GRAPH DELETE EDGE IN 'products' FROM $product_a TO $product_b TYPE 'co_purchased';
+GRAPH INSERT EDGE IN 'products' FROM $product_a TO $product_b TYPE 'co_purchased'
+  PROPERTIES { weight: $copurchase_count };
+
+-- "Customers also bought": direct co-purchase neighbours of a product,
+-- ranked by co-purchase weight. Graph nodes are document rows, so their
+-- catalog fields are available in RETURN.
+MATCH (seed:Product)-[e:co_purchased]->(rec:Product)
+WHERE seed.id = $product_id
+  AND rec.in_stock = true
+RETURN rec.id, rec.title, rec.price, e.weight AS affinity
+ORDER BY e.weight DESC
+LIMIT 8;
+```
+
+## Real-time inventory — LIVE SELECT
+
+Push in-stock / out-of-stock transitions to product pages without polling. `LIVE SELECT` registers a query and streams matching changes over pgwire, WebSocket, or the native protocol.
+
+```sql
+-- A shopper viewing their wishlist subscribes to back-in-stock events
+LIVE SELECT id, title FROM products
+WHERE id = ANY($wishlist_ids)
+  AND in_stock = true;
+
+-- When a back-ordered item is restocked, every subscriber gets the row
+-- delivered immediately. Cancel with: CANCEL LIVE SELECT <subscription_id>;
+```
+
+## Sales analytics — Columnar engine
+
+The Columnar engine handles aggregation-heavy analytics across millions of orders without a separate data warehouse — per-column compression, block statistics, and predicate pushdown.
+
+```sql
+CREATE COLLECTION orders (
+  id          TEXT PRIMARY KEY,
+  placed_at   TIMESTAMP TIME_KEY,
+  status      TEXT
+) WITH (engine='columnar');
+
+-- Revenue by category, last 30 days
+SELECT
+  c.name                       AS category,
+  count(DISTINCT o.id)         AS orders,
+  sum(oi.quantity * oi.price)  AS revenue,
+  avg(oi.quantity * oi.price)  AS avg_order_value
+FROM orders o
+JOIN order_items oi  ON oi.order_id    = o.id
+JOIN products    p   ON p.id           = oi.product_id
+JOIN categories  c   ON c.id           = p.category_id
+WHERE o.placed_at >= now() - INTERVAL '30 days'
+  AND o.status    = 'completed'
+GROUP BY c.name
+ORDER BY revenue DESC;
+
+-- Conversion funnel: views → add-to-cart → purchase
+SELECT
+  time_bucket('1d', e.ts) AS day,
+  count(CASE WHEN e.event = 'product_view' THEN 1 END) AS views,
+  count(CASE WHEN e.event = 'add_to_cart'  THEN 1 END) AS add_to_cart,
+  count(CASE WHEN e.event = 'purchase'     THEN 1 END) AS purchases,
+  round(
+    count(CASE WHEN e.event = 'purchase' THEN 1 END)::numeric
+    / nullif(count(CASE WHEN e.event = 'product_view' THEN 1 END), 0) * 100,
+    2
+  ) AS conversion_pct
+FROM events e
+WHERE e.ts >= now() - INTERVAL '14 days'
+GROUP BY day
+ORDER BY day;
+```
+
+<Callout kind="tip" title="Matryoshka embeddings for tiered search">
+Store full-precision embeddings and rank the first N dimensions for a fast first pass via the `query_dim` tuning argument, then re-rank the top candidates at full precision — no reindexing:
+
+```sql
+SELECT id, title, vector_distance(text_embedding, $query_vec, query_dim => 256) AS distance
+FROM products
+WHERE in_stock = true
+ORDER BY distance
+LIMIT 100;
+```
+</Callout>
+
+## Why not Elasticsearch + a vector database?
+
+Elasticsearch handles keyword search but requires a separate vector database for semantic recall, a graph database for recommendations, and a data warehouse for analytics. Synchronising product-catalog changes across four systems is the dominant operational burden. NodeDB keeps every engine in the same process: a hybrid search + recommendation + inventory check is one SQL statement, not four API calls.