Find rows

This Astra DB Serverless feature 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.

The Data API tables commands are available through HTTP and the clients.

If you use a client, tables commands are available only in client versions 2.0-preview or later. For more information, see Data API client upgrade guide.

Finds rows in a table using filter and sort clauses.

For general information about working with tables and rows, see About tables.

Method signature

  • Python

  • TypeScript

  • Java

  • curl

The following method belongs to the astrapy.Table class.

find(
  filter: Dict[str, Any],
  *,
  projection: Iterable[str] | Dict[str, bool],
  row_type: type,
  skip: int,
  limit: int,
  include_similarity: bool,
  include_sort_vector: bool,
  sort: Dict[str, Any],
  request_timeout_ms: int,
  timeout_ms: int,
) -> TableFindCursor

The following method belongs to the Table class.

find(
  filter: TableFilter<WSchema>,
  options?: {
    sort?: Sort,
    projection?: Projection,
    limit?: number,
    skip?: number
    includeSimilarity?: boolean,
    includeSortVector?: boolean,
    timeout?: number | TimeoutDescriptor,
  }
): TableFindCursor<WithSim<RSchema>, WithSim<RSchema>>

The following methods belong to the com.datastax.astra.client.tables.Table class.

TableCursor<T, T> find(
  Filter filter,
  TableFindOptions options
)
TableCursor<T, T> find(
  Filter filter
)
TableCursor<T, T> find(
  TableFindOptions options
)
<R> TableCursor<T, R> find(
  Filter filter,
  TableFindOptions options,
  Class<R> rowClass
)
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": FILTER,
    "sort": SORT,
    "projection": PROJECTION,
    "options": {
      "includeSimilarity": BOOLEAN,
      "includeSortVector": BOOLEAN,
      "skip": INTEGER,
      "limit": INTEGER
    }
  }
}'

Result

  • Python

  • TypeScript

  • Java

  • curl

Returns a cursor (astrapy.cursors.TableFindCursor) for iterating over rows that match the specified filter and sort clauses.

The columns included in the returned rows depend on the subset of columns that were requested in the projection.

If requested and applicable, each row will also include a $similarity key with a numeric similarity score that represents the closeness of the sort vector and the row’s vector.

If requested when executing a vector search with vectorize, the result will also include the sort vector.

When you iterate over the cursor, rows are fetched in batches. The fetched batches may reflect real-time updates on the table.

If you need a list of all results, you can invoke .to_list() on the cursor instead of iterating over the cursor. However, the time and memory required for this operation depend on the number of results. This is not recommended when you expect a large number of rows.

For more information about iterating over and manipulating the cursor, see FindCursor.

Returns a cursor (TableFindCursor<RSchema>) for iterating over rows that match the specified filter and sort clauses.

The columns included in the returned rows depend on the subset of columns that were requested in the projection.

If requested and applicable, each row will also include a $similarity key with a numeric similarity score that represents the closeness of the sort vector and the row’s vector.

If requested when executing a vector search with vectorize, the result will also include the sort vector.

If you need a list of all results, you can call toArray() on the cursor instead of iterating over the cursor. However, the time and memory required for this operation depend on the number of results. This is not recommended when you expect a large number of rows.

Returns a cursor (TableCursor<T, R>) for iterating over rows that match the specified filter and sort clauses.

If rowClass is not specified, then the type R is the same type as that of the rows in the table.

The columns included in the returned rows depend on the subset of columns that were requested in the projection.

If requested and applicable, each row will also include a $similarity key with a numeric similarity score that represents the closeness of the sort vector and the row’s vector.

If requested when executing a vector search with vectorize, the result will also include the sort vector.

If you need a list of all results, you can use .to_list() to exhaust the cursor. However, the time and memory required for this operation depend on the number of results. This is not recommended when you expect a large number of rows.

The response includes a data.documents property, which is an array of objects representing rows that match the specified filter and sort clauses.

The columns included in the returned rows depend on the subset of columns that were requested in the projection. If requested and applicable, each row will also include a $similarity key with a numeric similarity score that represents the closeness of the sort vector and the row’s vector.

If the query supports pagination, the response also includes a data.nextPageState property, which indicates the ID of the next page of results, if any. For non-vector searches, the results will be paginated if more than 20 rows match the specified filter and sort clauses.

For vector search (with $vector or $vectorize), returns a single page of up to 1000 rows (or a lower amount if specified).

Some operations do not support pagination. These include:

  • Operations that require in-memory sort, such as allow filtering on non-indexed columns. The Data API returns a warning if this happens.

  • Vector searches.

  • Certain combinations of sort and filter options.

If requested when executing a vector search with vectorize, the result also includes a status.sortVector property, which is the sort vector used for the search.

Example response:

{
  "data": {
    "documents":[
      {
        "_id":"85a54382-9227-4075-a543-829227407556",
        "title":"Within Silence of the Past",
        "isCheckedOut":false
      },
      {
        "_id":"aa762475-4fc1-4477-b624-754fc1f477c7",
        "title":"Beyond Dreams and Forgotten Worlds",
        "isCheckedOut":false
      }
    ],
    "nextPageState":"LQAAAAEBAAAAJGQ2OTk5NzY2LTgyODQtNDc3Mi05OTk3LTY2ODI4NGU3NzJjYQDwf///6wA="
  }
}

Example response if no rows were found:

{
  "data": {
    "documents": [],
    "nextPageState": null
  }
}

Parameters

  • Python

  • TypeScript

  • Java

  • curl

For best performance, filter and sort on indexed columns, partition keys, and clustering keys.

Filtering on non-indexed columns can use allow filtering, which is inefficient and resource-intensive, especially for large datasets. With the Data API clients, allow filtering operations can hit the client timeout limit before the underlying HTTP operation is complete.

An empty filter ("filter": {}) does not use allow filtering, but it can still be an inefficient and long-running operation.

Additionally, the Data API can perform in-memory sorting, depending on the columns you sort on, the table’s partitioning structure, and whether the sorted columns are indexed. In-memory sorts can have performance implications.
Name Type Summary

filter

dict | None

A dictionary expressing which condition the returned row must satisfy. You can use filter operators to compare columns with literal values. For example:

  • {"match_no": 123}: Uses the implied equality ($eq) operator. Shorthand for {"match_no": {"$eq": 123}}.

  • {"match_no": 123, "round": "C"}: Uses the implied equality operator and combines the two conditions with an implicit $and.

  • (Not recommended) {}: An empty filter returns all rows. This is slow and inefficient.

You cannot filter on map, list, or set columns.

To perform a vector search, use sort instead of filter.

sort

dict | None

This dictionary parameter controls the sorting order and, therefore, determines which row is returned if there are multiple matches. The sort parameter can express either a vector search or regular ascending/descending sorting. For more information, see Sort clauses for tables.

projection

dict | None

Select a subset of columns to include in the response for the returned row:

  • Include only the given columns: {"column1": True, "column2": True}

  • Include all columns except the given columns: {"column1": False, "column2": False}

  • Include all columns (default if empty or unspecified): {"*": True}

DataStax recommends using projections to optimize bandwidth, especially to avoid unnecessarily returning large columns, such as vector columns with highly dimensional embeddings.

For more information and examples, see Projections for tables.

row_type

type

This parameter acts a formal specifier for the type checker. If omitted, the resulting cursor is implicitly a TableFindCursor[ROW, ROW], meaning that it maintains the same type for the returned rows as that of the rows in the table. Strictly typed code may want to specify this parameter, especially when a projection is given. For more information, see Typing support.

skip

int | None

Optionally specify a number of rows to bypass (skip) before returning rows. The first n rows matching the query are discarded from the results, and the results begin at the skip+1 row. For example, if skip=5, the first 5 rows are discarded, and the results begin at the 6th row.

This parameter is only valid with sort.

limit

int | None

Limit the total number of rows returned from the table. The returned cursor stops yielding rows either when it reaches the limit or there are no more rows to return.

include_similarity

bool | None

If true, the returned rows include a $similarity key with the numeric similarity score representing the closeness of the sort vector and the row’s vector. This is only valid for vector search (sort on a vector column).

include_sort_vector

bool | None

If true, you can call the get_sort_vector method on the returned cursor to get the vector used for the vector search. The default is false. This is only relevant for vector search (sort on a vector column) when you want to get the sort vector from the returned cursor. This can be useful with vectorize because you don’t know the sort vector in advance.

You can’t use include_sort_vector with find_one, but you can use include_sort_vector and limit=1 with find. However, because vector search is approximate (as in approximate nearest neighbor), the lower your limit, the more likely you are to find an approximate, but not maximal, match.

request_timeout_ms

int

A timeout, in milliseconds, to impose on each individual HTTP request to the Data API to accomplish the operation. If not provided, the Table defaults apply. This parameter is aliased as timeout_ms for convenience.

For best performance, filter and sort on indexed columns, partition keys, and clustering keys.

Filtering on non-indexed columns can use allow filtering, which is inefficient and resource-intensive, especially for large datasets. With the Data API clients, allow filtering operations can hit the client timeout limit before the underlying HTTP operation is complete.

An empty filter ("filter": {}) does not use allow filtering, but it can still be an inefficient and long-running operation.

Additionally, the Data API can perform in-memory sorting, depending on the columns you sort on, the table’s partitioning structure, and whether the sorted columns are indexed. In-memory sorts can have performance implications.
Name Type Summary

filter

TableFilter

An object that defines filter criteria using the Data API filter syntax. For more information and examples, see Filter operators for tables.

You cannot filter on map, list, or set columns.

To perform a vector search, use sort instead of filter.

option?

TableFindOptions

The options for this operation

Options (TableFindOptions):

Name Type Summary

sort?

Sort

The sort parameter can express either a vector search or regular ascending/descending sorting. For more information, see Sort clauses for tables.

projection?

Projection

Select a subset of columns to include in the response for the returned rows:

  • Include only the given columns: {column1: 1, column2: 1}

  • Include all columns except the given columns: {column1: 0, column2: 0}

If empty or unspecified, the default projection (all columns) is used.

DataStax recommends using projections to optimize bandwidth, especially to avoid unnecessarily returning large columns, such as vector columns with highly dimensional embeddings.

Additionally, DataStax recommends providing your own type for the returned rows because projections can break typing guarantees. If your query includes projection, then you must include $similarity in the type of the returned rows.

For more information and examples, see Projections for tables.

skip?

number

Optionally specify a number of rows to bypass (skip) before returning rows. The first n rows matching the query are discarded from the results, and the results begin at the skip+1 row. For example, if skip=5, the first 5 rows are discarded, and the results begin at the 6th row.

This parameter is only valid with sort.

limit?

number

Limit the total number of rows returned from the table. The returned cursor stops yielding rows either when it reaches the limit or there are no more rows to return.

includeSimilarity?

boolean

If true, the returned rows include a $similarity key with the numeric similarity score representing the closeness of the sort vector and the row’s vector. This is only valid for vector search (sort on a vector column).

If your query includes projection, then you must manually include $similarity in the type of the returned row. If you don’t include projection, then $similarity is inferred to be a part of the returned row. For more information, see sort clauses and Projections for tables.

includeSortVector?

boolean

If true, you can call the cursor.getSortVector() method to get the vector used for the vector search. The default is false. This is only relevant for vector search (sort on a vector column) when you want to get the sort vector from the returned cursor. This can be useful with vectorize because you don’t know the sort vector in advance.

You can’t use includeSortVector with findOne, but you can use includeSortVector and limit(1) with find. However, because vector search is approximate (as in approximate nearest neighbor), the lower your limit, the more likely you are to find an approximate, but not maximal, match.

timeout?

number | TimeoutDescriptor

The client-side timeout for this operation.

For best performance, filter and sort on indexed columns, partition keys, and clustering keys.

Filtering on non-indexed columns can use allow filtering, which is inefficient and resource-intensive, especially for large datasets. With the Data API clients, allow filtering operations can hit the client timeout limit before the underlying HTTP operation is complete.

An empty filter ("filter": {}) does not use allow filtering, but it can still be an inefficient and long-running operation.

Additionally, the Data API can perform in-memory sorting, depending on the columns you sort on, the table’s partitioning structure, and whether the sorted columns are indexed. In-memory sorts can have performance implications.
Name Type Summary

filter

Filter

A filter expressing which condition the returned rows must satisfy. You can use filter operators to compare columns with literal values. Filters can be instantiated with its constructor and specialized with method where(..) or leverage the class Filters.

You cannot filter on map, list, or set columns.

To perform a vector search, use sort instead of filter.

options

TableFindOptions

A wrapper for the different options and specialization of this search.

rowClass

Class<?>

This parameter acts a formal specifier for the type checker. If omitted, the resulting cursor is implicitly a TableFindCursor<T>, meaning that the response maintains the same type for the returned rows as the rows in the table itself. Strictly typed code may want to specify this parameter, especially when a projection is given. For related information, albeit in the context of the Python client, see Typing support.

TableFindOptions

Name Type Summary

sort

Sort

The sort parameter can express either a vector search or regular ascending/descending sorting. For more information, see Sort clauses for tables.

projection

Projection

Select a subset of columns to include in the response for the returned rows:

  • Include only the given columns: Projection.include("column1","column2")

  • Include all columns except the given columns: Projection.exclude("column1","column2")

If empty or unspecified, the default projection (all columns) is used.

DataStax recommends using projections to optimize bandwidth, especially to avoid unnecessarily returning large columns, such as vector columns with highly dimensional embeddings.

For more information and examples, see Projections for tables.

includeSimilarity

boolean

If true, the returned rows include a $similarity key with the numeric similarity score representing the closeness of the sort vector and the row’s vector. This is only valid for vector search (sort on a vector column).

includeSortVector

boolean

If true, you can call the getSortVector() method on the returned cursor to get the vector used for the vector search. The default is false. This is only relevant for vector search (sort on a vector column) when you want to get the sort vector from the returned cursor. This can be useful with vectorize because you don’t know the sort vector in advance.

You can’t use includeSortVector with findOne, but you can use includeSortVector and limit(1) with find. However, because vector search is approximate (as in approximate nearest neighbor), the lower your limit, the more likely you are to find an approximate, but not maximal, match.

skip

int

Optionally specify a number of rows to bypass (skip) before returning rows. The first n rows matching the query are discarded from the results, and the results begin at the skip+1 row. For example, if skip(5), the first 5 rows are discarded, and the results begin at the 6th row.

This parameter is only valid with sort.

limit

int

Limit the total number of rows returned from the table. The returned cursor stops yielding rows either when it reaches the limit or there are no more rows to return.

timeout

long or Duration

A timeout, in milliseconds (long), to impose on the underlying API request. If not provided, the Table defaults apply.

For best performance, filter and sort on indexed columns, partition keys, and clustering keys.

Filtering on non-indexed columns can use allow filtering, which is inefficient and resource-intensive, especially for large datasets. With the Data API clients, allow filtering operations can hit the client timeout limit before the underlying HTTP operation is complete.

An empty filter ("filter": {}) does not use allow filtering, but it can still be an inefficient and long-running operation.

Additionally, the Data API can perform in-memory sorting, depending on the columns you sort on, the table’s partitioning structure, and whether the sorted columns are indexed. In-memory sorts can have performance implications.
Name Type Summary

find

command

The Data API command to retrieve multiple rows in a table based on one or more of filter, sort, projection, and options.

filter

object

An object that defines filter criteria using the Data API filter syntax. For a list of available operators, see Filter operators for tables.

You cannot filter on map, list, or set columns.

To perform a vector search, use sort instead of filter.

sort

object

Perform a vector search or set the order in which rows are returned. For more information and examples, see sort clauses and Vector type.

projection

object

Select a subset of columns to include in the response for each returned row. If empty or unset, the default projection is used. The default projection includes all columns, but it omits null values.

The response always omits null values, even if you include them in projection.

For more information and examples, see Projections for tables.

skip

integer

Specify a number of rows to bypass (skip) before returning rows. The first n rows matching the query are discarded from the results, and the results begin at the skip+1 row. For example, if "skip": 5, the first 5 rows are discarded, and the results begin at the 6th row.

This parameter is only valid with sort.

limit

integer

Limit the total number of rows returned. Pagination can occur if more than 20 rows are returned in the current set of matching rows. Once the limit is reached, either in a single response or the last page of a paginated response, nothing more is returned.

options.includeSimilarity

boolean

If true, the response includes a $similarity key with the numeric similarity score that represents the closeness of the sort vector and the row’s vector. This is only valid for vector search (sort on a vector column).

options.includeSortVector

boolean

If true, the response includes the sortVector. The default is false. This is only relevant for vector search (sort on a vector column) when you want the response to include the sort vector. This can be useful with vectorize because you don’t know the sort vector in advance.

"find": {
  "sort": { "vect_emb": [ "some string" ] },
  "options": {
    "includeSortVector": true
  }
}

You can’t use includeSortVector with findOne, but you can use includeSortVector and limit: 1 with find. However, because vector search is approximate (as in approximate nearest neighbor), the lower your limit, the more likely you are to find an approximate, but not maximal, match.

Examples

The following examples demonstrate how to find rows in a table.

Use filters to find rows

You can use a filter to find rows that matches specific criteria. For example, you can find rows with an isCheckedOut value of false and a numberOfPages value less than 300.

For optimal performance, you only filter on indexed columns. The Data API returns a warning if you filter on a non-indexed column.

You cannot filter on map, list, or set columns.

For a list of available filter operators, see Filter operators for tables.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

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

# Find rows
cursor = table.find(
    {
        "$and": [
            {"isCheckedOut": False},
            {"numberOfPages": {"$lt": 300}},
        ]
    }
)

# 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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

(async function () {
  // Find rows
  const cursor = table.find({
    $and: [{ isCheckedOut: false }, { numberOfPages: { $lt: 300 } }],
  });

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

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.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.cursor.TableCursor;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;

public class Find {

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

        // Find rows
        Filter filter = Filters.and(
          Filters.eq("isCheckedOut", false),
          Filters.lt("numberOfPages", 300));

        TableFindOptions options = new TableFindOptions();

        TableCursor<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 "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": {"$and": [
      {"isCheckedOut": false},
      {"numberOfPages": {"$lt": 300}}
    ]}
  }
}'

Use vector search with a search vector to find rows

Perform a vector search by providing a search vector in the sort clause. This returns the row whose vector column value is most similar to the provided search vector.

The vector column must be indexed.

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

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.data_types import DataAPIVector

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

# Find rows
cursor = table.find(
    {},
    sort={"summaryGenresVector": DataAPIVector([.12, .52, .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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

(async function () {
  // Find rows
  const cursor = table.find(
    {},
    { sort: { summaryGenresVector: vector([.12, .52, .32]) } }
  );

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.vector.DataAPIVector;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.cursor.TableCursor;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;

public class Find {

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

        // Find rows
        TableFindOptions options = new TableFindOptions()
            .sort(Sort.vector("summaryGenresVector", new DataAPIVector(new float[] {0.12f, 0.52f, 0.32f})));
        TableCursor<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 or as a binary.

Example with the search vector as an array:

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "sort": { "summaryGenresVector": [.12, .52, .32] }
  }
}'

Example with the search vector as a binary:

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "sort": { "summaryGenresVector": { "$binary": "PczMzb5MzM0+mZma" } }
  }
}'

Use vector search with a search string to find rows

Perform a vector search by providing a search string in the sort clause. The search string is converted to a search vector, and the row whose vector column value is most similar to the search vector is returned.

The vector column must have a vectorize integration. The vector column must be indexed.

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

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

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

# Find rows
cursor = table.find(
    {},
    sort={"summaryGenresVector": "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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

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

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.cursor.TableCursor;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;

public class Find {

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

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

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

Use sorting to find rows

You can use a sort clause to sort rows by one or more columns.

For best performance, only sort on columns that are indexed or that are part of the primary key.

For more information, see Sort clauses for tables.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.constants import SortMode

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

# Find rows
cursor = table.find(
    {"isCheckedOut": 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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

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

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

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.tables.definition.rows.Row;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.cursor.TableCursor;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;

public class Find {

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

        // Find rows
        Filter filter = Filters.eq("isCheckedOut", false);
        TableFindOptions options = new TableFindOptions()
            .sort(Sort.ascending("rating"))
            .sort(Sort.descending("title"));
        TableCursor<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 "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": { "isCheckedOut": false },
    "sort": {
      "rating": 1,
      "title": -1
    }
  }
}'

Use an empty filter to find all rows

To find all rows, use an empty filter.

Avoid this if you have a large number of rows.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

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

# Find rows
cursor = table.find({})

# 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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

(async function () {
  // Find rows
  const cursor = table.find({});

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.cursor.TableCursor;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;

public class Find {

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

        // Find rows
        Filter filter = new Filter();
        TableFindOptions options = new TableFindOptions();

        TableCursor<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 "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": {}
  }
}'

Include the similarity score with the result

If you use a vector search to find rows, you can also include a $similarity property in the result. The $similarity value represents the closeness of the sort vector and the value of the row’s vector column.

  • Python

  • TypeScript

  • Java

  • curl

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

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

# 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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

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

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.cursor.TableCursor;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;

public class Find {

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

        // Find rows
        TableFindOptions options = new TableFindOptions()
            .sort(Sort.vectorize("summaryGenresVector", "Text to vectorize"))
            .includeSimilarity(true);
        TableCursor<Row, Row> cursor = table.find(options);
        // Iterate over the found rows
        for (Row row : cursor) {
            System.out.println(row);
        }
    }
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "sort": { "summaryGenresVector": "Text to vectorize" },
    "options": { "includeSimilarity": true }
  }
}'

Include only specific columns in the response

To specify which columns to include or exclude in the returned row, use a projection.

The following example demonstrates an inclusive projection.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

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

# Find rows
cursor = table.find(
    {"numberOfPages": {"$lt": 300}},
    projection={"isCheckedOut": True, "title": True}
)

# 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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

(async function () {
  // Find rows
  const cursor = table.find(
    { numberOfPages: { $lt: 300 } },
    { projection: { isCheckedOut: true, title: true} },
  );

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

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.Projection;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.cursor.TableCursor;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;

public class Find {

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

        // Find rows
        Filter filter = Filters.lt("numberOfPages", 300);
        TableFindOptions options = new TableFindOptions()
            .projection(Projection.include("isCheckedOut", "title"));
        TableCursor<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 "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": {"numberOfPages": {"$lt": 300}},
    "projection": {"isCheckedOut": true, "title": true}
  }
}'

Exclude specific columns from the response

To specify which columns to include or exclude in the returned row, use a projection.

The following example demonstrates an exclusive projection.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

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

# Find rows
cursor = table.find(
    {"numberOfPages": {"$lt": 300}},
    projection={"isCheckedOut": False, "title": False}
)

# 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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

(async function () {
  // Find rows
  const cursor = table.find(
    { numberOfPages: { $lt: 300 } },
    { projection: { isCheckedOut: false, title: false} },
  );

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

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.Projection;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.cursor.TableCursor;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;

public class Find {

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

        // Find rows
        Filter filter = Filters.lt("numberOfPages", 300);
        TableFindOptions options = new TableFindOptions()
            .projection(Projection.exclude("isCheckedOut", "title"));
        TableCursor<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 "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": {"numberOfPages": {"$lt": 300}},
    "projection": {"isCheckedOut": false, "title": false}
  }
}'

Limit the number of rows returned

Specify a limit to only fetch up to a certain number of rows.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

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

# Find rows
cursor = table.find(
    {
        "$and": [
            {"isCheckedOut": False},
            {"numberOfPages": {"$lt": 300}},
        ]
    },
    limit=10
)

# 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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

(async function () {
  // Find rows
  const cursor = table.find(
    {
      $and: [{ isCheckedOut: false }, { numberOfPages: { $lt: 300 } }],
    },
    { limit: 10 },
  );

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

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.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.cursor.TableCursor;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;

public class Find {

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

        // Find rows
        Filter filter = Filters.and(
          Filters.eq("isCheckedOut", false),
          Filters.lt("numberOfPages", 300));
        TableFindOptions options = new TableFindOptions()
            .limit(10);
        TableCursor<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 "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": {"$and": [
      {"isCheckedOut": false},
      {"numberOfPages": {"$lt": 300}}
    ]},
    "options": {
      "limit": 10
    }
  }
}'

Skip rows

You can specify a number of rows to skip (bypass) before returning rows.

You can only do this if your find explicitly includes an ascending or descending sort criterion. You cannot do this in conjunction with vector search.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.constants import SortMode

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

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

# 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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

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

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

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.tables.definition.rows.Row;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.cursor.TableCursor;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;

public class Find {

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

        // Find rows
        Filter filter = Filters.eq("isCheckedOut", false);
        TableFindOptions options = new TableFindOptions()
            .sort(Sort.ascending("rating"))
            .sort(Sort.descending("title"))
            .skip(5);
        TableCursor<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 "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": { "isCheckedOut": false },
    "sort": {
      "rating": 1,
      "title": -1
    },
    "options": {
      "skip": 5
    }
  }
}'

Use filter, sort, and projection together

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.constants import SortMode

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

# Find rows
cursor = table.find(
    {
        "$and": [
            {"isCheckedOut": False},
            {"numberOfPages": {"$lt": 300}},
        ]
    },
    sort={
        "rating": SortMode.ASCENDING,
        "title": SortMode.DESCENDING,
    },
    projection={"isCheckedOut": True, "title": True}
)

# 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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');

(async function () {
  // Find rows
  const cursor = table.find(
    {
      $and: [{ isCheckedOut: false }, { numberOfPages: { $lt: 300 } }],
    },
    {
      sort: {
        rating: 1, // ascending
        title: -1, // descending
      },
      projection: {
        isCheckedOut: true,
        title: true,
      },
    },
  );

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();
package com.example;

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.Projection;
import com.datastax.astra.client.tables.definition.rows.Row;
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.TableCursor;

public class Find {

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

        // Find rows
        Filter filter = Filters.and(
          Filters.eq("isCheckedOut", false),
          Filters.lt("numberOfPages", 300));
        TableFindOptions options = new TableFindOptions()
            .sort(Sort.ascending("rating"))
            .sort(Sort.descending("title"))
            .projection(Projection.include("isCheckedOut", "title"));
        TableCursor<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 "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": {"$and": [
      {"isCheckedOut": false},
      {"numberOfPages": {"$lt": 300}}
    ]},
    "sort": {
      "rating": 1,
      "title": -1
    },
    "projection": {"isCheckedOut": true, "title": true}
  }
}'

Iterate over found rows

  • Python

  • TypeScript

  • Java

  • curl

Use a for loop to iterate over the cursor. The client will periodically fetch more rows until no matching rows remain.

from astrapy import DataAPIClient

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

# Find rows
cursor = table.find(
  {
    "$and": [
      {"isCheckedOut": False},
      {"numberOfPages": {"$lt": 300}},
    ]
})

# Iterate over the found rows
for row in cursor:
    print(row)

The cursor returned by find() is compatible with for loops and next(). The client will periodically fetch more documents until no matching documents remain.

import { DataAPIClient } from '@datastax/astra-db-ts';

// Get an existing table
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const table = database.table('TABLE_NAME');


(async function () {
  // Find rows
  const cursor = table.find({
    $and: [{ isCheckedOut: false }, { numberOfPages: { $lt: 300 } }],
  });

  // Get the next item in the cursor
  console.log(await cursor.next());

  // Iterate over the found rows
  for await (const row of cursor) {
    console.log(row);
  }
})();

The cursor returned by find() is an Iterable and is compatible with for loops. The client will periodically fetch more documents until no matching documents remain.

package com.example;

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.tables.definition.rows.Row;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;
import com.datastax.astra.client.tables.cursor.TableCursor;

public class Find {

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

        // Find rows
        Filter filter = Filters.and(
          Filters.eq("isCheckedOut", false),
          Filters.lt("numberOfPages", 300));

        TableFindOptions options = new TableFindOptions();

        TableCursor<Row, Row> cursor = table.find(filter, options);

        // Iterate over the found rows
        for (Row row : cursor) {
            System.out.println(row);
        }
    }
}

If the response includes a non-null nextPageState, then the specified sort or filter operation supports pagination, and more documents than the ones already returned exist.

To fetch additional documents, you must send a request with the nextPageState value from your previous request. For example:

  1. Send an initial request

    curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": {"isCheckedOut": false}
  }
}'

  2. Get the data.documents.nextPageState value from the response

    {
  "data": {
    "documents": [
      {
        "_id": { "$uuid": "018e65c9-df45-7913-89f8-175f28bd7f74" }
      },
      {
        "_id": { "$uuid": "018e65c9-e33d-749b-9386-e848739582f0" }
      }
    ],
    "nextPageState": "NEXT_PAGE_STATE"
  }
}

  3. Use the data.documents.nextPageState from the previous response to request the next page of results.

    curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": {"isCheckedOut": false},
    "options": {
      "pageState": "NEXT_PAGE_STATE_FROM_PRIOR_RESPONSE"
    }
  }
}'

  4. Once nextPageState is null, you have fetched all matching documents.

    {
  "data": {
    "documents": [
      {
        "_id": { "$uuid": "018e65c9-df45-7913-89f8-175f28bd7f74" }
      },
      {
        "_id": { "$uuid": "018e65c9-e33d-749b-9386-e848739582f0" }
      }
    ],
    "nextPageState": null
  }
}

Client reference

  • Python

  • TypeScript

  • Java

  • curl

For more information, see the client reference.

For more information, see the client reference.

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

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