Instantiate a client object
All Data API interactions through a client start with a DataAPIClient object.
Once you have a DataAPIClient object, you can connect to a database and the perform CRUD operations on your data.
Creating a client object is an essential component of Data API client scripts. For more information, see Get started with the Data API.
For more information about the Data API client hierarchy, see Python client internals, TypeScript client internals, Go client internals, Java client internals, and C# client internals.
Result
-
Python
-
TypeScript
-
Go
-
Java
-
C#
Returns a DataAPIClient object that you can use to interact with the Data API.
Returns a DataAPIClient object that you can use to interact with the Data API.
|
The Go client is in preview. For more information, see astra-db-go. |
Returns a DataAPIClient struct that you can use to interact with the Data API.
Returns a DataAPIClient object that you can use to interact with the Data API.
Returns a DataAPIClient object that you can use to interact with the Data API.
Parameters
-
Python
-
TypeScript
-
Go
-
Java
-
C#
| Name | Type | Summary |
|---|---|---|
|
|
Optional.
An application token for a database, in the form of an The token should have sufficient permissions to perform the desired operations.
|
|
|
Optional. Specify the environment this client will work in. Must be one of the values in Default: |
|
|
Optional. Attaches special identifying entries to the User-Agent header for all HTTP requests issued to the Data API. The full type of this parameter is |
|
|
Optional. A complete or partial specification of the APIOptions for the client. This allows you to customize the client interaction with the Data API. For example, you can use this parameter to change the timeout settings. |
| Name | Type | Summary |
|---|---|---|
|
|
Optional.
An application token for a database.
Tokens are prefixed with The token should have sufficient permissions to perform the desired operations.
|
|
Optional.
The options to use for the client, including defaults.
See Properties of |
| Name | Type | Summary |
|---|---|---|
Optional. Specify the environment this client will work in. Can be one of: For more information, see the astra-db-ts README. Default: |
||
Optional. Options related to the API requests made by the client. The
For more information on http clients, see the astra-db-ts README and the client reference. |
||
Optional.
Specify default options for when spawning a |
||
Optional.
Specify default options for when spawning an |
|
The Go client is in preview. For more information, see astra-db-go. |
Use the NewClient method.
Method signature
func NewClient(
opts ...options.APIOption
) *DataAPIClient
| Name | Type | Summary |
|---|---|---|
|
Optional. A specification of options to override the inherited defaults. Use this to customize the interaction of the client with the admin object. For example, you can change the default timeouts or token. You can override these options later with See Methods of the |
| Method | Summary |
|---|---|
|
Optional.
An application token for a database, in the form of an The token should have sufficient permissions to perform the desired operations. |
|
Optional. Specify the environment this client will work in. Default: |
|
Optional. Sets the database backend. Default: |
|
Optional The keyspace to use for downstream operations. Default: default_keyspace |
|
Optional. Specifies headers for all HTTP requests to the Data API. |
|
Optional. Attaches special identifying entries to the User-Agent header for all HTTP requests to the Data API. |
|
Sets the Data API version. Default: v1 |
|
Optional. Sets the HTTP client to use for requests. |
|
Optional. Specifies a callback function that is invoked for warnings emitted by the Data API. Data API warnings indicate non-fatal conditions that don’t prevent the operation from completing, such as missing indexes or deprecated features. |
|
Optional. Sets the serialization/deserialization options. |
| Name | Type | Summary |
|---|---|---|
|
|
Optional.
An application token for a database, in the form of The token should have sufficient permissions to perform the desired operations.
|
|
A class wrapping the advanced configuration of the client, such as as |
| Name | Type | Summary |
|---|---|---|
|
|
Optional.
An application token for a database, in the form of The token should have sufficient permissions to perform the desired operations.
|
|
A class wrapping the advanced configuration of the client, such as |
Examples
The following examples demonstrate how to instantiate a client.
Instantiate a client
-
Python
-
TypeScript
-
Go
-
Java
-
C#
from astrapy import DataAPIClient
client = DataAPIClient()
import { DataAPIClient } from "@datastax/astra-db-ts";
const client = new DataAPIClient();
|
The Go client is in preview. For more information, see astra-db-go. |
package main
import (
"github.com/datastax/astra-db-go/v2/astra"
)
func main() {
_ = astra.NewClient()
}
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.options.DataAPIClientOptions;
public class Example {
public static void main(String[] args) {
DataAPIClient client = new DataAPIClient(new DataAPIClientOptions());
}
}
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
namespace Examples;
public class Program
{
static void Main()
{
var client = new DataAPIClient();
}
}
Instantiate a client and pass a token
-
Python
-
TypeScript
-
Go
-
Java
-
C#
from astrapy import DataAPIClient
client = DataAPIClient("APPLICATION_TOKEN")
import { DataAPIClient } from "@datastax/astra-db-ts";
const client = new DataAPIClient("APPLICATION_TOKEN");
|
The Go client is in preview. For more information, see astra-db-go. |
package main
import (
"github.com/datastax/astra-db-go/v2/astra"
"github.com/datastax/astra-db-go/v2/astra/options"
)
func main() {
_ = astra.NewClient(options.API().SetToken("APPLICATION_TOKEN"))
}
import com.datastax.astra.client.DataAPIClient;
public class Example {
public static void main(String[] args) {
DataAPIClient client = new DataAPIClient("APPLICATION_TOKEN");
}
}
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
namespace Examples;
public class Program
{
static void Main()
{
var client = new DataAPIClient("APPLICATION_TOKEN");
}
}
Instantiate a client and specify options
-
Python
-
TypeScript
-
Go
-
Java
-
C#
from astrapy import DataAPIClient
from astrapy.api_options import (
APIOptions,
SerdesOptions,
TimeoutOptions,
)
from astrapy.authentication import (
AWSEmbeddingHeadersProvider,
)
client = DataAPIClient(
api_options=APIOptions(
embedding_api_key=AWSEmbeddingHeadersProvider(
embedding_access_id="my-access-id",
embedding_secret_id="my-secret-id",
),
timeout_options=TimeoutOptions(
request_timeout_ms=15000,
general_method_timeout_ms=30000,
table_admin_timeout_ms=120000,
),
serdes_options=SerdesOptions(
custom_datatypes_in_reading=False,
use_decimals_in_collections=True,
),
)
)
import { DataAPIClient } from "@datastax/astra-db-ts";
import * as fetchH2 from "fetch-h2";
const client = new DataAPIClient({
logging: [
{ events: "commandStarted", emits: "stdout" },
{ events: "commandFailed", emits: "stderr" },
],
httpOptions: { client: "fetch-h2", fetchH2: fetchH2 },
timeoutDefaults: {
requestTimeoutMs: 20000,
generalMethodTimeoutMs: 40000,
},
});
|
The Go client is in preview. For more information, see astra-db-go. |
package main
import (
"time"
"github.com/datastax/astra-db-go/v2/astra"
"github.com/datastax/astra-db-go/v2/astra/options"
)
func main() {
_ = astra.NewClient(
options.API().
SetRequestTimeout(15 * time.Second).
SetGeneralMethodTimeout(30 * time.Second).
SetConnectionTimeout(60 * time.Second).
SetKeyspace("example_keyspace"),
)
}
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIDestination;
import com.datastax.astra.client.core.headers.AWSEmbeddingHeadersProvider;
import com.datastax.astra.client.core.headers.EmbeddingAPIKeyHeaderProvider;
import com.datastax.astra.client.core.http.HttpClientOptions;
import com.datastax.astra.client.core.http.HttpProxy;
import com.datastax.astra.client.core.options.DataAPIClientOptions;
import com.datastax.astra.client.core.options.TimeoutOptions;
import com.datastax.astra.internal.command.CommandObserver;
import com.datastax.astra.internal.command.ExecutionInfos;
import java.net.http.HttpClient;
import java.time.Duration;
public class Example {
public static void main(String[] args) {
DataAPIClientOptions options = new DataAPIClientOptions();
// Specify the environment
options.destination(DataAPIDestination.ASTRA);
// Specify the HTTP client
HttpClientOptions httpClientOptions =
new HttpClientOptions()
.retryCount(3)
.retryDelay(Duration.ofMillis(200))
.httpRedirect(HttpClient.Redirect.NORMAL)
.httpVersion(HttpClient.Version.HTTP_2)
.httpProxy(new HttpProxy().hostname("localhost").port(8080));
options.httpClientOptions(httpClientOptions);
// Specify timeouts
TimeoutOptions timeoutsOptions =
new TimeoutOptions()
.collectionAdminTimeoutMillis(5000)
.collectionAdminTimeout(Duration.ofMillis(5000))
.tableAdminTimeoutMillis(5000)
.tableAdminTimeout(Duration.ofMillis(5000))
.databaseAdminTimeoutMillis(15000)
.databaseAdminTimeout(Duration.ofMillis(15000))
.generalMethodTimeoutMillis(1000)
.generalMethodTimeout(Duration.ofMillis(1000))
.requestTimeoutMillis(200)
.requestTimeout(Duration.ofMillis(200))
.connectTimeoutMillis(100)
.connectTimeout(Duration.ofMillis(100));
options.timeoutOptions(timeoutsOptions);
// Add your application in the chain of callers in the header
options.addCaller("MySampleApplication", "1.0.0");
// Add a header to computer embeddings externally
options.embeddingHeadersProvider(new EmbeddingAPIKeyHeaderProvider("key_embeddings"));
options.embeddingHeadersProvider(
new AWSEmbeddingHeadersProvider("aws_access_key", "aws_secret_key"));
// Add headers to calls for admin or database operations
options.addAdminAdditionalHeader("X-My-Header", "MyValue");
options.addDatabaseAdditionalHeader("X-My-Header", "MyValue");
// Add loggers and observers
options.addObserver(
"my_dummy_logger",
new CommandObserver() {
@Override
public void onCommand(ExecutionInfos executionInfo) {
System.out.println("Command executed: " + executionInfo.getCommand().getName());
}
});
// Get a sl4j logger at debug level
options.logRequests();
DataAPIClient client = new DataAPIClient(options);
}
}
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
namespace Examples;
public class Program
{
static void Main()
{
var options = new CommandOptions()
{
TimeoutOptions = new TimeoutOptions()
{
ConnectionTimeout = TimeSpan.FromMilliseconds(3000),
RequestTimeout = TimeSpan.FromMilliseconds(9000),
},
};
var client = new DataAPIClient(options);
}
}
Client reference
-
Python
-
TypeScript
-
Go
-
Java
-
C#
For more information, see the client reference.
For more information, see the client reference.
|
The Go client is in preview. For more information, see astra-db-go. |
For more information, see the client reference.
For more information, see the client reference.
For more information, see the client reference.