Baradb/docs/en/crossmodal.md

Cross-Modal Queries

BaraDB's unique capability is executing queries that span multiple storage engines in a single unified BaraQL statement.

Overview

Traditional databases require separate queries and application-level joins when working with different data models. BaraDB's cross-modal query planner optimizes execution across:

• Document/KV (LSM-Tree) — structured records
• Graph (Adjacency List) — relationships
• Vector (HNSW/IVF-PQ) — similarity search
• Full-Text (Inverted Index) — text search
• Columnar — analytical aggregates

Query Patterns

Vector + Full-Text (Semantic + Keyword Search)

Find documents that are semantically similar to a query vector AND contain specific keywords:

SELECT title, score
FROM articles
WHERE MATCH(body) AGAINST('machine learning')
ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, ...])
LIMIT 10;

Execution plan:

1. FTS engine filters articles matching "machine learning"
2. Vector engine ranks filtered results by embedding similarity
3. Top-K results returned

Graph + Vector (Social Recommendations)

Find friends of a user with similar taste vectors:

MATCH (u:User)-[:KNOWS]->(friend:User)
WHERE u.name = 'Alice'
ORDER BY cosine_distance(friend.taste_vector, u.taste_vector)
RETURN friend.name, friend.age;

Execution plan:

1. Graph engine traverses "KNOWS" edges from Alice
2. Vector engine computes similarity for each friend
3. Results sorted and projected

Document + Graph (Entity Enrichment)

Get order details with customer relationship graph:

SELECT o.id, o.total, c.name,
       (SELECT count(*) FROM orders WHERE customer_id = c.id) as order_count
FROM orders o
JOIN customers c ON o.customer_id = c.id
WHERE c.id IN (
  SELECT node_id FROM graph
  WHERE MATCH pattern (c:Customer)-[:REFERRED]->(:Customer)
);

Full-Text + Aggregate (Content Analytics)

Analyze which departments write most about a topic:

SELECT department, count(*) as article_count,
       avg(length(content)) as avg_length
FROM docs
WHERE MATCH(content) AGAINST('Nim programming')
GROUP BY department
ORDER BY article_count DESC;

Vector + Aggregate (Cluster Analysis)

Group similar vectors and analyze each cluster:

SELECT cluster_id, count(*) as size,
       centroid(embedding) as center,
       avg(created_at) as avg_date
FROM products
GROUP BY vector_cluster(embedding, k=10)
ORDER BY size DESC;

All Modalities Combined

A complex query using all engines:

WITH relevant_docs AS (
  SELECT id, title, embedding
  FROM articles
  WHERE MATCH(body) AGAINST('database optimization')
    AND created_at > '2024-01-01'
),
author_graph AS (
  MATCH (a:Author)-[:COAUTHORED]->(b:Author)
  WHERE a.name = 'Dr. Smith'
  RETURN b.id as coauthor_id
)
SELECT rd.title, rd.score,
       a.name as author,
       cosine_distance(rd.embedding, query_vec) as similarity
FROM relevant_docs rd
JOIN authors a ON rd.author_id = a.id
WHERE a.id IN (SELECT coauthor_id FROM author_graph)
ORDER BY similarity ASC, rd.score DESC
LIMIT 20;

Optimization

Cross-Modal Query Planner

BaraDB's adaptive query optimizer (query/adaptive.nim) chooses execution order based on selectivity:

1. Most selective filter first (usually FTS or vector)
2. Push down predicates to each engine
3. Use bloom filters for KV lookups
4. Parallelize independent branches

Index Selection

The optimizer automatically selects the best index:

Query Pattern	Primary Engine	Secondary Engine
MATCH ... ORDER BY cosine_distance	Vector	FTS
MATCH ... WHERE graph condition	Graph	FTS
WHERE id = ? AND vector_search	KV	Vector
GROUP BY + MATCH	FTS	Columnar

Hints

Force a specific execution order:

SELECT /*+ USE_INDEX(vector) */ *
FROM products
WHERE category = 'electronics'
ORDER BY cosine_distance(embedding, [...])
LIMIT 10;

Performance

Cross-modal queries are optimized to minimize data movement:

Query Type	Latency (10K rows)	Latency (100K rows)
FTS + Vector	15 ms	85 ms
Graph + Vector	25 ms	120 ms
FTS + Aggregate	12 ms	55 ms
All modalities	45 ms	220 ms

Use Cases

E-Commerce Search

-- Find products matching a search term, similar to a viewed item,
-- purchased by similar users
SELECT p.name, p.price
FROM products p
WHERE MATCH(p.description) AGAINST('wireless headphones')
  AND cosine_distance(p.embedding, viewed_embedding) < 0.3
  AND p.id IN (
    SELECT product_id FROM orders o
    JOIN graph ON o.customer_id = graph.node_id
    WHERE graph.similarity > 0.8
  )
ORDER BY p.rating DESC
LIMIT 20;

Fraud Detection

-- Find transactions similar to known fraud patterns
-- where the user is connected to flagged accounts
SELECT t.id, t.amount
FROM transactions t
WHERE cosine_distance(t.pattern_vector, fraud_vector) < 0.2
  AND t.user_id IN (
    MATCH (u:User)-[*1..3]->(f:FlaggedAccount)
    RETURN u.id
  );

Knowledge Graph + RAG

-- Retrieve relevant documents for a query,
-- then traverse the knowledge graph for related concepts
WITH docs AS (
  SELECT id, content, embedding
  FROM documents
  ORDER BY cosine_distance(embedding, query_embedding)
  LIMIT 5
)
SELECT d.content, c.name as related_concept
FROM docs d
JOIN graph ON d.id = graph.doc_id
MATCH (d)-[:MENTIONS]->(c:Concept)
RETURN d.content, c.name;