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 (Go).
For command specifications, see the command references, such as About collections with the Data API (Go), and About tables with the Data API (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:
-
-
Databases-
CollectionsandTables
-
-
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 (Go).
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().
SetEnvironment(options.EnvironmentHCD).
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().
SetUsernamePasswordTokenProvider(
"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 |
|
The maximum time that the client should wait for an entire operation, which may involve multiple HTTP requests, to complete. |
|
The maximum time that the client should wait for individual HTTP requests. |
|
The maximum time that the client should wait for keyspace administrative operations like |
|
The maximum time that the client should wait for collection administrative operations like |
|
The maximum time that the client should wait for table administrative operations like |
Error handling
The Go client provides custom error types and sentinel errors to help applications detect errors, inspect error codes, and handle partial successes during multi-document or multi-row operations using standard Go error inspection (errors.Is and errors.As).
When a Data API command fails, the client returns an error wrapping *results.DataAPIError (or results.DataAPIErrors when multiple errors occur).
Inspect fields such as ErrorCode and Message to retrieve structured error information.
For a full list of Data API error codes, see Data API errors and error codes.
The client returns specialized error types when client-side logic, thresholds, or multi-request coordination require dedicated attributes.
For example, bulk operations such as InsertMany, UpdateMany, and DeleteMany return errors indicating whether part of the operations succeeded.
For example:
package main
import (
"context"
"errors"
"fmt"
"github.com/datastax/astra-db-go/v2/astra"
"github.com/datastax/astra-db-go/v2/astra/options"
"github.com/datastax/astra-db-go/v2/astra/results"
)
func main() {
ctx := context.Background()
client := astra.NewClient(
options.API().SetEnvironment(options.EnvironmentHCD),
)
database := client.Database(
"API_ENDPOINT",
options.API().
SetUsernamePasswordTokenProvider(
"USERNAME",
"PASSWORD",
).
SetKeyspace("KEYSPACE_NAME"),
)
collection := database.Collection("COLLECTION_NAME")
documents := []map[string]any{
{"_id": "123", "value": 1},
{"_id": "123", "value": 2}, // Duplicate _id
{"_id": "456", "value": 3},
}
_, err := collection.InsertMany(
ctx,
documents,
options.CollectionInsertMany().SetOrdered(false),
)
if err == nil {
return
}
var insertManyErr *results.InsertManyError
var apiErrs *results.DataAPIErrors
switch {
case errors.As(err, &insertManyErr):
var insertedIDs []string
if decodeErr := insertManyErr.DecodeIDs(
&insertedIDs,
); decodeErr != nil {
fmt.Printf("Failed to decode inserted IDs: %v\n", decodeErr)
}
if insertManyErr.InsertedCount() > 0 {
fmt.Printf(
"Successfully inserted %d document(s): %v\n",
insertManyErr.InsertedCount(),
insertedIDs,
)
}
for _, apiErr := range insertManyErr.Errors {
fmt.Printf(
"Error reported: %s - %s\n",
apiErr.ErrorCode,
apiErr.Message,
)
}
case errors.As(err, &apiErrs):
fmt.Println("API command failed:")
for _, apiErr := range *apiErrs {
fmt.Printf(" Code: %s\n", apiErr.ErrorCode)
fmt.Printf(" Message: %s\n", apiErr.Message)
}
case errors.Is(err, context.DeadlineExceeded):
fmt.Printf("Timed out: %v\n", err)
default:
fmt.Printf("Other error: %v\n", err)
}
}
See also
For examples and details about each command, see the command references About collections with the Data API (Go) and About tables with the Data API (Go).
For major changes between versions, see Data API client upgrade guide (Go).
For the complete client reference, see Go client reference.