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

database.mddocs/

Database Operations

Database operations allow you to create, read, delete, and query databases, as well as manage database-level throughput provisioning.

DatabaseClient Type

type DatabaseClient struct {
    // Has unexported fields.
}

Client for performing database-level operations including container management and throughput configuration.

Database Creation

CreateDatabase

func (c *Client) CreateDatabase(
    ctx context.Context,
    databaseProperties DatabaseProperties,
    o *CreateDatabaseOptions) (DatabaseResponse, error)

Creates a new database in the Cosmos account.

Parameters:

  • ctx - Context for the request
  • databaseProperties - Database configuration including ID
  • o - Optional creation options (throughput configuration)

Returns: DatabaseResponse containing the created database properties

Database Client Operations

NewDatabase

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

Returns a DatabaseClient for performing operations on a specific database.

Parameters:

  • id - The database identifier

Returns: A DatabaseClient instance

ID

func (db *DatabaseClient) ID() string

Returns the identifier of the database.

Read

func (db *DatabaseClient) Read(
    ctx context.Context,
    o *ReadDatabaseOptions) (DatabaseResponse, error)

Retrieves database properties and metadata.

Parameters:

  • ctx - Context for the request
  • o - Optional read options (ETag conditions)

Returns: DatabaseResponse containing database properties

Delete

func (db *DatabaseClient) Delete(
    ctx context.Context,
    o *DeleteDatabaseOptions) (DatabaseResponse, error)

Deletes the database and all its containers.

Parameters:

  • ctx - Context for the request
  • o - Optional delete options (ETag conditions)

Returns: DatabaseResponse confirming deletion

Database Queries

NewQueryDatabasesPager

func (c *Client) NewQueryDatabasesPager(query string, o *QueryDatabasesOptions) *runtime.Pager[QueryDatabasesResponse]

Executes a SQL query to retrieve databases in the account.

Parameters:

  • query - The SQL query to execute
  • o - Optional query options (continuation token, query parameters)

Returns: A pager for iterating through query results

Database Throughput Operations

ReadThroughput

func (db *DatabaseClient) ReadThroughput(
    ctx context.Context,
    o *ThroughputOptions) (ThroughputResponse, error)

Retrieves the provisioned throughput configuration for the database.

Parameters:

  • ctx - Context for the request
  • o - Optional throughput options

Returns: ThroughputResponse containing throughput properties

ReplaceThroughput

func (db *DatabaseClient) ReplaceThroughput(
    ctx context.Context,
    throughputProperties ThroughputProperties,
    o *ThroughputOptions) (ThroughputResponse, error)

Updates the provisioned throughput for the database.

Parameters:

  • ctx - Context for the request
  • throughputProperties - New throughput configuration (manual or autoscale)
  • o - Optional throughput options

Returns: ThroughputResponse with updated throughput properties

Container Management

CreateContainer

func (db *DatabaseClient) CreateContainer(
    ctx context.Context,
    containerProperties ContainerProperties,
    o *CreateContainerOptions) (ContainerResponse, error)

Creates a new container in the database.

Parameters:

  • ctx - Context for the request
  • containerProperties - Container configuration (ID, partition key, indexing policy, etc.)
  • o - Optional creation options (throughput configuration)

Returns: ContainerResponse containing created container properties

NewContainer

func (db *DatabaseClient) NewContainer(id string) (*ContainerClient, error)

Returns a ContainerClient for performing operations on a specific container.

Parameters:

  • id - The container identifier

Returns: A ContainerClient instance

NewQueryContainersPager

func (c *DatabaseClient) NewQueryContainersPager(query string, o *QueryContainersOptions) *runtime.Pager[QueryContainersResponse]

Executes a SQL query to retrieve containers in the database.

Parameters:

  • query - The SQL query to execute
  • o - Optional query options (continuation token, query parameters)

Returns: A pager for iterating through query results

Types

DatabaseProperties

type DatabaseProperties struct {
    // ID contains the unique id of the database.
    ID string `json:"id"`
    // ETag contains the entity etag of the database
    ETag *azcore.ETag `json:"_etag,omitempty"`
    // SelfLink contains the self-link of the database
    SelfLink string `json:"_self,omitempty"`
    // ResourceID contains the resource id of the database
    ResourceID string `json:"_rid,omitempty"`
    // LastModified contains the last modified time of the database
    LastModified time.Time `json:"_ts,omitempty"`
}

Represents the properties and metadata of a database.

MarshalJSON

func (tp DatabaseProperties) MarshalJSON() ([]byte, error)

Implements the json.Marshaler interface.

UnmarshalJSON

func (tp *DatabaseProperties) UnmarshalJSON(b []byte) error

Implements the json.Unmarshaler interface.

DatabaseResponse

type DatabaseResponse struct {
    // DatabaseProperties contains the unmarshalled response body in DatabaseProperties format.
    DatabaseProperties *DatabaseProperties
    Response
}

Represents the response from a database operation.

Fields:

  • DatabaseProperties - The database properties (nil on delete operations)
  • Response - Base response fields (request charge, activity ID, ETag, etc.)

CreateDatabaseOptions

type CreateDatabaseOptions struct {
    // ThroughputProperties: Optional throughput configuration of the database
    ThroughputProperties *ThroughputProperties
}

Options for CreateDatabase operation.

ReadDatabaseOptions

type ReadDatabaseOptions struct {
    IfMatchEtag     *azcore.ETag
    IfNoneMatchEtag *azcore.ETag
}

Options for Read operation including ETag-based conditional requests.

DeleteDatabaseOptions

type DeleteDatabaseOptions struct {
    IfMatchEtag     *azcore.ETag
    IfNoneMatchEtag *azcore.ETag
}

Options for Delete operation including ETag-based conditional requests.

QueryDatabasesOptions

type QueryDatabasesOptions struct {
    // ContinuationToken to be used to continue a previous query execution.
    // Obtained from QueryDatabasesResponse.ContinuationToken.
    ContinuationToken *string

    // QueryParameters allows execution of parametrized queries.
    // See https://docs.microsoft.com/azure/cosmos-db/sql/sql-query-parameterized-queries
    QueryParameters []QueryParameter
}

Options for querying databases.

QueryDatabasesResponse

type QueryDatabasesResponse struct {
    Response
    // ContinuationToken contains the value of the x-ms-continuation header in the response.
    // It can be used to stop a query and resume it later.
    ContinuationToken *string
    // List of databases.
    Databases []DatabaseProperties
}

Response from a database query operation.

Usage Examples

Create a Database

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

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

databaseProperties := azcosmos.DatabaseProperties{ID: "products"}
response, err := client.CreateDatabase(context.Background(), databaseProperties, nil)
if err != nil {
    panic(err)
}

fmt.Printf("Created database: %s\n", response.DatabaseProperties.ID)

Create Database with Manual Throughput

throughput := azcosmos.NewManualThroughputProperties(400)
options := &azcosmos.CreateDatabaseOptions{
    ThroughputProperties: &throughput,
}

databaseProperties := azcosmos.DatabaseProperties{ID: "products"}
response, err := client.CreateDatabase(context.Background(), databaseProperties, options)
if err != nil {
    panic(err)
}

Create Database with Autoscale Throughput

throughput := azcosmos.NewAutoscaleThroughputProperties(4000)
options := &azcosmos.CreateDatabaseOptions{
    ThroughputProperties: &throughput,
}

databaseProperties := azcosmos.DatabaseProperties{ID: "products"}
response, err := client.CreateDatabase(context.Background(), databaseProperties, options)
if err != nil {
    panic(err)
}

Read Database Properties

database, _ := client.NewDatabase("products")
response, err := database.Read(context.Background(), nil)
if err != nil {
    panic(err)
}

fmt.Printf("Database ID: %s\n", response.DatabaseProperties.ID)
fmt.Printf("ETag: %s\n", *response.DatabaseProperties.ETag)

Delete a Database

database, _ := client.NewDatabase("products")
response, err := database.Delete(context.Background(), nil)
if err != nil {
    panic(err)
}

fmt.Printf("Deleted database, RU charge: %f\n", response.RequestCharge)

Query Databases

query := "SELECT * FROM c WHERE c.id LIKE 'test%'"
pager := client.NewQueryDatabasesPager(query, nil)

for pager.More() {
    response, err := pager.NextPage(context.Background())
    if err != nil {
        panic(err)
    }
    
    for _, db := range response.Databases {
        fmt.Printf("Database: %s\n", db.ID)
    }
}

Query Databases with Parameters

query := "SELECT * FROM c WHERE c.id = @dbId"
options := &azcosmos.QueryDatabasesOptions{
    QueryParameters: []azcosmos.QueryParameter{
        {Name: "@dbId", Value: "products"},
    },
}

pager := client.NewQueryDatabasesPager(query, options)
for pager.More() {
    response, err := pager.NextPage(context.Background())
    if err != nil {
        panic(err)
    }
    
    for _, db := range response.Databases {
        fmt.Printf("Found database: %s\n", db.ID)
    }
}

Read Database Throughput

database, _ := client.NewDatabase("products")
throughputResponse, err := database.ReadThroughput(context.Background(), nil)
if err != nil {
    panic(err)
}

if manual, ok := throughputResponse.ThroughputProperties.ManualThroughput(); ok {
    fmt.Printf("Manual throughput: %d RU/s\n", manual)
}

if autoscale, ok := throughputResponse.ThroughputProperties.AutoscaleMaxThroughput(); ok {
    fmt.Printf("Autoscale max throughput: %d RU/s\n", autoscale)
}

Update Database Throughput

database, _ := client.NewDatabase("products")

// Change from 400 to 1000 RU/s
newThroughput := azcosmos.NewManualThroughputProperties(1000)
response, err := database.ReplaceThroughput(context.Background(), newThroughput, nil)
if err != nil {
    panic(err)
}

fmt.Printf("Updated throughput, RU charge: %f\n", response.RequestCharge)

Conditional Read with ETag

database, _ := client.NewDatabase("products")

// First read to get ETag
response1, _ := database.Read(context.Background(), nil)
etag := response1.DatabaseProperties.ETag

// Conditional read - only retrieve if modified
options := &azcosmos.ReadDatabaseOptions{
    IfNoneMatchEtag: etag,
}

response2, err := database.Read(context.Background(), options)
if err != nil {
    // Will return 304 Not Modified if unchanged
    fmt.Printf("Database not modified\n")
}