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 usage, TypeScript client usage, and Java client usage.

Result

Python
TypeScript
Java

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 Database object that you can use to perform CRUD operations on your database

Parameters

Python
TypeScript
Java

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, 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.

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

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.

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'`.

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, 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`	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 DevOps API request is made to determine the default region and use it in subsequent operations.
`dbOptions`	`DatabaseOptions`	The options to use for the database.

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

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 DevOps API request is made to determine the default region and use it in subsequent operations.

dbOptions

DatabaseOptions

The options to use for the database.

Examples

The following examples demonstrate how to connect to a database.

Python
TypeScript
Java

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',
});

package com.examples;

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 DeleteOne {

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

      Database database =
          client.getDatabase(
              "API_ENDPOINT", new DatabaseOptions("APPLICATION_TOKEN", new DataAPIClientOptions()));
    }
}

Client reference

Python
TypeScript
Java

For more information, see the client reference.

Get a database object

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback