Sort clauses for tables

Many Data API commands use sort clauses to sort rows by column values or to perform vector search.

Sort by column values

Use a sort clause to sort rows by column values in ascending or descending order.

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

For best performance, only sort on indexed columns, partition keys, and clustering keys. Otherwise, the Data API can perform in-memory sorting, which can have performance implications.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.constants import SortMode

# Get an existing table
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Find rows
cursor = table.find(
    {"is_checked_out": False},
    sort={
        "rating": SortMode.ASCENDING,
        "title": SortMode.DESCENDING,
    },
)

# Iterate over the found rows
for row in cursor:
    print(row)
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

(async function () {
  // Find rows
  const cursor = table.find(
    { is_checked_out: false },
    {
      sort: {
        rating: 1, // ascending
        title: -1, // descending
      },
    },
  );

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;
import com.datastax.astra.client.tables.cursor.TableFindCursor;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Find rows
    Filter filter = Filters.eq("is_checked_out", false);
    TableFindOptions options =
        new TableFindOptions().sort(Sort.ascending("rating"), Sort.descending("title"));
    TableFindCursor<Row, Row> cursor = table.find(filter, options);
    // Iterate over the found rows
    for (Row row : cursor) {
      System.out.println(row);
    }
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": { "is_checked_out": false },
    "sort": {
      "rating": 1,
      "title": -1
    }
  }
}'

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

The vector column must be indexed.

To perform a vector search with a string instead of vector embeddings, the vector column must have a vectorize integration.

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

Vector search returns up to 1000 rows per search operation, unless you specify a lower limit.

Example sorting against a search vector

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.data_types import DataAPIVector

# Get an existing table
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Find rows
cursor = table.find(
    {}, sort={"summary_genres_vector": DataAPIVector([0.12, 0.52, 0.32])}
)

# Iterate over the found rows
for row in cursor:
    print(row)
import { DataAPIClient, vector } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

(async function () {
  // Find rows
  const cursor = table.find(
    {},
    { sort: { summary_genres_vector: vector([0.12, 0.52, 0.32]) } },
  );

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.core.vector.DataAPIVector;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;
import com.datastax.astra.client.tables.cursor.TableFindCursor;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Find rows
    TableFindOptions options =
        new TableFindOptions()
            .sort(
                Sort.vector(
                    "summary_genres_vector", new DataAPIVector(new float[] {0.12f, 0.52f, 0.32f})));
    TableFindCursor<Row, Row> cursor = table.find(options);
    // Iterate over the found rows
    for (Row row : cursor) {
      System.out.println(row);
    }
  }
}

You can provide the search vector as an array of floats, or you can use $binary to provide the search vector as a Base64-encoded string. $binary can be more performant.

  • Array of floats

  • $binary

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "sort": { "summary_genres_vector": [.12, .52, .32] }
  }
}'
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "sort": { "summary_genres_vector": {"$binary": "PfXCjz8FHrg+o9cK"} }
  }
}'

Example sorting against a search string

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Find rows
cursor = table.find({}, sort={"summary_genres_vector": "Text to vectorize"})

# Iterate over the found rows
for row in cursor:
    print(row)
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

(async function () {
  // Find rows
  const cursor = table.find(
    {},
    { sort: { summary_genres_vector: "Text to vectorize" } },
  );

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;
import com.datastax.astra.client.tables.cursor.TableFindCursor;
import com.datastax.astra.client.tables.definition.rows.Row;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Find rows
    TableFindOptions options =
        new TableFindOptions().sort(Sort.vectorize("summary_genres_vector", "Text to vectorize"));

    TableFindCursor<Row, Row> cursor = table.find(options);
    // Iterate over the found rows
    for (Row row : cursor) {
      System.out.println(row);
    }
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "sort": { "summary_genres_vector": "Text to vectorize" }
  }
}'

Commands that support sort clauses for tables

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

For more examples of sort clauses, including vector search, 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