Find rows

Finds rows in a table using filter and sort clauses, including vector search.

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

Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart.

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, 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<Schema>) 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, 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 (TableFindCursor<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, 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, 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, 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",
        "is_checked_out":false
      },
      {
        "_id":"aa762475-4fc1-4477-b624-754fc1f477c7",
        "title":"Beyond Dreams and Forgotten Worlds",
        "is_checked_out":false
      }
    ],
    "nextPageState":"LQAAAAEBAAAAJGQ2OTk5NzY2LTgyODQtNDc3Mi05OTk3LTY2ODI4NGU3NzJjYQDwf///6wA="
  }
}

Example response if no rows were found:

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

Parameters

  • Python

  • TypeScript

  • Java

  • curl

Use the find method, which belongs to the astrapy.Table class.

Method signature 
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],
  initial_page_state: str,
  request_timeout_ms: int,
  timeout_ms: int,
) -> TableFindCursor

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

Filtering on non-indexed columns is inefficient and resource-intensive, especially for large datasets. With the Data API clients, such operations can hit the client timeout limit before the underlying HTTP operation is complete. If you filter on non-indexed columns, the Data API will give a warning.

An empty filter or omitted filter may also result in 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[str, Any]

Optional. An object that defines filter criteria using the Data API filter syntax. The method only finds rows that match the filter criteria.

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

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

Default: No filter

See Use filters to find rows for an example.

sort

Dict[str, Any]

Optional. Sorts rows by one or more columns, or performs a vector search.

For more information, see Sort clauses for tables.

See Use sorting to find rows, Use vector search with a search vector to find rows, and Use vector search with a search string to find rows for examples.

projection

Dict[str, bool]

Optional. Controls which columns are included or excluded in the returned rows.

For more information, see Projections for tables.

DataStax recommends a projection to avoid unnecessarily returning large columns, such as vector columns with highly dimensional embeddings.

Default: All columns

See Include only specific columns in the response and Exclude specific columns from the response for examples.

row_type

type

Optional. A formal specifier for the type checker.

This parameter is useful if your code is strictly typed and you use a projection.

For more information, see Typing support.

Default: The same type as the rows in the table. If you didn’t specify this when you instantiated the Table object, the row type defaulted to dict.

skip

int

Optional. The number of rows to bypass (skip) before returning rows.

The API excludes the first n rows matching the query, and the results begin at the n+1 row.

This parameter only applies if you also explicitly specify an ascending or descending sort criterion. This parameter is not valid with vector search.

limit

int

Optional. Limit the total number of rows returned. Once limit is reached, or the cursor is exhausted due to lack of matching rows, nothing more is returned.

For vector search, a lower limit reduces the accuracy of the search and the time required for the search.

include_similarity

bool

Optional. Whether to include a $similarity property in the response. The $similarity value represents the closeness of the sort vector and the row’s vector.

This parameter only applies if you use a vector search.

Default: false

See Include the similarity score with the result for an example.

include_sort_vector

bool

Optional. Whether to include the sort vector in the response.

This can be useful if you do a vector search with $vectorize, since you don’t know the sort vector in advance.

Because vector search is approximate, setting a lower limit increases the chance of finding a close match, but not necessarily the best match.

This parameter only applies if you use a vector search.

Default: false

initial_page_state

str

Optional. The next_page_state value from the response of fetch_next_page() called on a previous cursor. You cannot pass None, which is the value of next_page_state when no pages remain.

Used to manually request the next page of results. This is useful for cases where an external action triggers fetching the next page of results.

For usage, see Iterate over found rows.

request_timeout_ms

int

Optional. The maximum time, in milliseconds, that the client should wait for the underlying HTTP request.

This parameter is aliased as request_timeout_ms and timeout_ms for convenience.

Default: The default value for the table. This default is 30 seconds unless you specified a different default when you initialized the Table or DataAPIClient object. For more information, see Timeout options.

Use the find method, which belongs to the Table class.

Method signature 
find(
  filter: TableFilter<Schema>,
  options?: {
    sort?: Sort,
    projection?: Projection,
    limit?: number,
    skip?: number
    includeSimilarity?: boolean,
    includeSortVector?: boolean,
    initialPageState?: string,
    timeout?: number | TimeoutDescriptor,
  }
): TableFindCursor<Schema, Schema> | null

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

Filtering on non-indexed columns is inefficient and resource-intensive, especially for large datasets. With the Data API clients, such operations can hit the client timeout limit before the underlying HTTP operation is complete. If you filter on non-indexed columns, the Data API will give a warning.

An empty filter or omitted filter may also result in 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

Optional. An object that defines filter criteria using the Data API filter syntax. The method only finds rows that match the filter criteria.

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

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

Default: No filter

See Use filters to find rows for an example.

options

TableFindOptions

Optional. The options for this operation. See Properties of options for more details.
Properties of options
Name Type Summary

sort

Sort

Optional. Sorts rows by one or more columns, or performs a vector search.

For more information, see Sort clauses for tables.

See Use sorting to find rows, Use vector search with a search vector to find rows, and Use vector search with a search string to find rows for examples.

projection

Projection

Optional. Controls which columns are included or excluded in the returned rows.

For more information, see Projections for tables.

DataStax recommends a projection to avoid unnecessarily returning large columns, such as vector columns with highly dimensional embeddings.

Default: All columns

See Include only specific columns in the response and Exclude specific columns from the response for examples.

skip

number

Optional. The number of rows to bypass (skip) before returning rows.

The API excludes the first n rows matching the query, and the results begin at the n+1 row.

This parameter only applies if you also explicitly specify an ascending or descending sort criterion. This parameter is not valid with vector search.

limit

number

Optional. Limit the total number of rows returned. Once limit is reached, or the cursor is exhausted due to lack of matching rows, nothing more is returned.

For vector search, a lower limit reduces the accuracy of the search and the time required for the search.

includeSimilarity

boolean

Optional. Whether to include a $similarity property in the response. The $similarity value represents the closeness of the sort vector and the row’s vector.

This parameter only applies if you use a vector search.

Default: false

If you use a projection and you set the includeSimlarity parameter to true for a vector search, you must manually include $similarity in the type of the returned rows.

See Include the similarity score with the result for an example.

includeSortVector

boolean

Optional. Whether to include the sort vector in the response.

This can be useful if you do a vector search with $vectorize, since you don’t know the sort vector in advance.

Because vector search is approximate, setting a lower limit increases the chance of finding a close match, but not necessarily the best match.

This parameter only applies if you use a vector search.

Default: false

initialPageState

string

Optional. The nextPageState value from the response of fetchNextPage() called on a previous cursor.

Used to manually request the next page of results. This is useful for cases where an external action triggers fetching the next page of results.

For usage, see Iterate over found rows.

timeout

number | TimeoutDescriptor

Optional. The timeout to apply to this method.

Use the find method, which belongs to the com.datastax.astra.client.tables.Table class.

Method signature 
TableFindCursor<T, T> find(
  Filter filter,
  TableFindOptions options
)
TableFindCursor<T, T> find(
  Filter filter
)
TableFindCursor<T, T> find(
  TableFindOptions options
)
<R> TableFindCursor<T, R> find(
  Filter filter,
  TableFindOptions options,
  Class<R> rowClass
)

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

Filtering on non-indexed columns is inefficient and resource-intensive, especially for large datasets. With the Data API clients, such operations can hit the client timeout limit before the underlying HTTP operation is complete. If you filter on non-indexed columns, the Data API will give a warning.

An empty filter or omitted filter may also result in 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

Optional. An object that defines filter criteria using the Data API filter syntax. The method only finds rows that match the filter criteria.

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

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

Default: No filter

See Use filters to find rows for an example.

rowClass

Class<?>

Optional. A specification of the class of the returned row object.

This parameter is useful if your code is strictly typed and you use a projection.

Default: The same class as the rows in the table. If you didn’t specify this when you instantiated the Table object, the row type defaulted to Row, which is close to a Map object.

options

TableFindOptions

Optional. The options for this operation. See Methods of the TableFindOneOptions class for more details.
Methods of the TableFindOneOptions class
Method Parameters Summary

sort()

Sort

Optional. Sorts rows by one or more columns, or performs a vector search.

For more information, see Sort clauses for tables.

See Use sorting to find rows, Use vector search with a search vector to find rows, and Use vector search with a search string to find rows for examples.

projection()

Projection

Optional. Controls which columns are included or excluded in the returned rows.

For more information, see Projections for tables.

DataStax recommends a projection to avoid unnecessarily returning large columns, such as vector columns with highly dimensional embeddings.

Default: All columns

See Include only specific columns in the response and Exclude specific columns from the response for examples.

includeSimilarity()

boolean

Optional. Whether to include a $similarity property in the response. The $similarity value represents the closeness of the sort vector and the row’s vector.

This parameter only applies if you use a vector search.

Default: false

See Include the similarity score with the result for an example.

includeSortVector()

boolean

Optional. Whether to include the sort vector in the response.

This can be useful if you do a vector search with $vectorize, since you don’t know the sort vector in advance.

Because vector search is approximate, setting a lower limit increases the chance of finding a close match, but not necessarily the best match.

This parameter only applies if you use a vector search.

Default: false

skip()

int

Optional. The number of rows to bypass (skip) before returning rows.

The API excludes the first n rows matching the query, and the results begin at the n+1 row.

This parameter only applies if you also explicitly specify an ascending or descending sort criterion. This parameter is not valid with vector search.

limit

int

Optional. Limit the total number of rows returned. Once limit is reached, or the cursor is exhausted due to lack of matching rows, nothing more is returned.

For vector search, a lower limit reduces the accuracy of the search and the time required for the search.

timeout()

long | Duration

Optional. The timeout(s) to apply to HTTP request(s) originating from this method.

Default: The default value for the table. This default is 30 seconds unless you specified a different default when you initialized the Table or DataAPIClient object.

Use the find command.

Command signature 
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": FILTER,
    "sort": SORT,
    "projection": PROJECTION,
    "options": {
      "includeSimilarity": BOOLEAN,
      "includeSortVector": BOOLEAN,
      "skip": INTEGER,
      "limit": INTEGER
    }
  }
}'

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

Filtering on non-indexed columns is inefficient and resource-intensive, especially for large datasets. With the Data API clients, such operations can hit the client timeout limit before the underlying HTTP operation is complete. If you filter on non-indexed columns, the Data API will give a warning.

An empty filter or omitted filter may also result in 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

object

Optional. An object that defines filter criteria using the Data API filter syntax. The method only finds rows that match the filter criteria.

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

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

Default: No filter

See Use filters to find rows for an example.

sort

object

Optional. Sorts rows by one or more columns, or performs a vector search.

For more information, see Sort clauses for tables.

See Use sorting to find rows, Use vector search with a search vector to find rows, and Use vector search with a search string to find rows for examples.

projection

object

Optional. Controls which columns are included or excluded in the returned rows.

For more information, see Projections for tables.

DataStax recommends a projection to avoid unnecessarily returning large columns, such as vector columns with highly dimensional embeddings.

Default: All columns

See Include only specific columns in the response and Exclude specific columns from the response for examples.

skip

integer

Optional. The number of rows to bypass (skip) before returning rows.

The API excludes the first n rows matching the query, and the results begin at the n+1 row.

This parameter only applies if you also explicitly specify an ascending or descending sort criterion. This parameter is not valid with vector search.

limit

integer

Optional. Limit the total number of rows returned.

Pagination can occur if more that 20 rows are found.

Once the limit is reached, either in a single response or the last page of a paginated response, nothing more is returned.

For vector search, a lower limit reduces the accuracy of the search and the time required for the search.

options.includeSimilarity

boolean

Optional. Whether to include a $similarity property in the response. The $similarity value represents the closeness of the sort vector and the row’s vector.

This parameter only applies if you use a vector search.

Default: false

See Include the similarity score with the result for an example.

options.includeSortVector

boolean

Optional. Whether to include the sort vector in the response.

This can be useful if you do a vector search with $vectorize, since you don’t know the sort vector in advance.

Because vector search is approximate, setting a lower limit increases the chance of finding a close match, but not necessarily the best match.

This parameter only applies if you use a vector search.

Default: false

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 is_checked_out value of false and a number_of_pages 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.

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("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Find rows
cursor = table.find(
    {
        "$and": [
            {"is_checked_out": False},
            {"number_of_pages": {"$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("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

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

  // 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.tables.Table;
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.and(Filters.eq("is_checked_out", false), Filters.lt("number_of_pages", 300));

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

    // 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": {"$and": [
      {"is_checked_out": false},
      {"number_of_pages": {"$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("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"} }
  }
}'

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("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" }
  }
}'

Use lexicographical matching to find rows

Hybrid search, lexical search, and reranking are 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.

There are two ways to use lexicographical matching to find rows with the Data API:

  • Sort to find rows with a text or ascii column value that is most relevant to a given string of space-separated keywords or terms.

  • Filter with the $match operator to find rows with a text or ascii column value that is a lexicographical match to the specified string of space-separated keywords or terms

You can use these strategies together or separately.

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 and Indexes in tables.

  • 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(
    {"summary": {"$match": "futuristic laboratory discovery"}},
    sort={"summary": "futuristic laboratory"},
)

# 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(
    { summary: { $match: "futuristic laboratory discovery" } },
    {
      sort: {
        summary: "futuristic laboratory",
      },
    },
  );

  // 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.match("summary", "futuristic laboratory discovery");
    TableFindOptions options =
        new TableFindOptions().sort(Sort.lexical("summary", "futuristic laboratory"));

    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": {
      "summary": {"$match": "futuristic laboratory discovery"}
    },
    "sort": { 
      "summary": "futuristic laboratory"
    }
  }
}'

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("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
    }
  }
}'

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("APPLICATION_TOKEN")
database = client.get_database("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("APPLICATION_TOKEN");
const database = client.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);
  }
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.tables.Table;
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 = new Filter();

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

    // 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": {}
  }
}'

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

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"}, 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("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" },
      includeSimilarity: true,
    },
  );

  // 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"))
            .includeSimilarity(true);
    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" },
    "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("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Find rows
cursor = table.find(
    {"number_of_pages": {"$lt": 300}},
    projection={"is_checked_out": 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("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

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

  // 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.Projection;
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.lt("number_of_pages", 300);
    TableFindOptions options =
        new TableFindOptions().projection(Projection.include("is_checked_out", "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": {"number_of_pages": {"$lt": 300}},
    "projection": {"is_checked_out": 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("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Find rows
cursor = table.find(
    {"number_of_pages": {"$lt": 300}},
    projection={"is_checked_out": 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("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

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

  // 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.Projection;
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.lt("number_of_pages", 300);
    TableFindOptions options =
        new TableFindOptions().projection(Projection.exclude("is_checked_out", "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": {"number_of_pages": {"$lt": 300}},
    "projection": {"is_checked_out": 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("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Find rows
cursor = table.find(
    {
        "$and": [
            {"is_checked_out": False},
            {"number_of_pages": {"$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("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

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

  // 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.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.and(Filters.eq("is_checked_out", false), Filters.lt("number_of_pages", 300));
    TableFindOptions options = new TableFindOptions().limit(10);
    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": {"$and": [
      {"is_checked_out": false},
      {"number_of_pages": {"$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("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,
    },
    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("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
      },
      skip: 5,
    },
  );

  // 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")).skip(5);
    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
    },
    "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("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

# Find rows
cursor = table.find(
    {
        "$and": [
            {"is_checked_out": False},
            {"number_of_pages": {"$lt": 300}},
        ]
    },
    sort={
        "rating": SortMode.ASCENDING,
        "title": SortMode.DESCENDING,
    },
    projection={"is_checked_out": 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("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const table = database.table("TABLE_NAME");

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

  // 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.Projection;
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.and(Filters.eq("is_checked_out", false), Filters.lt("number_of_pages", 300));
    TableFindOptions options =
        new TableFindOptions()
            .sort(Sort.ascending("rating"), Sort.descending("title"))
            .projection(Projection.include("is_checked_out", "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": {"$and": [
      {"is_checked_out": false},
      {"number_of_pages": {"$lt": 300}}
    ]},
    "sort": {
      "rating": 1,
      "title": -1
    },
    "projection": {"is_checked_out": 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("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
table = database.get_table("TABLE_NAME")

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

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

Alternatively, you can use the initial_page_state parameter to fetch a specific page of results. This is useful for cases where an external action triggers fetching the next page of results. For example, you might use this feature if you implement an infinite scroll interface or a button to load more results.

from astrapy import DataAPIClient

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

# Create the filter
filter = {
    "$and": [
        {"is_checked_out": False},
        {"number_of_pages": {"$lt": 300}},
    ]
}

# Get the first page
cursor_1 = table.find(filter)
page_1 = cursor_1.fetch_next_page()
results_1 = page_1.results
for row in results_1:
    print(row)
pagination_state_1 = page_1.next_page_state

# Get the next page
if pagination_state_1:
    cursor_2 = table.find(filter, initial_page_state=pagination_state_1)
    page_2 = cursor_2.fetch_next_page()
    results_2 = page_2.results
    for row in results_2:
        print(row)
    pagination_state_2 = page_2.next_page_state

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

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({
    $and: [{ is_checked_out: false }, { number_of_pages: { $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);
  }
})();

Alternatively, you can use the initialPageState parameter to fetch a specific page of results. This is useful for cases where an external action triggers fetching the next page of results. For example, you might use this feature if you implement a "Load More" button or an infinite scroll interface.

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");

// Create the filter
const filter = {
  $and: [{ is_checked_out: false }, { number_of_pages: { $lt: 300 } }],
};

(async function () {
  // Get the first page
  const cursor1 = table.find(filter);
  const page1 = await cursor1.fetchNextPage();
  const results1 = page1.result;
  for (const row of results1) {
    console.log(row);
  }
  const paginationState1 = page1.nextPageState;

  // Get the next page
  if (paginationState1) {
    const cursor2 = table.find(filter, { initialPageState: paginationState1 });
    const page2 = await cursor2.fetchNextPage();
    const results2 = page2.result;
    for (const row of results2) {
      console.log(row);
    }
    const paginationState2 = page2.nextPageState;
  }
})();

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

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.Table;
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.and(Filters.eq("is_checked_out", false), Filters.lt("number_of_pages", 300));

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

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

Alternatively, you can use the findPage method to fetch a specific page of results. This is useful for cases where an external action triggers fetching the next page of results. For example, you might use this feature if you implement a "Load More" button or an infinite scroll interface.

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.paging.Page;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOptions;
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");

    // Create the filter
    Filter filter =
        Filters.and(Filters.eq("is_checked_out", false), Filters.lt("number_of_pages", 300));

    // Get the first page
    Page<Row> page1 = table.findPage(filter, null);
    page1.getResults().forEach(System.out::println);
    String paginationState1 = page1.getPageState().orElse(null);

    // Get the next page
    if (paginationState1 != null) {
      Page<Row> page2 = table.findPage(filter, new TableFindOptions().pageState(paginationState1));
      page2.getResults().forEach(System.out::println);
    }
  }
}

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

To fetch additional rows, 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 "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}
  }
}'

  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 "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},
    "options": {
      "pageState": "NEXT_PAGE_STATE_FROM_PRIOR_RESPONSE"
    }
  }
}'

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

    {
  "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, an IBM Company | 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