Find a row
Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Hyper-Converged Database (HCD), and the use of such, is subject to the DataStax Preview Terms. |
Finds a single row 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 dictionary representation of a row that matches the specified filter and sort clauses, or returns None
if no row was found.
The columns included in the returned row depend on the subset of columns that were requested in the projection.
If requested and applicable, the 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.
Returns a promise that resolves to a row that matches the specified filter and sort clauses (Schema
), or to null
if no row was found.
The columns included in the returned row depend on the subset of columns that were requested in the projection.
If requested and applicable, the 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.
Returns a row that matches the specified filter and sort clauses (Optional<R>
), or returns Optional.empty()
if no row was found.
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 row depend on the subset of columns that were requested in the projection.
If requested and applicable, the 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.
Returns a dictionary representation of a row that matches the specified filter and sort clauses, or returns null
if no row was found.
The columns included in the returned row depend on the subset of columns that were requested in the projection.
If requested and applicable, the 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.
The response omits any columns with null
values, regardless of the projection.
Example response:
{
"data": {
"document": {
"_id": 101,
"name": "John Doe",
"$vector": [0.12, 0.52, 0.32]
}
}
}
Example null response:
{
"data": {
"document": null
}
}
Parameters
-
Python
-
TypeScript
-
Java
-
curl
Use the find_one
method, which belongs to the astrapy.Table
class.
Method signature
find_one(
filter: Dict[str, Any],
*,
projection: Iterable[str] | Dict[str, bool],
include_similarity: bool,
sort: Dict[str, Any],
general_method_timeout_ms: int,
request_timeout_ms: int,
timeout_ms: int,
) -> Dict[str, Any] | None
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 |
---|---|---|
|
|
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 Default: No filter See Use filters to find a row for an example. |
|
|
Optional. Sorts rows by one or more columns, or performs a vector search. For more information, see Sort clauses for tables. |
|
|
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 Default: All columns See Include only specific columns in the response and Exclude specific columns from the response for examples. |
|
|
Optional.
Whether to include a This parameter only applies if you use a vector search. Default: false See Include the similarity score with the result for an example. |
|
|
Optional. The maximum time, in milliseconds, that the client should wait for the underlying HTTP request. This parameter is aliased as Default: The default value for the table. This default is 30 seconds unless you specified a different default when you initialized the |
Use the findOne
method, which belongs to the Table
class.
Method signature
async findOne(
filter: TableFilter<Schema>,
options?: {
sort?: Sort,
projection?: Projection,
includeSimilarity?: boolean,
timeout?: number | TimeoutDescriptor,
},
): 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 |
---|---|---|
|
|
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 Default: No filter See Use filters to find a row for an example. |
|
|
Optional.
The options for this operation. See Properties of |
Name | Type | Summary |
---|---|---|
|
|
Optional. Sorts rows by one or more columns, or performs a vector search. For more information, see Sort clauses for tables. |
|
|
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 Default: All columns See Include only specific columns in the response and Exclude specific columns from the response for examples. |
|
|
Optional.
Whether to include a This parameter only applies if you use a vector search. Default: false If you use a projection and you set the See Include the similarity score with the result for an example. |
|
|
Optional. The timeout to apply to this method. |
Use the findOne
method, which belongs to the com.datastax.astra.client.tables.Table
class.
Method signature
Optional<T> findOne(
Filter filter
)
Optional<T> findOne(
TableFindOneOptions options
)
Optional<T> findOne(
Filter filter,
TableFindOneOptions options
)
<R> Optional<R> findOne(
Filter filter,
Class<R> rowClass
)
<R> Optional<R> findOne(
Filter filter,
TableFindOneOptions 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 |
---|---|---|
|
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 Default: No filter See Use filters to find a row for an example. |
|
|
|
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 |
|
Optional.
The options for this operation. See Methods of the |
Method | Parameters | Summary |
---|---|---|
|
Optional. Sorts rows by one or more columns, or performs a vector search. For more information, see Sort clauses for tables. |
|
|
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 Default: All columns See Include only specific columns in the response and Exclude specific columns from the response for examples. |
|
|
|
Optional.
Whether to include a This parameter only applies if you use a vector search. Default: false See Include the similarity score with the result for an example. |
|
|
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 |
Use the findOne
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 '{
"findOne": {
"filter": FILTER,
"sort": SORT,
"projection": PROJECTION,
"options": {
"includeSimilarity": BOOLEAN
}
}
}'
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 |
---|---|---|
|
|
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 Default: No filter See Use filters to find a row for an example. |
|
|
Optional. Sorts rows by one or more columns, or performs a vector search. For more information, see Sort clauses for tables. |
|
|
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 Default: All columns See Include only specific columns in the response and Exclude specific columns from the response for examples. |
|
|
Optional.
Whether to include a This parameter only applies if you use a vector search. If you use a projection and you set the Default: false See Include the similarity score with the result for an example. |
Examples
The following examples demonstrate how to find a row in a table.
Use filters to find a row
You can use a filter to find a row that matches specific criteria.
For example, you can find a row with an is_checked_out
value of false
and a number_of_pages
value less than 300.
For optimal performance, 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
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
table = database.get_table("TABLE_NAME", keyspace="KEYSPACE_NAME")
# Find a row
result = table.find_one(
{
"$and": [
{"is_checked_out": False},
{"number_of_pages": {"$lt": 300}},
]
}
)
print(result)
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const table = database.table("TABLE_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Find a row
(async function () {
const result = await table.findOne({
$and: [{ is_checked_out: false }, { number_of_pages: { $lt: 300 } }],
});
console.log(result);
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;
public class Example {
public static void main(String[] args) {
// Get an existing table
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
Table<Row> table = database.getTable("TABLE_NAME");
// Find a row
Filter filter =
Filters.and(Filters.eq("is_checked_out", false), Filters.lt("number_of_pages", 300));
Optional<Row> result = table.findOne(filter);
System.out.println(result);
}
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"findOne": {
"filter": {"$and": [
{"is_checked_out": false},
{"number_of_pages": {"$lt": 300}}
]}
}
}'
Use vector search with a search vector to find a row
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
You can use the astrapy.data_types.DataAPIVector
class to binary-encode your search vector.
DataStax recommends that you always use a DataAPIVector
object instead of a list of floats to improve performance.
When you read the value of a vector column, the client always returns a DataAPIVector
object, unless you change the default serialization/deserialization behavior.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.data_types import DataAPIVector
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
table = database.get_table("TABLE_NAME", keyspace="KEYSPACE_NAME")
# Find a row
result = table.find_one(
{}, sort={"summary_genres_vector": DataAPIVector([0.12, -0.46, 0.35, 0.52, -0.32])}
)
print(result)
You can use the DataAPIVector
class to binary-encode your search vector.
DataStax recommends that you always use a DataAPIVector
object instead of a list of floats to improve performance.
When you read the value of a vector column, the client always returns a DataAPIVector
object, unless you change the default serialization/deserialization behavior.
You can use vector.asArray()
to lazily convert a DataAPIVector
object to an array.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const table = database.table("TABLE_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Find a row
(async function () {
const result = await table.findOne(
{},
{ sort: { summary_genres_vector: [0.12, -0.46, 0.35, 0.52, -0.32] } },
);
console.log(result);
})();
You can use the DataAPIVector
class to binary-encode your search vector.
DataStax recommends that you always use a DataAPIVector
object instead of a list of floats to improve performance.
When you read the value of a vector column, the client always returns a DataAPIVector
object, unless you change the default serialization/deserialization behavior.
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.core.vector.DataAPIVector;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;
public class Example {
public static void main(String[] args) {
// Get an existing table
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
Table<Row> table = database.getTable("TABLE_NAME");
// Find a row
TableFindOneOptions options =
new TableFindOneOptions()
.sort(
Sort.vector(
"summary_genres_vector",
new DataAPIVector(new float[] {0.12f, -0.46f, 0.35f, 0.52f, -0.32f})));
Optional<Row> result = table.findOne(options);
System.out.println(result);
}
}
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.
Vector binary encodings specification
A d-dimensional vector is a list of d floating-point numbers that can be binary encoded.
To prepare for encoding, the list must be transformed into a sequence of bytes where each float is represented as four bytes in big-endian format.
Then, the byte sequence is Base64-encoded, with =
padding, if needed.
For example, here are some vectors and their resulting Base64 encoded strings:
[0.1, -0.2, 0.3] = "PczMzb5MzM0+mZma" [0.1, 0.2] = "PczMzT5MzM0=" [10, 10.5, 100, -91.19] = "QSAAAEEoAABCyAAAwrZhSA=="
Once encoded, you use $binary
to pass the Base64 string to the Data API:
{ "$binary": "BASE64_STRING" }
You can use a script to encode your vectors, for example:
python
import base64
import struct
input_vector = [0.1, -0.2, 0.3]
d = len(input_vector)
pack_format = ">" + "f" * d
binary_encode = base64.b64encode(struct.pack(pack_format, *input_vector)).decode()
-
Array of floats
-
$binary
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"findOne": {
"sort": { "summary_genres_vector": {"$binary": "PfXCjz8FHrg+o9cK"} }
}
}'
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"findOne": {
"sort": { "summary_genres_vector": [0.12, -0.46, 0.35, 0.52, -0.32] }
}
}'
Use sorting to find a row
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.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.constants import SortMode
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
table = database.get_table("TABLE_NAME", keyspace="KEYSPACE_NAME")
# Find a row
result = table.find_one(
{"is_checked_out": False},
sort={
"rating": SortMode.ASCENDING,
"title": SortMode.DESCENDING,
},
)
print(result)
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const table = database.table("TABLE_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Find a row
(async function () {
const result = await table.findOne(
{ is_checked_out: false },
{
sort: {
rating: 1, // ascending
title: -1, // descending
},
},
);
console.log(result);
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
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.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;
public class Example {
public static void main(String[] args) {
// Get an existing table
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
Table<Row> table = database.getTable("TABLE_NAME");
// Find a row
Filter filter = Filters.eq("is_checked_out", false);
TableFindOneOptions options =
new TableFindOneOptions().sort(Sort.ascending("rating"), Sort.descending("title"));
Optional<Row> result = table.findOne(filter, options);
System.out.println(result);
}
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"findOne": {
"filter": { "is_checked_out": false },
"sort": {
"rating": 1,
"title": -1
}
}
}'
Include the similarity score with the result
If you use a vector search to find a row, 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
The client always returns the similarity score as a DataAPIVector
object, unless you change the default serialization/deserialization behavior.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
table = database.get_table("TABLE_NAME", keyspace="KEYSPACE_NAME")
# Find a row
result = table.find_one(
{},
sort={"summary_genres_vector": [0.12, -0.46, 0.35, 0.52, -0.32]},
include_similarity=True,
)
print(result)
The client always returns the similarity score as a DataAPIVector
object, unless you change the default serialization/deserialization behavior.
You can use vector.asArray()
to lazily convert a DataAPIVector
object to an array.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const table = database.table("TABLE_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Find a row
(async function () {
const result = await table.findOne(
{},
{
sort: { summary_genres_vector: [0.12, -0.46, 0.35, 0.52, -0.32] },
includeSimilarity: true,
},
);
console.log(result);
})();
The client always returns the similarity score as a DataAPIVector
object, unless you change the default serialization/deserialization behavior.
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.core.query.Sort;
import com.datastax.astra.client.core.vector.DataAPIVector;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;
public class Example {
public static void main(String[] args) {
// Get an existing table
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
Table<Row> table = database.getTable("TABLE_NAME");
// Find a row
TableFindOneOptions options =
new TableFindOneOptions()
.sort(
Sort.vector(
"summary_genres_vector",
new DataAPIVector(new float[] {0.12f, -0.46f, 0.35f, 0.52f, -0.32f})))
.includeSimilarity(true);
Optional<Row> result = table.findOne(options);
System.out.println(result);
}
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"findOne": {
"sort": { "summary_genres_vector": [0.12, -0.46, 0.35, 0.52, -0.32] },
"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
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
table = database.get_table("TABLE_NAME", keyspace="KEYSPACE_NAME")
# Find a row
result = table.find_one(
{"number_of_pages": {"$lt": 300}},
projection={"is_checked_out": True, "title": True},
)
print(result)
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const table = database.table("TABLE_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Find a row
(async function () {
const result = await table.findOne(
{ number_of_pages: { $lt: 300 } },
{ projection: { is_checked_out: true, title: true } },
);
console.log(result);
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
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.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;
public class Example {
public static void main(String[] args) {
// Get an existing table
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
Table<Row> table = database.getTable("TABLE_NAME");
// Find a row
Filter filter = Filters.lt("number_of_pages", 300);
TableFindOneOptions options =
new TableFindOneOptions().projection(Projection.include("is_checked_out", "title"));
Optional<Row> result = table.findOne(filter, options);
System.out.println(result);
}
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"findOne": {
"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
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
table = database.get_table("TABLE_NAME", keyspace="KEYSPACE_NAME")
# Find a row
result = table.find_one(
{"number_of_pages": {"$lt": 300}},
projection={"is_checked_out": False, "title": False},
)
print(result)
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const table = database.table("TABLE_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Find a row
(async function () {
const result = await table.findOne(
{ number_of_pages: { $lt: 300 } },
{ projection: { is_checked_out: false, title: false } },
);
console.log(result);
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
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.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;
public class Example {
public static void main(String[] args) {
// Get an existing table
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
Table<Row> table = database.getTable("TABLE_NAME");
// Find a row
Filter filter = Filters.lt("number_of_pages", 300);
TableFindOneOptions options =
new TableFindOneOptions().projection(Projection.exclude("is_checked_out", "title"));
Optional<Row> result = table.findOne(filter, options);
System.out.println(result);
}
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"findOne": {
"filter": {"number_of_pages": {"$lt": 300}},
"projection": {"is_checked_out": false, "title": false}
}
}'
Use filter, sort, and projection together
-
Python
-
TypeScript
-
Java
-
curl
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.constants import SortMode
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
table = database.get_table("TABLE_NAME", keyspace="KEYSPACE_NAME")
# Find a row
result = table.find_one(
{
"$and": [
{"is_checked_out": False},
{"number_of_pages": {"$lt": 300}},
]
},
sort={
"rating": SortMode.ASCENDING,
"title": SortMode.DESCENDING,
},
projection={"is_checked_out": True, "title": True},
)
print(result)
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const table = database.table("TABLE_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Find a row
(async function () {
const result = await table.findOne(
{
$and: [{ is_checked_out: false }, { number_of_pages: { $lt: 300 } }],
},
{
sort: {
rating: 1, // ascending
title: -1, // descending
},
projection: {
is_checked_out: true,
title: true,
},
},
);
console.log(result);
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
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.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.options.TableFindOneOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Optional;
public class Example {
public static void main(String[] args) {
// Get an existing table
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
Table<Row> table = database.getTable("TABLE_NAME");
// Find a row
Filter filter =
Filters.and(Filters.eq("is_checked_out", false), Filters.lt("number_of_pages", 300));
TableFindOneOptions options =
new TableFindOneOptions()
.sort(Sort.ascending("rating"), Sort.descending("title"))
.projection(Projection.include("is_checked_out", "title"));
Optional<Row> result = table.findOne(filter, options);
System.out.println(result);
}
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"findOne": {
"filter": {"$and": [
{"is_checked_out": false},
{"number_of_pages": {"$lt": 300}}
]},
"sort": {
"rating": 1,
"title": -1
},
"projection": {"is_checked_out": true, "title": true}
}
}'
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.