or run

tessl search
Log in

Version

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos@v1.4.1

docs

batch.mdclient.mdconfiguration.mdcontainer.mddatabase.mdindex.mditems.mdpartition-keys.mdpatch.mdquerying.mdthroughput.mdtypes.md
tile.json

tessl/golang-github-com-azure-azure-sdk-for-go-sdk-data-azcosmos

tessl install tessl/golang-github-com-azure-azure-sdk-for-go-sdk-data-azcosmos@1.4.1

Go SDK client library for interacting with Azure Cosmos DB SQL API

client.mddocs/

Client Creation & Authentication

The azcosmos package supports multiple authentication methods for creating a Cosmos DB client: Azure Active Directory (Azure AD) token credentials, account keys, and connection strings.

Client Type

type Client struct {
    // Has unexported fields.
}

The root client for interacting with Azure Cosmos DB service. Used to perform account-level operations and obtain database/container clients.

Client Constructors

NewClient

func NewClient(endpoint string, cred azcore.TokenCredential, o *ClientOptions) (*Client, error)

Creates a new Cosmos client instance with Azure AD access token authentication.

Parameters:

  • endpoint - The Cosmos service endpoint URL (e.g., "https://myaccount.documents.azure.com:443/")
  • cred - The Azure credential used to authenticate (from azidentity package)
  • o - Optional client configuration. Pass nil to accept defaults

Returns: A configured Client instance or an error

NewClientWithKey

func NewClientWithKey(endpoint string, cred KeyCredential, o *ClientOptions) (*Client, error)

Creates a new Cosmos client instance with shared key (master key) authentication.

Parameters:

  • endpoint - The Cosmos service endpoint URL
  • cred - The KeyCredential containing the account's primary or secondary key
  • o - Optional client configuration. Pass nil to accept defaults

Returns: A configured Client instance or an error

NewClientFromConnectionString

func NewClientFromConnectionString(connectionString string, o *ClientOptions) (*Client, error)

Creates a new Cosmos client instance from a connection string.

Parameters:

  • connectionString - The Cosmos service connection string (contains endpoint and key)
  • o - Optional client configuration. Pass nil to accept defaults

Returns: A configured Client instance or an error

Client Methods

Endpoint

func (c *Client) Endpoint() string

Returns the endpoint URL used to create the client.

NewDatabase

func (c *Client) NewDatabase(id string) (*DatabaseClient, error)

Returns a DatabaseClient for performing database-level operations.

Parameters:

  • id - The database identifier

Returns: A DatabaseClient instance or an error

NewContainer

func (c *Client) NewContainer(databaseId string, containerId string) (*ContainerClient, error)

Returns a ContainerClient for performing container-level operations.

Parameters:

  • databaseId - The database identifier
  • containerId - The container identifier

Returns: A ContainerClient instance or an error

Credentials

KeyCredential

type KeyCredential struct {
    // Has unexported fields.
}

Contains an account's primary or secondary key. Immutable and goroutine-safe.

NewKeyCredential

func NewKeyCredential(accountKey string) (KeyCredential, error)

Creates a KeyCredential containing the account's primary or secondary key.

Parameters:

  • accountKey - The account's master key

Returns: A KeyCredential instance or an error

Update

func (c *KeyCredential) Update(accountKey string) error

Replaces the existing account key with a new key. Thread-safe.

Parameters:

  • accountKey - The new account key

Returns: An error if the key is invalid

Client Options

type ClientOptions struct {
    azcore.ClientOptions
    // When EnableContentResponseOnWrite is false will cause the response to have a null resource.
    // This reduces networking and CPU load by not sending the resource back over the network and serializing it on the client.
    // The default is false.
    EnableContentResponseOnWrite bool
    // PreferredRegions is a list of regions to be used when initializing the client in case the default region fails.
    PreferredRegions []string
}

Configuration options for the Cosmos client.

Fields:

  • azcore.ClientOptions - Base Azure SDK client options (retry policy, telemetry, logging, transport)
  • EnableContentResponseOnWrite - Whether to return full resource bodies on write operations (default: false)
  • PreferredRegions - List of preferred regions for multi-region accounts

Usage Examples

Azure AD Authentication

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
)

// Using DefaultAzureCredential
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    panic(err)
}

client, err := azcosmos.NewClient("https://myaccount.documents.azure.com:443/", cred, nil)
if err != nil {
    panic(err)
}

// Using ClientSecretCredential
cred, err := azidentity.NewClientSecretCredential("tenantId", "clientId", "clientSecret", nil)
if err != nil {
    panic(err)
}

client, err := azcosmos.NewClient("https://myaccount.documents.azure.com:443/", cred, nil)
if err != nil {
    panic(err)
}

Account Key Authentication

import "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"

cred, err := azcosmos.NewKeyCredential("myAccountPrimaryKey")
if err != nil {
    panic(err)
}

client, err := azcosmos.NewClientWithKey("https://myaccount.documents.azure.com:443/", cred, nil)
if err != nil {
    panic(err)
}

Connection String Authentication

import "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"

connectionString := "AccountEndpoint=https://myaccount.documents.azure.com:443/;AccountKey=mykey=="

client, err := azcosmos.NewClientFromConnectionString(connectionString, nil)
if err != nil {
    panic(err)
}

Using Client Options

import (
    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
    "github.com/Azure/azure-sdk-for-go/sdk/azcore/policy"
)

options := &azcosmos.ClientOptions{
    EnableContentResponseOnWrite: true,
    PreferredRegions: []string{"West US", "East US"},
    ClientOptions: azcore.ClientOptions{
        Retry: policy.RetryOptions{
            MaxRetries: 5,
        },
    },
}

cred, _ := azcosmos.NewKeyCredential("mykey")
client, err := azcosmos.NewClientWithKey("https://myaccount.documents.azure.com:443/", cred, options)
if err != nil {
    panic(err)
}

Rotating Account Keys

import "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"

cred, _ := azcosmos.NewKeyCredential("primaryKey")
client, _ := azcosmos.NewClientWithKey("https://myaccount.documents.azure.com:443/", cred, nil)

// Later, rotate to secondary key
err := cred.Update("secondaryKey")
if err != nil {
    panic(err)
}
// Client will now use the new key for all subsequent requests