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

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

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

Name	Type	Summary
`api_endpoint`	`str`	A database API endpoint URL.
`token`	`str \| TokenProvider`	Optional. An application token, or an instance of `TokenProvider`. For more information about how to generate a token, see Get endpoint and token. The username and password used to generate the token must be tied to a role that has 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. This keyspace is used for all downstream operations unless you later override it with a method such as `use_keyspace`, `get_collection`, `create_collection`, `get_table`, `create_table`. If you don’t set this, you must specify the keyspace in a downstream method before performing an operation that requires a 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.

api_endpoint

str

A database API endpoint URL.

token

str | TokenProvider

Optional.

An application token, or an instance of TokenProvider. For more information about how to generate a token, see Get endpoint and token.

The username and password used to generate the token must be tied to a role that has 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. This keyspace is used for all downstream operations unless you later override it with a method such as use_keyspace, get_collection, create_collection, get_table, create_table.

If you don’t set this, you must specify the keyspace in a downstream method before performing an operation that requires a 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

Name	Type	Summary
`endpoint`	`string`	A database API endpoint URL.
`options`	`RootDbOptions`	Optional. The options to use for the database. See Properties of `options` for more details.

endpoint

string

A database API endpoint URL.

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. This keyspace is used for all downstream operations unless you later override it with a method such as `useKeyspace`, `collection`, `createCollection`, `table`, or `createTable`. If you don’t set this, you must specify the keyspace in a downstream method before performing an operation that requires a 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, or an instance of `TokenProvider`. For more information about how to generate a token, see Get endpoint and token. The username and password used to generate the token must be tied to a role that has 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'`.

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

Name	Type	Summary
`endpoint`	`string`	A database API endpoint URL.
`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.

endpoint

string

A database API endpoint URL.

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 more information about how to generate a token, see Get endpoint and token. The username and password used to generate the token must be tied to a role that has sufficient permissions to perform the desired operations. Alternatively, use `SetUsernamePasswordTokenProvider()` or `SetTokenProvider()` to set the token based on a username and password.
`SetUsernamePasswordTokenProvider(user string, pass string)`	Optional. Generates and sets the application token based on a username and password. The username and password must be tied to a role that has sufficient permissions to perform the desired operations. Alternatively, use `SetToken()` to pass a token directly.
`SetTokenProvider(provider options.TokenProvider)`	Optional. Generates and sets the application token based on a `TokenProvider` like `NewUsernamePasswordTokenProvider`. The username and password set in the `TokenProvider` must be tied to a role that has sufficient permissions to perform the desired operations. Alternatively, use the `SetUsernamePasswordTokenProvider()` shortcut, or use `SetToken()` to pass a token directly.
`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
`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()`.
`SetEnvironment(v options.Environment)`	Sets the database backend. You must set this to `options.EnvironmentHCD`
`SetKeyspace(v string)`	Optional. Specify the working keyspace. This keyspace is used for all downstream operations unless you later override it with a method such as `UseKeyspace`, `Collection`, `CreateCollection`, `Table`, or `CreateTable`. If you don’t set this, you must specify the keyspace in a downstream method before performing an operation that requires a 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

Name	Type	Summary
`apiEndpoint`	`String`	A database API endpoint URL.
`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. This keyspace is used for all downstream operations unless you later override it with a method such as `useKeyspace`, `getCollection`, `createCollection`, `getTable`, or `createTable`. If you don’t set this, you must specify the keyspace in a downstream method before performing an operation that requires a keyspace.
`dbOptions`	`DatabaseOptions`	The options to use for the database.

apiEndpoint

String

A database API endpoint URL.

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. This keyspace is used for all downstream operations unless you later override it with a method such as useKeyspace, getCollection, createCollection, getTable, or createTable.

If you don’t set this, you must specify the keyspace in a downstream method before performing an operation that requires a keyspace.

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

Name	Type	Summary
`apiEndpoint`	`string`	A database API endpoint URL.
`token`	`str`	Optional. An application token. You can use `DataAPIClient.UsernamePasswordTokenProvider` to generate a token from a username and password. The username and password used to generate the token must be tied to a role that has sufficient permissions to perform the desired operations. For more information about how to generate a token, see Get endpoint and token. If you specified a token when instantiating the `DataAPIClient`, that token will be overridden.
`keyspace`	`string`	Optional. Specify the working keyspace. This keyspace is used for all downstream operations unless you later override it with a method such as `useKeyspace`, `getCollection`, `createCollection`, `getTable`, or `createTable`. If you don’t set this, you must specify the keyspace in a downstream method before performing an operation that requires a keyspace.
`options`	`GetDatabaseOptions`	Optional. General API options for this operation, including the keyspace and timeout. Keyspace is required unless you specified a working keyspace when instantiating the `Database` object. For more information and examples, see Customize API interaction.

apiEndpoint

string

A database API endpoint URL.

token

str

Optional.

An application token. You can use DataAPIClient.UsernamePasswordTokenProvider to generate a token from a username and password.

The username and password used to generate the token must be tied to a role that has sufficient permissions to perform the desired operations.

For more information about how to generate a token, see Get endpoint and token.

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

keyspace

string

If you don’t set this, you must specify the keyspace in a downstream method before performing an operation that requires a keyspace.

options

GetDatabaseOptions

Optional. General API options for this operation, including the keyspace and timeout. Keyspace is required unless you specified a working keyspace when instantiating the Database object. 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
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)

import {
  DataAPIClient,
  UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";

const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});

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(
		options.API().SetEnvironment(options.EnvironmentHCD),
	)

	_ = client.Database(
		"API_ENDPOINT",
		options.API().
			SetUsernamePasswordTokenProvider(
				"USERNAME",
				"PASSWORD",
			),
	)
}

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;

public class Example {
  public static void main(String[] args) {
    DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
    Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
  }
}

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;

namespace Examples;

public class Program
{
  static void Main()
  {
    var client = new DataAPIClient(
      new CommandOptions() { Destination = DataAPIDestination.HCD }
    );

    var database = client.GetDatabase(
      "API_ENDPOINT",
      DataAPIClient.UsernamePasswordTokenProvider(
        "USERNAME",
        "PASSWORD"
      )
    );
  }
}

Client reference

Python
TypeScript
Go
Java
C#

For more information, see the client reference.

Get a database object

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback