Feature Request: Support for Vector Search (APPROX_VECTOR_DISTANCE) in SQL++ Queries

[Fujio-Turner]

Description

Vector search using APPROX_VECTOR_DISTANCE() is not available in cbl-reactnative. This function is supported in Couchbase Lite 3.2+ for Swift/Kotlin/C but the React Native plugin does not expose this functionality.

Expected Behavior

Should be able to execute SQL++ queries using APPROX_VECTOR_DISTANCE() to find similar vectors:

const query = `
  SELECT META().id, *, APPROX_VECTOR_DISTANCE(embedding, $queryVector) AS distance
  FROM catalog.vectors
  WHERE APPROX_VECTOR_DISTANCE(embedding, $queryVector) < 0.5
  ORDER BY APPROX_VECTOR_DISTANCE(embedding, $queryVector)
  LIMIT 10
`;

const queryObj = await database.createQuery(query);
const params = new Parameters();
params.setValue('queryVector', queryVector); // number[] with 512 dimensions
queryObj.parameters = params;

const results = await queryObj.execute();

Actual Behavior

Queries with APPROX_VECTOR_DISTANCE() fail. The cbl-reactnative documentation confirms this limitation:

"Vector Search - This is still in beta for the native platforms and is not yet supported in the plugin."

Source: https://cbl-reactnative.dev/ (Limitations section)

Additional Requirements

Vector search also requires:

1. VectorIndexConfiguration - Need ability to create vector indexes:

const vectorIndexConfig = new VectorIndexConfiguration(
  'embedding',    // expression - field containing the vector
  512,            // dimensions
  100             // centroids
);
vectorIndexConfig.setMetric(DistanceMetric.COSINE);

await collection.createIndex('vectors_embedding_idx', vectorIndexConfig);

2. VectorEncoding options - For compression (None, SQ, PQ)

Use Case

Building a visual product search feature for a mobile app:

1. User captures image with camera
2. Generate CLIP embedding (512-dim vector) on-device
3. Query Couchbase Lite to find similar products using vector similarity
4. Display matching results

Currently impossible without vector search support.

Environment

Package	Version
cbl-reactnative	0.6.3
React Native	0.76.3
Expo SDK	52.0.0
Platform	iOS 18.6 (iPhone 16 Pro Simulator)
Couchbase Lite (underlying)	3.2.x

Workaround

Currently using a simple query without vector distance:

const query = `
  SELECT META().id, *
  FROM catalog.vectors
  LIMIT ${limit}
`;

This returns vectors but cannot calculate similarity or order by distance.

References

• Couchbase Lite Swift Vector Search Guide
• Couchbase Lite Vector Index Configuration
• cbl-reactnative Limitations

Related

This feature would enable AI-powered mobile apps with:

• Visual search (image → embedding → similar products)
• Semantic text search
• RAG (Retrieval Augmented Generation) on mobile
• Offline-first vector similarity

---

Would you like me to save this to a markdown file for easy copy/paste?

[Fujio-Turner]

Implementation PRs Submitted

I've analyzed the cbl-reactnative architecture and submitted PRs to add vector search support:

Pull Requests

Repository	PR	Description
cblite-js	#43	TypeScript: VectorIndex, VectorIndexConfiguration, enums
cbl-js-swift	#21	Swift: CollectionManager+Vector extension
cbl-reactnative	#87	Android: CollectionManagerVector.kt

Architecture

The implementation adds the "vector" case to the existing index creation flow:

TypeScript (VectorIndexConfiguration.toJson())
    ↓
React Native Bridge
    ↓
Swift/Kotlin (createVectorIndex → CBL VectorIndexConfiguration)
    ↓
Couchbase Lite 3.2.x (native vector search)

Usage After Merge

import { VectorIndexConfiguration, DistanceMetric } from 'cbl-reactnative';

// Create vector index
const config = new VectorIndexConfiguration('embedding', 512, 100);
config.metric = DistanceMetric.COSINE;
await collection.createIndex('embedding_idx', config);

// Query with APPROX_VECTOR_DISTANCE
const query = \`
  SELECT META().id, APPROX_VECTOR_DISTANCE(embedding, \$qv) AS distance
  FROM catalog.vectors
  ORDER BY APPROX_VECTOR_DISTANCE(embedding, \$qv)
  LIMIT 10
\`;

Happy to address any feedback on the PRs!