Perform a vector search

After you load data into a collection, you can use the Astra Portal’s Data Explorer or the Data API to view, search, and filter your data.

You can use the Data Explorer to perform simple searches on your data. For more complex searches and application development, use the Data API to perform searches programmatically. The Data API provides additional search options that aren’t available in the Astra Portal. For more information, see Find a document and Find documents.

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:

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

  2. 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.

  3. 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.

  4. 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.

While vectors can replace or augment some functions of a traditional database query, vectors are not a replacement for other data types. Vector search is best used as a supplement to traditional search techniques, such as sorting and filtering, because 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 traditional search filter on 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 traditional search 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 traditional 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 What is Vector Search, Vector Search on Astra DB on the DataStax Developers YouTube channel, and What is the K-Nearest Neighbors (KNN) Algorithm.

Prerequisites

To perform a vector search, you need a role or application token that can view the database and collection that you want to search.

You can use a built-in role or a custom role with the following permissions: View DB, Describe All Keyspaces, Describe Keyspace, Select Table, and Describe Table.

You can use the Astra Portal or the Data API to perform a vector search.

Find documents with vector search and vectorize

For collections that auto-generate embeddings with vectorize, you can perform a vector search by providing a natural-language text string. Vectorize generates an embedding from your text string, and then runs the vector search based on that embedding.

You can use the Astra Portal or the Data API to perform a search with vectorize.

  • Astra Portal

  • Python

  • TypeScript

  • Java

  • curl

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

  2. Click Data Explorer.

  3. Select the Keyspace and Collection that contain the data you want to view.

    In the Collection Data section, the ($vectorize) label indicates the field that you designated to auto-generate embeddings for this collection’s documents. The $vector field contains the generated embeddings.

  4. In the Vector Search field, enter a text query, and then click Apply.

    Using the collection’s embedding provider integration, Astra DB generates a vector for your text query, and then performs a vector search.

    The Collection Data 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.

  5. Optional: Use metadata filters to refine the search results based on other fields in the collection:

    1. Click Add Filter, and then configure the filter:

      • Key: Select the field to filter on.

      • Condition: Select the filter operator to use. The is condition performs an exact match of a scalar or value within an array, and the contains condition performs an exact match of a value within an array. Some data types have a default condition.

        The Data API supports more operators than the Astra Portal. If you need more filtering options, consider using the Data API clients.

      • Value: Enter a filter value.

        All conditions are case-sensitive and the filter value must be an exact match.

        Filter example: is

        For this example, assume that you have the following filter:

        • Key: character

        • Condition: is

        • Value: Lassie

        This filter returns all documents with a character field set to a scalar value of "Lassie" or set to an array containing a value of "Lassie".

        This matches values like "Lassie" and ["Lassie", "Timmy"], but this does not match values like "lassie", "Lassie Come Home", or ["lassie", "Timmy"].

        Filter example: contains

        For this example, assume that you have the following filter:

        • Key: color

        • Condition: contains

        • Value: red

        This filter returns all documents with a color field set to an array containing a value of "red".

        This matches values like ["red", "blue", "green"] and ["red"], but this does not match values like "red", ["reddish", "Red", "Green", "Blue"], or ["green", "blue"].

    2. To add more filters, click Add Filter again.

    3. Click Apply to refresh the Collection Data section based on your filters.

For more information about this command and related commands, see Find a document, Find documents, and Find distinct values. For a complete list of filter conditions, see Data API query operators. For information about $vector and $vectorize, see Vector and vectorize.

Perform a vector search with vectorize:

# Perform a vector search
query = "I'd like some talking shoes"
results = collection.find(
    sort={"$vectorize": query},
    limit=2,
    projection={"$vectorize": True},
    include_similarity=True,
)
print(f"Vector search results for '{query}':")
for document in results:
    print("    ", document)

Perform a vector search with vectorize and metadata filters:

# Perform a vector search with metadata filters
query = "I'd like some talking shoes"
results = collection.find(
    {"$and": [
        {"price": {"$gte": 100}},
        {"name": "John"}
    ]},
    sort={"$vectorize": query},
    limit=10,
    projection={"$vectorize": True},
)
print("Vector search results:")
for document in results:
    print("    ", document)

For vector search, the response is a single page of up to 1000 documents, unless you set a lower limit.

You can use a projection to include specific document properties in the response. A projection is required if you want to return certain reserved fields, like $vector and $vectorize, that are excluded by default.

For more information about this command and related commands, see Find a document, Find documents, and Find distinct values. For a complete list of filter conditions, see Data API query operators. For information about $vector and $vectorize, see Vector and vectorize.

Perform a vector search with vectorize:

  // Perform a vector search
  const cursor = await collection.find({}, {
    sort: { $vectorize: 'shoes' },
    limit: 2,
    includeSimilarity: true,
  });

  console.log('* Search results:')
  for await (const doc of cursor) {
    console.log('  ', doc.text, doc.$similarity);
  }

Perform a vector search with vectorize and metadata filters:

  // Perform a vector search with metadata filters
  const cursor = await collection.find({
    $and: [
      { price: { $gte: 100 } },
      { name: 'John' }
    ]
  }, {
    sort: { $vectorize: 'shoes' },
    limit: 10,
    includeSimilarity: true,
  });

  console.log('* Search results:')
  for await (const doc of cursor) {
    console.log('  ', doc);
  }

For vector search, the response is a single page of up to 1000 documents, unless you set a lower limit.

You can use a projection to include specific document properties in the response. A projection is required if you want to return certain reserved fields, like $vector and $vectorize, that are excluded by default.

For more information about this command and related commands, see Find a document, Find documents, and Find distinct values. For a complete list of filter conditions, see Data API query operators. For information about $vector and $vectorize, see Vector and vectorize.

Perform a vector search with vectorize:

// Perform a vector search
FindOptions findOptions = new FindOptions()
       .limit(2)
       .includeSimilarity()
       .sort("I'd like some talking shoes");
FindIterable<Document> results = collection.find(findOptions);
for (Document document : results) {
   System.out.println("Document: " + document);
}

You can use metadata filters with a vectorize vector search in the same way that you would with a regular vector search.

For vector search, the response is a single page of up to 1000 documents, unless you set a lower limit.

You can use a projection to include specific document properties in the response. A projection is required if you want to return certain reserved fields, like $vector and $vectorize, that are excluded by default.

For more information about this command and related commands, see Find a document, Find documents, and Find distinct values. For a complete list of filter conditions, see Data API query operators. For information about $vector and $vectorize, see Vector and vectorize.

Perform a vector search with vectorize:

# Perform a vector search
curl -sS -L -X POST "$ASTRA_DB_API_ENDPOINT/api/json/v1/default_keyspace/pass:q[**COLLECTION_NAME**]" \
--header "Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "sort": {"$vectorize": "Talking shoes"},
    "projection": {"$vectorize": 1},
    "options": {
      "includeSimilarity": true,
      "limit": 10
    }
  }
}' | jq

Perform a vector search with vectorize and metadata filters:

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": {
      "$and": [
        { "customer.credit_score": { "$gte": 700 } },
        { "customer.credit_score": { "$lt": 800 } }
      ]
    }
    "sort": { "$vectorize": "green car" },
    "options": {
      "limit": 100
    }
  }
}' | jq

For vector search, the response is a single page of up to 1000 documents, unless you set a lower limit.

You can use a projection to include specific document properties in the response. A projection is required if you want to return certain reserved fields, like $vector and $vectorize, that are excluded by default.

Perform a vector search on a table

The preceding sections described how to perform a vector search on a collection in a vector database.

For information about performing vector searches on tables, see the following:

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com