Get a database object

When using a client, most Data API interactions require you to connect to a database through a DataAPIClient object.

Connecting to a database is an essential component of most 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 Database object that you can use to perform CRUD operations on your database

Returns a Db object that you can use to perform CRUD operations on your database

The Go client is in preview. For more information, see astra-db-go.

Returns a Db struct that you can use to perform CRUD operations on your database

Returns a Database object that you can use to perform CRUD operations on your database

Returns a Database object that you can use to perform CRUD operations on your database

Parameters

  • Python

  • TypeScript

  • Go

  • Java

  • C#

Use the get_database method, which belongs to the astrapy.DataAPIClient class.

Method signature 
get_database(
    api_endpoint: str,
    *,
    token: str | TokenProvider,
    keyspace: str,
    spawn_api_options: APIOptions,
) -> Database
Name Type Summary

api_endpoint

str

A database API endpoint URL, such as https://DATABASE_ID-REGION.apps.astra.datastax.com.

token

str | TokenProvider

Optional. An application token for a database, in the form of an "AstraCS:…​" string, or an instance of TokenProvider.

The token should have sufficient permissions to perform the desired operations.

If you specified a token when instantiating the DataAPIClient, that token will be overridden.

keyspace

str

Optional. Specify the working keyspace. You can override this in downstream methods such as use_keyspace, get_collection, create_collection, get_table, create_table.

Default: "default_keyspace".

spawn_api_options

APIOptions

Optional. A complete or partial specification of the APIOptions.

This overrides the defaults inherited from the Data API client. This allows you to customize the interaction with the Data API. For example, you can use this parameter to change the timeout settings.

Use the db method, which belongs to the DataAPIClient class.

Method signature 
db(
  endpoint: string,
  options?: {
    logging?: LoggingConfig,
    keyspace?: string | null,
    token?: string | TokenProvider | null,
    dataApiPath?: string,
    serdes?: DbSerDesConfig,
    timeoutDefaults?: TimeoutDescriptor,
  }
): Db
Name Type Summary

endpoint

string

A database API endpoint URL, such as https://DATABASE_ID-REGION.apps.astra.datastax.com.

options

RootDbOptions

Optional. The options to use for the database. See Properties of options for more details.
Properties of options
Name Type Summary

keyspace

string

Optional. Specify the working keyspace. You can override this in downstream methods such as useKeyspace, collection, createCollection, table, and getTable.

Default: "default_keyspace".

monitorCommands

boolean

Optional. Whether to monitor commands through CommandEvents, using the client as an event emitter.

Default: false.

token

string

Optional. An application token for a database. Tokens are prefixed with AstraCS:.

The token should have sufficient permissions to perform the desired operations.

If you specified a token when instantiating the DataAPIClient, that token will be overridden.

dataApiPath

string

Optional. The path to the Data API.

Default: 'api/json/v1'.

The Go client is in preview. For more information, see astra-db-go.

Use the Database method, which belongs to the DataAPIClient type.

Method signature 
func (c *DataAPIClient) Database(
  endpoint string,
  opts ...options.APIOption
) *Db
Name Type Summary

endpoint

string

A database API endpoint URL, such as https://DATABASE_ID-REGION.apps.astra.datastax.com.

opts

…​options.APIOption

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 in downstream Data API operations.

See Methods of the options.APIOption builder for more details.
Methods of the options.APIOption builder
Method Summary

SetToken(token string)

Optional. An application token for a database, in the form of an "AstraCS:…​" string.

The token should have sufficient permissions to perform the desired operations.

SetAstraEnvironment(v AstraEnvironment)

Optional. Specify the environment this client will work in.

Default: options.AstraEnvironmentProd.

SetGeneralMethodTimeout(v time.Duration)

Optional. The maximum time that the client should wait for an entire operation, which may involve multiple HTTP requests, to complete. Default: 30 seconds

SetRequestTimeout(v time.Duration)

Optional. The maximum time that the client should wait for individual HTTP requests.

Default: 15 seconds

SetDatabaseAdminTimeout(v time.Duration)

Optional. The maximum time that the client should wait for database administrative operations like CreateDatabase and DropDatabase.

Default: 10 minutes

SetKeyspaceAdminTimeout(v time.Duration)

Optional. The maximum time that the client should wait for keyspace administrative operations like CreateKeyspace and DropKeyspace.

Default: 30 seconds

SetCollectionAdminTimeout(v time.Duration)

Optional. The maximum time that the client should wait for collection administrative operations like CreateCollection and DropCollection.

Default: 60 seconds

SetTableAdminTimeout(v time.Duration)

Optional. The maximum time that the client should wait for table administrative operations like CreateTable, CreateIndex, and CreateType.

Default: 30 seconds

UpdateTimeout(v …​options.TimeoutOption)

Optional. An alternative to SetGeneralMethodTimeout(), SetRequestTimeout(), SetDatabaseAdminTimeout(), SetKeyspaceAdminTimeout(), SetCollectionAdminTimeout(), and SetTableAdminTimeout().

SetDataAPIBackend(v options.DataAPIBackend)

Optional. Sets the database backend.

Default: options.DataAPIBackendAstra

SetKeyspace(v string)

Optional The keyspace to use for downstream operations.

Default: default_keyspace

AddHeader(key string, value string)

Optional. Specifies headers for all HTTP requests to the Data API.

AddCaller(name string, version string)

Optional. Attaches special identifying entries to the User-Agent header for all HTTP requests to the Data API.

SetAPIVersion(v string)

Optional. Sets the Data API version.

Default: v1

SetHTTPClient(v *http.Client)

Optional. Sets the HTTP client to use for requests.

SetWarningHandler(handler options.WarningHandler)

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.

UpdateSerdes(v …​options.SerdesOption)

Optional. Sets the serialization/deserialization options.

Use the getDatabase method, which belongs to the com.datastax.astra.client.DataAPIClient class.

Method signature 
public Database getDatabase(String apiEndpoint, DatabaseOptions dbOptions)
public Database getDatabase(String apiEndpoint, String keyspace)
public Database getDatabase(String apiEndpoint)
public Database getDatabase(UUID databaseId)
public Database getDatabase(UUID databaseId, DatabaseOptions dbOptions)
public Database getDatabase(UUID databaseId, String region, DatabaseOptions dbOptions)
Name Type Summary

apiEndpoint

String

A database API endpoint URL, such as https://DATABASE_ID-REGION.apps.astra.datastax.com.

databaseId

UUID

A database ID. You can optionally specify a region for multi-region databases.

DataStax recommends using apiEndpoint instead.

keyspace

String

Optional. Specify the working keyspace. You can override this in downstream methods such as useKeyspace, getCollection, createCollection, getTable, createTable.

Default: "default_keyspace".

region

String

The region to use for connecting to the database.

The database must be deployed in that region.

If you don’t set this parameter and the region cannot be inferred from an API endpoint, an additional request is made to determine the default region and use it in subsequent operations.

dbOptions

DatabaseOptions

The options to use for the database.

Use the GetDatabase method, which belongs to the DataAPIClient class.

Method signature 
public Database GetDatabase(string apiEndpoint);
public Database GetDatabase(
  string apiEndpoint, string token, string keyspace = null
);
public Database GetDatabase(
  string apiEndpoint, GetDatabaseOptions options
);
Name Type Summary

apiEndpoint

string

A database API endpoint URL, such as https://DATABASE_ID-REGION.apps.astra.datastax.com.

token

str

Optional. An application token for a database, in the form of an "AstraCS:…​" string.

The token should have sufficient permissions to perform the desired operations.

If you specified a token when instantiating the DataAPIClient, that token will be overridden.

keyspace

string

Optional. Specify the working keyspace. You can override this in downstream methods such as useKeyspace, getCollection, createCollection, getTable, createTable.

Default: "default_keyspace".

options

GetDatabaseOptions

Optional. General API options for this operation, including the keyspace and timeout. For more information and examples, see Customize API interaction.

Examples

The following examples demonstrate how to connect to a database.

  • Python

  • TypeScript

  • Go

  • Java

  • C#

from astrapy import DataAPIClient

client = DataAPIClient()
database = client.get_database(
    "API_ENDPOINT", token="APPLICATION_TOKEN"
)
import { DataAPIClient } from "@datastax/astra-db-ts";

const client = new DataAPIClient();
const database = client.db("API_ENDPOINT", {
  token: "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() {

	client := astra.NewClient()

	_ = client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)
}
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.options.DataAPIClientOptions;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.databases.DatabaseOptions;

public class Example {
  public static void main(String[] args) {
    DataAPIClient client = new DataAPIClient(new DataAPIClientOptions());

    Database database =
        client.getDatabase(
            "API_ENDPOINT",
            new DatabaseOptions("APPLICATION_TOKEN", new DataAPIClientOptions()));
  }
}
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static void Main()
  {
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );
  }
}

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.

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM