Go client internals

This page discusses supplemental information about the internals of the Data API Go client.

For information about installing and getting started with the Go client, see Get started with the Data API.

For command specifications, see the command references, such as About collections with the Data API, and About tables with the Data API.

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

Client hierarchy

When you create apps using the Data API clients, you must instantiate a DataAPIClient object.

The DataAPIClient object serves as the entry point to the client hierarchy. It includes the following concepts:

Adjacent to these concepts are the administration classes for database administration. The specific administration classes you use, and how you instantiate them, depends on your client language and database type (Astra DB, HCD, or DSE).

You directly instantiate the DataAPIClient object only. Then, through the DataAPIClient object, you can instantiate and access other classes and concepts. Where necessary, instructions for instantiating other classes are provided in the command reference relevant to each class.

For instructions for instantiating the DataAPIClient object, see Instantiate a client object.

Timeouts

You can specify timeouts in any method that accepts API options. Timeouts are inherited from parent to child.

For example:

package main

import (
	"context"
	"log"
	"time"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
)

func main() {
	ctx := context.Background()

	// Set the general method timeout and table admin timeout
	// for any structs spawned from this client struct
	client := astra.NewClient(
		options.API().
			SetDataAPIBackend(options.DataAPIBackendHCD).
			SetGeneralMethodTimeout(10 * time.Second).
			SetTableAdminTimeout(40 * time.Second),
	)

	// Override the general method timeout
	// and set the keyspace admin timeout
	// for any structs spawned from this Db struct
	// and for any methods called by this struct
	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetTokenProvider(
				options.NewUsernamePasswordTokenProvider(
					"USERNAME",
					"PASSWORD",
				),
			).
			SetGeneralMethodTimeout(5*time.Second).
			SetKeyspaceAdminTimeout(20*time.Second),
	)

	// Override the general method timeout
	// and set the request admin timeout
	// for any structs spawned from this Db struct
	// and for any methods called by this struct
	table := database.Table(
		"TABLE_NAME",
		options.GetTable().
			UpdateAPIOptions(options.API().
				SetGeneralMethodTimeout(15*time.Second).
				SetRequestTimeout(7*time.Second),
			),
	)

	// Override the request timeout for this method
	var result astra.Row
	err := table.FindOne(
		ctx,
		filter.Lt("number_of_pages", 300),
		options.TableFindOne().
			UpdateAPIOptions(options.API().SetRequestTimeout(5*time.Second)),
	).
		Decode(&result)

	if err != nil {
		log.Fatal(err)
	}
}

The client supports the following timeouts:

Timeout name

Description

GeneralMethod

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

Request

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

KeyspaceAdmin

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

CollectionAdmin

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

TableAdmin

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

See also

For examples and details about each command, see the command references About collections with the Data API and About tables with the Data API.

For major changes between versions, see Data API client upgrade guide.

For the complete client reference, see Go 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