Sort clauses for collections

Many Data API commands use sort clauses to sort documents by field values, or to perform vector search or hybrid search.

Sort by field values

Use a sort clause to sort documents by field values in ascending or descending order.

When sorting by multiple fields, the order of the fields in the sort clause controls the order of the sorting.

Sort clauses can use only indexed fields. If you apply selective indexing when you create a collection, you cannot reference non-indexed fields in sort queries.

python
from astrapy import DataAPIClient
from astrapy.constants import SortMode

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Find documents
cursor = collection.find(
    {"metadata.language": "English"},
    sort={
        "rating": SortMode.ASCENDING,
        "title": SortMode.DESCENDING,
    },
)

To find the documents whose $vector value is most similar to a given vector, use a sort clause with the vector embeddings that you want to match. To find the documents whose $vector value is most similar to the $vector value generated from a given search string, use a sort with the search string that you want to vectorize and match. For more information, see Find data with vector search.

Vector search is only available for vector-enabled collections. For more information, see Create a collection that can store vector embeddings and $vector in collections.

Vector search with vectorize is only available for collections that have vectorize enabled. For more information, see Create a collection that can automatically generate vector embeddings and $vectorize in collections.

Example sorting against a search vector

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Find documents
cursor = collection.find({}, sort={"$vector": [0.12, 0.52, 0.32]})

Example sorting against a search string

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Find documents
cursor = collection.find({}, sort={"$vectorize": "Text to vectorize"})

A hybrid search uses a reranker model to combine results from a vector search and a lexical search. When you find documents via hybrid search, you use a sort clause to specify the queries for the underlying vector search and hybrid search.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT",
    token="APPLICATION_TOKEN",
)
collection = database.get_collection("COLLECTION_NAME")

# Find documents
cursor = collection.find_and_rerank(
    sort={
        "$hybrid": {"$vectorize": "A tree on a hill", "$lexical": "house woods forest"},
    },
)

Commands that support sort clauses for collections

There are many Data API commands that support sort clauses for collections.

For more examples of sort clauses, including vector search and hybrid search examples, see the reference for the command that you want to run:

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