Instantiate a client object (TypeScript)

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 (TypeScript).

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

Returns a DataAPIClient object that you can use to interact with the Data API.

Parameters

Name Type Summary

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.

DataAPIClient objects aren’t specific to a database. Therefore, when you instantiate a client, you can omit this parameter and specify a token later with client.db() or client.admin().

options

DataAPIClientOptions

Optional. The options to use for the client, including defaults. See Properties of options for more details.
Properties of options
Name Type Summary

environment

DataAPIEnvironment

Optional. Specify the environment this client will work in.

Can be one of: astra, dse, hcd, cassandra, other

For more information, see the astra-db-ts README.

Default: astra

httpOptions

DataAPIClientOptions

Optional. Options related to the API requests made by the client.

The DataAPIClientOptions type is a discriminated union on the client field. There are four available behaviors for the client field:

  • httpOptions not set: Use fetch-h2 if available or fall back to fetch.

  • client: 'default' or unset: Use fetch-h2 if available or throw an error.

  • client: 'fetch': Only use the native fetch API.

  • client: 'custom': Pass a custom Fetcher implementation to the client.

fetch-h2 is typically available by default on node runtimes only. On other runtimes, you might need to use the native fetch API or, if your code is minified, pass in the fetch-h2 module manually.

For more information on http clients, see the astra-db-ts README and the client reference.

dbOptions

RootDbOptions

Optional. Specify default options for when spawning a Db instance.

adminOptions

RootAdminOptions

Optional. Specify default options for when spawning an Admin instance.

Examples

The following examples demonstrate how to instantiate a client.

Instantiate a client

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

const client = new DataAPIClient({ environment: "hcd" });

Instantiate a client and pass a token

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

const client = new DataAPIClient(
  new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
  { environment: "hcd" },
);

Instantiate a client and specify options

import { DataAPIClient } from "@datastax/astra-db-ts";
import * as fetchH2 from "fetch-h2";

const client = new DataAPIClient({
  environment: "hcd",
  logging: [
    { events: "commandStarted", emits: "stdout" },
    { events: "commandFailed", emits: "stderr" },
  ],
  httpOptions: { client: "fetch-h2", fetchH2: fetchH2 },
  timeoutDefaults: {
    requestTimeoutMs: 20000,
    generalMethodTimeoutMs: 40000,
  },
});

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