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

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?