Sort clauses for tables (C#)

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.

  • Typed

  • Untyped

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnPrimaryKey(2)]
  [ColumnName("author")]
  public string Author { get; set; } = null!;

  [ColumnName("rating")]
  public float? Rating { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable<Book>("TABLE_NAME");

    // Find rows
    var results = table.Find(
      new TableFindOptions<Book>()
      {
        Sort = Builders<Book>
          .TableSort.Ascending(b => b.Rating)
          .Descending(b => b.Title),
      }
    );

    await foreach (var row in results)
    {
      Console.WriteLine(JsonSerializer.Serialize(row));
    }
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable("TABLE_NAME");

    // Find rows
    var results = table.Find(
      new TableFindOptions<Row>()
      {
        Sort = Builders<Row>
          .TableSort.Ascending("rating")
          .Descending("title"),
      }
    );

    await foreach (var row in results)
    {
      Console.WriteLine(JsonSerializer.Serialize(row));
    }
  }
}

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

  • Typed

  • Untyped

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnPrimaryKey(2)]
  [ColumnName("author")]
  public string Author { get; set; } = null!;

  [ColumnVector(5)]
  [ColumnName("summary_genres_vector")]
  public object? SummaryGenresVector { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable<Book>("TABLE_NAME");

    // Find rows
    var embeddings = new float[] { 0.08f, -0.62f, 0.39f };
    var results = table.Find(
      new TableFindOptions<Book>()
      {
        Sort = Builders<Book>.TableSort.Vector(
          b => b.SummaryGenresVector,
          embeddings
        ),
      }
    );

    await foreach (var row in results)
    {
      Console.WriteLine(JsonSerializer.Serialize(row));
    }
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable("TABLE_NAME");

    // Find rows
    var embeddings = new float[] { 0.08f, -0.62f, 0.39f };
    var results = table.Find(
      new TableFindOptions<Row>()
      {
        Sort = Builders<Row>.TableSort.Vector(
          "summary_genres_vector",
          embeddings
        ),
      }
    );

    await foreach (var row in results)
    {
      Console.WriteLine(JsonSerializer.Serialize(row));
    }
  }
}

Example sorting against a search string

  • Typed

  • Untyped

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnPrimaryKey(2)]
  [ColumnName("author")]
  public string Author { get; set; } = null!;

  [ColumnVectorize(
    provider: "nvidia",
    modelName: "nvidia/nv-embedqa-e5-v5",
    dimension: 1024
  )]
  [ColumnName("summary_genres_vector")]
  public object? SummaryGenresVector { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable<Book>("TABLE_NAME");

    // Find rows
    var results = table.Find(
      new TableFindOptions<Book>()
      {
        Sort = Builders<Book>.TableSort.Vectorize(
          b => b.SummaryGenresVector,
          "Text to vectorize"
        ),
      }
    );

    await foreach (var row in results)
    {
      Console.WriteLine(JsonSerializer.Serialize(row));
    }
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable("TABLE_NAME");

    // Find rows
    var results = table.Find(
      new TableFindOptions<Row>()
      {
        Sort = Builders<Row>.TableSort.Vectorize(
          "summary_genres_vector",
          "Text to vectorize"
        ),
      }
    );

    await foreach (var row in results)
    {
      Console.WriteLine(JsonSerializer.Serialize(row));
    }
  }
}

Sort by lexicographical matching (BM25-based ranking)

Lexicographical matching is currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

To find rows with a text or ascii column value that is most relevant to a given string of space-separated keywords or terms, sort on a column that is associated with a text index.

Lexicographical matching is only available for text or ascii columns that have a text index, not a regular index. For more information, see Create a text index (C#) and Indexes in tables (C#).

When performing this type of sort, you can’t include additional sort clauses.

  • Typed

  • Untyped

You can manually define a client-side type for your table to help statically catch errors. For more information and examples, see Custom typing for tables.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Book
{
  [ColumnPrimaryKey(1)]
  [ColumnName("title")]
  public string Title { get; set; } = null!;

  [ColumnPrimaryKey(2)]
  [ColumnName("author")]
  public string Author { get; set; } = null!;

  [ColumnName("summary")]
  public string? Summary { get; set; }
}

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable<Book>("TABLE_NAME");

    // Find a row
    var findOptions = new TableFindOneOptions<Book>()
    {
      Sort = Builders<Book>.TableSort.Lexical(
        b => b.Summary,
        "futuristic laboratory discovery"
      ),
    };
    var result = await table.FindOneAsync(findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

If you don’t pass a type parameter, the collection or table remains untyped. This is a more flexible but less type-safe option.

using System.Text.Json;
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Core.Query;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
    var table = database.GetTable("TABLE_NAME");

    // Find a row
    var findOptions = new TableFindOneOptions<Row>()
    {
      Sort = Builders<Row>.TableSort.Lexical(
        "summary",
        "futuristic laboratory discovery"
      ),
    };
    var result = await table.FindOneAsync(findOptions);

    Console.WriteLine(JsonSerializer.Serialize(result));
  }
}

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, see the reference for the command that you want to run:

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | 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: Contact IBM