vai search

Perform vector similarity search against a MongoDB Atlas collection using $vectorSearch.

CLI

Synopsis

vai search --query <text> --db <database> --collection <name> [options]

Description

vai search embeds your query text, then runs a $vectorSearch aggregation pipeline against MongoDB Atlas to find the most similar documents. Results are returned with similarity scores, with the embedding vectors stripped from output for readability.

This is a single-stage retrieval command. For two-stage retrieval (search + rerank), use vai query.

Options

Flag	Description	Default
--query <text>	Search query (required)	—
--db <database>	Database name (required)	—
--collection <name>	Collection name (required)	—
--index <name>	Vector search index name	vector_index
--field <name>	Embedding field name	embedding
-m, --model <model>	Embedding model	voyage-4-large
--input-type <type>	Input type for query embedding	query
-d, --dimensions <n>	Output dimensions	Model default
-l, --limit <n>	Maximum results to return	10
--min-score <n>	Minimum similarity score threshold	—
--num-candidates <n>	ANN search candidates	limit × 15
--filter <json>	Pre-filter JSON for $vectorSearch	—
--json	Machine-readable JSON output	—
-q, --quiet	Suppress non-essential output	—

Examples

Basic search

vai search --query "How do I configure replica sets?" --db myapp --collection docs

Search with a filter

vai search --query "deployment" --db myapp --collection docs \
  --filter '{"category": "operations"}'

Limit results and set minimum score

vai search --query "authentication" --db myapp --collection docs --limit 5 --min-score 0.7

JSON output for downstream processing

vai search --query "vector search" --db myapp --collection docs --json | jq '.[0].text'

Use a custom index and field

vai search --query "scaling" --db myapp --collection docs \
  --index my_custom_index --field content_embedding

Playground

Using the Search Tab

The Search tab in vai playground provides a visual interface for vector similarity search against your MongoDB Atlas collections.

Getting Started

1. Run vai playground to start the web app
2. Select the Search tab from the navigation
3. Enter your database and collection names (or use defaults from .vai.json)
4. Type a search query and click Search

Features

Query input: Enter natural language search queries. The playground embeds your query and runs $vectorSearch against your collection.

Database and collection: Select which MongoDB Atlas collection to search. If you have a .vai.json config, defaults are pre-filled.

Result display: Results are shown with similarity scores, document text, and metadata. Embedding vectors are stripped for readability.

Filters: Apply MongoDB pre-filters to narrow results by metadata fields before vector comparison.

Limit and score threshold: Control how many results to return and set a minimum similarity score.

Model selection: Choose which embedding model to use for the query. Make sure it matches the model used when the documents were embedded.

Workflow Integration

Search is also available as a step in the Workflows tab. Add a search node to chain vector search with other operations like reranking or filtering.

Tips

• The --filter option maps directly to the filter parameter of MongoDB's $vectorSearch stage. Use it to narrow results by metadata before vector comparison.
• Increase --num-candidates for better recall at the cost of latency. The default (limit × 15, capped at 10,000) works well for most use cases.
• For production search with reranking, use vai query instead.

Related Commands

• vai query — Two-stage retrieval (search + rerank)
• vai store — Store documents for searching
• vai index — Manage vector search indexes