Find data with vector search

At its core, a vector database is about efficient similarity search, which is also known as vector search. Vector search finds content that is similar to a given query.

Here’s how vector search works:

Generate vector embeddings for a collection of content, and then load the data, along with the embeddings, into a vector database.

With Astra DB, you can directly provide previously-generated embeddings, you can use a vectorize integration to automatically generate embeddings from text strings, or you can use both options (some manually-provided embeddings and some automatically-generated embeddings). For more information, see $vector and $vectorize in collections.
Generate an embedding for a new piece of content outside the original collection. For example, you could generate an embedding from a text query submitted by a user to a chatbot.

Make sure you use the same embedding model for your original embeddings and your new embedding.
Use the new embedding to run a vector search on the collection and find data that is most similar to the new content.

Mechanically, a vector search determines the similarity between a query vector and the vectors of the documents in a collection. Each document’s resulting similarity score represents the closeness of the query vector and the document’s vector.
Use the returned content to produce a response or trigger an action in an LLM or GenAI application. For example, a support chatbot could use the result of a vector search to generate an answer to a user’s question.

Limitations of vector search

While vectors can replace or augment some functions of filters, vectors are not a replacement for other data types. Vector search can be powerful, particularly when combined with keyword filters, but it is important to be aware of its limitations:

Vectors aren’t human-readable. They must be interpreted by an LLM, and then transformed into a human-readable response.
Vector search isn’t meant to directly retrieve specific data. By design, vector search finds similar data.

For example, assume you have a database for your customer accounts. If you want to retrieve data for a single, specific customer, it is more appropriate to use a filter to exactly match the customer’s ID instead of a vector search.
Vector search is a mathematical approximation. By design, vector search uses mathematical calculations to find data that is mathematically similar to your query vector, but this data may not be the most contextually relevant from a human perspective.

For example, assume you have database for a department store inventory. A vector search for green hiking boots could return a mix of hiking boots, other types of boots, and other hiking gear.

Use keyword filters to narrow the context window and potentially improve the relevance of vector search results. For example, you can improve the hiking boots vector search by including a metadata filter like productType: "shoes".
The embedding model matters. It’s important to choose an embedding model that is ideal for your data, your queries, and your performance requirements. Embedding models exist for different data types (such as text, images, or audio), languages, use cases, and more.

Using an inappropriate embedding model can lead to inaccurate or unexpected results from vector searches. For example, if your dataset is in Spanish, and you choose an English language embedding model, then your vector search results could be inaccurate because the embedding model attempts to parse the Spanish text in the context of the English words that it was trained on.

Additionally, you must use the same model for your stored vectors and query vectors because mismatched embeddings can cause a vector search to fail or produce inaccurate results.

Approximate nearest neighbor

Astra DB supports only Approximate Nearest Neighbor (ANN) vector searches, not exact K-Nearest Neighbor (KNN) searches.

ANN search finds the most similar content within reason for efficiency, but it might not find the exact most similar match. Although precise, KNN is resource intensive, and it is not practical for applications that need quick responses from large datasets. ANN balances accuracy and performance, making it a better choice for applications that query large datasets or need to respond quickly.

To learn more about vector search in Astra DB Serverless, see the following:

Run a vector search in the Astra Portal

In the Astra Portal, you can use the Data Explorer to run vector searches on vector-enabled collections in Serverless (Vector) databases. For collections that aren’t vector enabled, see Find data with filters.

Use the Data Explorer for quick test searches.

For more complex searches and application development, use the Data API.

The Data API provides additional search options that aren’t available in the Astra Portal. Furthermore, you can’t edit individual documents in the Data Explorer; you must use the Data API if you want to find and edit documents. For more information, see Run a vector search with the Data API.

For required permissions for search, see Ways to find data in Astra DB Serverless.

In the Astra Portal, go to Databases, and then select a Serverless (Vector) database.

The Data Explorer isn’t available for Serverless (Non-Vector) databases. Instead, you can use the CQL shell and drivers.
Click Data Explorer.
Select a Keyspace and a vector-enabled Collection to search.

In the Search field, provide an embedding to compare against the embeddings in your collection:

Provide an embedding
Use an existing embedding
Generate an embedding from a string

Use this option if you have an embedding (typically, an array of vectors) already generated.

In the Search field, enter the literal, complete embedding that you want to use for your vector search.

Use this option if you want to test vector search by using an embedding that is already present in your collection.

In the Records section, in the Vector Search column, click Search to instantly run a vector search based on the selected document’s vector.

This search inherently results in an exact match to a document in your collection. This search isn’t representative of real-world vector search scenarios, which are designed for similarity, not exact matching. If you want to do an exact match search, see Find data with filters.

This option is available only for collections that can auto-generate embeddings with vectorize.

In the Search field, enter a natural-language text string.

When you run the search, Astra DB uses the collection’s vectorize integration to generate an embedding from your text string, and then run the vector search with that embedding.

In the Records section, the ($vectorize) label indicates the field that Astra DB uses to auto-generate embeddings for the collection’s documents. If you load additional documents into the collection, Astra DB uses the same field (if defined) to generate embeddings for those new documents.

The $vector field contains the generated embeddings. However, you can also load documents with pre-generated embeddings that you manually define in the $vector field.

Collections with a vectorize integration can use either a text string or a pre-generated embedding for vector search. To use a pre-generated embedding, enter the embedding in the Search field instead of a text string.

Optional: Use the Similarity Scores field to limit the total number of search results.
Optional: Click Add filter to add a metadata filter to your vector search.
Define a metadata filter
- Key: Select the field to filter on.
- Condition: Select a filter condition, such as is or is not. Available filters depend on the Key field’s data type. For more information about filter operators, see Filter operators for collections.
- Value: Enter the filter value.
  
  Conditions like is, is not, and contains require an exact, case-sensitive match on the Value.
  
  Filter example: is
  
  For this example, assume that you have the following filter:
  
  Key: character
  
  Condition: is
  
  Value: Lassie
  
  This filter returns documents where the character field is exactly Lassie. It doesn’t return documents with values like lassie or Lassie Come Home, which are not exact, case-sensitive matches.
  
  Filter example: is not
  
  For this example, assume that you have the following filter:
  
  Key: color
  
  Condition: is not
  
  Value: red
  
  This filter returns documents where the color field isn’t exactly red. However, it can return documents containing Red and reddish, which are not exact, case-sensitive matches.
If you add multiple filters, the filters are appended together with the and operator. For other operators, you must use the Data API.

To remove a filter, click Delete.
For more information about combining vector search with filters, see Find data with CQL analyzers.
Click Apply to run the search.

The Records section sorts the data based on the calculated similarity score for each document, from most similar to least similar. Similarity scores are based on the similarity metric that you chose when you created the collection.

The results can be limited by metadata filters and the Similarity Scores field, if you included either of these.

Run a vector search with the Data API

You can use the Data API to run vector searches on vector-enabled collections and tables in Serverless (Vector) databases.

For required permissions for search, see Ways to find data in Astra DB Serverless.

Collections
Tables

To perform a vector search on a vector-enabled collection, use a sort clause with a search vector on the $vector field. The Data API returns to document whose $vector field is most similar to the provided search vector.

If your collection has vectorize enabled, you can also use a sort clause with a search string on the $vectorize field. The vectorize integration for your collection converts the search string into a search vector, and the Data API returns the document whose $vector field is most similar to the search vector.

For Data API commands and examples, see:

To perform a vector search on a table, use a sort clause with an indexed vector column. Provide either a search vector or a search string to the sort clause.

If you provide a search vector, the Data API returns the row whose vector column value is most similar to the provided search vector.
If you provide a search string, the vector column must have a vectorize integration. The vectorize integration for your column converts the search string into a search vector, and the Data API returns the row whose vector column value is most similar to the search vector.

If your table has multiple vector columns, you can only sort on one vector column at a time.

For Data API commands and examples, see:

You can use filter and sort clauses together in the same Data API command.

For example, combining the keyword hiking with a vector search based on the phrase green boots might produce results that are more relevant than either search alone.

However, not all Data API commands allow both clauses, and some usage patterns can disallow one clause or the other. For more information and examples, see the the Data API reference documentation for the command you want to run, such as Find documents and Find rows.

Run a vector search with CQL and drivers

For information about executing vector search CQL statements with the CQL shell and drivers, see the following: