A simple, convenience package for the Azure Cosmos DB Go SDK

When using the Go SDK for the Azure Cosmos DB NoSQL API, I often find myself writing boilerplate code for various operations. This includes database/container operations, querying, and more. cosmosdb-go-sdk-helper (I know, not a great name!) is a package with convenience functions for some of these tasks. In this blog post, I will go over the packages in the repository with examples on how (and when) you can use them. It's early days for this project, but I hope to keep adding to it gradually. Overview auth: Simplifies authentication for both production and local development. common: Helps with common database and container operations. query: Offers type-safe, generic query helpers and optional metrics, and helps with Cosmos DB query metrics. functions: Eases the parsing of Azure Functions Cosmos DB trigger payloads. cosmosdb_errors: Extracts structured error information for simple error handling. Quick Start To get started, install the package: go get github.com/abhirockzz/cosmosdb-go-sdk-helper Try it out using the example below: package main import ( "fmt" "log" "github.com/abhirockzz/cosmosdb-go-sdk-helper/auth" "github.com/abhirockzz/cosmosdb-go-sdk-helper/common" "github.com/abhirockzz/cosmosdb-go-sdk-helper/query" ) func main() { endpoint := "https://ACCOUNT_NAME.documents.azure.com:443" type Task struct { ID string `json:"id"` Info string `json:"info"` } client, err := auth.GetCosmosDBClient(endpoint, false, nil) if err != nil { log.Fatalf("Azure AD auth failed: %v", err) } container, err := client.NewContainer(databaseName, containerName) if err != nil { log.Fatalf("NewContainer failed: %v", err) } task := Task{ ID: "45", Info: "Sample task", } insertedTask, err := common.InsertItemWithResponse(container, task, azcosmos.NewPartitionKeyString(task.ID), nil) if err != nil { log.Fatalf("InsertItem failed: %v", err) } fmt.Printf("Inserted task: %s (%s)\n", insertedTask.ID, insertedTask.Info) tasks, err := query.QueryItems[Task](container, sqlQuery, azcosmos.NewPartitionKey(), nil) if err != nil { log.Fatalf("QueryItems failed: %v", err) } for _, task := range tasks { fmt.Printf("Task: %s (%s)\n", task.ID, task.Info) } } Let's quickly go over the packages. Authentication (auth) The auth package gets authenticated Cosmos DB client handle for both Azure AD and local Cosmos DB emulator. It simplifies the process, making it easier to switch between production and local development environments. Example: When connecting to actual Cosmos DB endpoint, function uses DefaultAzureCredential. DefaultAzureCredential uses an ordered sequence of mechanisms for authentication (including environment variables, managed identity, Azure CLI credential etc.). client, err := auth.GetCosmosDBClient("https://your-account.documents.azure.com:443", false, nil) if err != nil { log.Fatalf("Azure AD auth failed: %v", err) } When using the emulator, simply set useEmulator flag to true and pass the emulator URL (e.g. http://localhost:8081) without changing anything else. client, err := auth.GetCosmosDBClient("http://localhost:8081", true, nil) if err != nil { log.Fatalf("Emulator auth failed: %v", err) } Database and Container Operations (common) The common package lets you to create databases and containers only if they don't already exist. This is useful for idempotent resource management, especially in CI/CD pipelines. It also provides other utility functions, such as listing all databases and containers, etc. Example: props := azcosmos.DatabaseProperties{ID: "tododb"} db, err := common.CreateDatabaseIfNotExists(client, props, nil) containerProps := azcosmos.ContainerProperties{ ID: "tasks", PartitionKeyDefinition: azcosmos.PartitionKeyDefinition{ Paths: []string{"/id"}, Kind: azcosmos.PartitionKeyKindHash, }, } container, err := common.CreateContainerIfNotExists(db, containerProps, nil) This is also goroutine-safe (can be used with concurrent programs), so you can run it in multiple instances without worrying about race conditions since its idempotent. Query Operations (query) The query package provides generic helpers for querying multiple or single items, returning strongly-typed results. This eliminates the need for manual unmarshalling and reduces boilerplate code. Example: type Task struct { ID string `json:"id"` Info string `json:"info"` } tasks, err := query.QueryItems[Task](container, "SELECT * FROM c", azcosmos.NewPartitionKey(), nil) // Query a single item task, err := query.QueryItem[Task](container, "item-id", azcosmos.NewPartitionKeyString("item-id"), nil) Query Metrics (metrics) You can use the metrics package to conveniently execute queries and the

May 12, 2025 - 13:24

A simple, convenience package for the Azure Cosmos DB Go SDK

When using the Go SDK for the Azure Cosmos DB NoSQL API, I often find myself writing boilerplate code for various operations. This includes database/container operations, querying, and more. cosmosdb-go-sdk-helper (I know, not a great name!) is a package with convenience functions for some of these tasks.

In this blog post, I will go over the packages in the repository with examples on how (and when) you can use them. It's early days for this project, but I hope to keep adding to it gradually.

Overview

auth: Simplifies authentication for both production and local development.
common: Helps with common database and container operations.
query: Offers type-safe, generic query helpers and optional metrics, and helps with Cosmos DB query metrics.
functions: Eases the parsing of Azure Functions Cosmos DB trigger payloads.
cosmosdb_errors: Extracts structured error information for simple error handling.

Quick Start

To get started, install the package:

go get github.com/abhirockzz/cosmosdb-go-sdk-helper

Try it out using the example below:

package main

import (
    "fmt"
    "log"

    "github.com/abhirockzz/cosmosdb-go-sdk-helper/auth"
    "github.com/abhirockzz/cosmosdb-go-sdk-helper/common"
    "github.com/abhirockzz/cosmosdb-go-sdk-helper/query"
)

func main() {
    endpoint := "https://ACCOUNT_NAME.documents.azure.com:443"

    type Task struct {
        ID   string `json:"id"`
        Info string `json:"info"`
    }

    client, err := auth.GetCosmosDBClient(endpoint, false, nil)
    if err != nil {
        log.Fatalf("Azure AD auth failed: %v", err)
    }

    container, err := client.NewContainer(databaseName, containerName)
    if err != nil {
        log.Fatalf("NewContainer failed: %v", err)
    }

    task := Task{
        ID:   "45",
        Info: "Sample task",
    }

    insertedTask, err := common.InsertItemWithResponse(container, task, azcosmos.NewPartitionKeyString(task.ID), nil)
    if err != nil {
        log.Fatalf("InsertItem failed: %v", err)
    }
    fmt.Printf("Inserted task: %s (%s)\n", insertedTask.ID, insertedTask.Info)

    tasks, err := query.QueryItems[Task](container, sqlQuery, azcosmos.NewPartitionKey(), nil)
    if err != nil {
        log.Fatalf("QueryItems failed: %v", err)
    }
    for _, task := range tasks {
        fmt.Printf("Task: %s (%s)\n", task.ID, task.Info)
    }
}

Let's quickly go over the packages.

Authentication (`auth`)

The auth package gets authenticated Cosmos DB client handle for both Azure AD and local Cosmos DB emulator. It simplifies the process, making it easier to switch between production and local development environments.

Example:

When connecting to actual Cosmos DB endpoint, function uses DefaultAzureCredential. DefaultAzureCredential uses an ordered sequence of mechanisms for authentication (including environment variables, managed identity, Azure CLI credential etc.).

client, err := auth.GetCosmosDBClient("https://your-account.documents.azure.com:443", false, nil)
if err != nil {
    log.Fatalf("Azure AD auth failed: %v", err)
}

When using the emulator, simply set useEmulator flag to true and pass the emulator URL (e.g. http://localhost:8081) without changing anything else.

client, err := auth.GetCosmosDBClient("http://localhost:8081", true, nil)
if err != nil {
    log.Fatalf("Emulator auth failed: %v", err)
}

Database and Container Operations (`common`)

The common package lets you to create databases and containers only if they don't already exist. This is useful for idempotent resource management, especially in CI/CD pipelines. It also provides other utility functions, such as listing all databases and containers, etc.

Example:

props := azcosmos.DatabaseProperties{ID: "tododb"}
db, err := common.CreateDatabaseIfNotExists(client, props, nil)

containerProps := azcosmos.ContainerProperties{
    ID: "tasks",
    PartitionKeyDefinition: azcosmos.PartitionKeyDefinition{
        Paths: []string{"/id"},
        Kind:  azcosmos.PartitionKeyKindHash,
    },
}
container, err := common.CreateContainerIfNotExists(db, containerProps, nil)

This is also goroutine-safe (can be used with concurrent programs), so you can run it in multiple instances without worrying about race conditions since its idempotent.

Query Operations (`query`)

The query package provides generic helpers for querying multiple or single items, returning strongly-typed results. This eliminates the need for manual unmarshalling and reduces boilerplate code.

Example:

type Task struct {
    ID   string `json:"id"`
    Info string `json:"info"`
}
tasks, err := query.QueryItems[Task](container, "SELECT * FROM c", azcosmos.NewPartitionKey(), nil)

// Query a single item
task, err := query.QueryItem[Task](container, "item-id", azcosmos.NewPartitionKeyString("item-id"), nil)

Query Metrics (`metrics`)

You can use the metrics package to conveniently execute queries and the get results as a Go struct (that includes the metrics).

Example:

// Query with metrics
result, err := query.QueryItemsWithMetrics[Task](container, "SELECT * FROM c WHERE c.status = 'complete'", azcosmos.NewPartitionKey(), nil)
for i, metrics := range result.Metrics {
    fmt.Printf("Page %d: TotalExecutionTimeInMs=%f\n", i, metrics.TotalExecutionTimeInMs)
}

You can also parse the metrics string manually using ParseQueryMetrics:

qm, err := metrics.ParseQueryMetrics("totalExecutionTimeInMs=12.5;queryCompileTimeInMs=1.2;...")
fmt.Println(qm.TotalExecutionTimeInMs, qm.QueryCompileTimeInMs)

The QueryItemsWithMetrics uses ParseQueryMetrics behind the scenes to parse the metrics string.

It also provides a ParseIndexMetrics function that parses the index metrics string returned by Cosmos DB (decodes base64-encoded index metrics from query responses):

indexMetrics, err := metrics.ParseIndexMetrics("base64-encoded-index-metrics")
fmt.Println(indexMetrics)

Azure Functions Triggers (`functions/trigger`)

When using Azure Cosmos DB triggers with Azure Functions written in Go (using Custom handlers), you will need to make sense of the raw payload sent by Azure Functions. The payload contains the changed documents in a nested JSON format. The functions/trigger package simplifies this by providing helpers to parse the payload into a format you can use directly in your function.

You can use ParseToCosmosDBDataMap to directly get the Cosmos DB documents data as a []map[string]any, which is flexible and easy to work with.

Example:

// from the Azure Function trigger
payload := `{"Data":{"documents":"\"[{\\\"id\\\":\\\"dfa26d32-f876-44a3-b107-369f1f48c689\\\",\\\"description\\\":\\\"Setup monitoring\\\",\\\"_rid\\\":\\\"lV8dAK7u9cCUAAAAAAAAAA==\\\",\\\"_self\\\":\\\"dbs/lV8dAA==/colls/lV8dAK7u9cA=/docs/lV8dAK7u9cCUAAAAAAAAAA==/\\\",\\\"_etag\\\":\\\"\\\\\\\"0f007efc-0000-0800-0000-67f5fb920000\\\\\\\"\\\",\\\"_attachments\\\":\\\"attachments/\\\",\\\"_ts\\\":1744173970,\\\"_lsn\\\":160}]\""},"Metadata":{"sys":{"MethodName":"cosmosdbprocessor","UtcNow":"2025-04-09T04:46:10.723203Z","RandGuid":"0d00378b-6426-4af1-9fc0-0793f4ce3745"}}}`

docs, err := trigger.ParseToCosmosDBDataMap(payload)

Alternatively, you can use ParseToRawString to get the raw JSON string and then unmarshal it into your own struct. This is useful if you can define the structure of the data you expect and want to work with it in a more type-safe manner.

Example:

// from the Azure Function trigger
payload := `{"Data":{"documents":"\"[{\\\"id\\\":\\\"dfa26d32-f876-44a3-b107-369f1f48c689\\\",\\\"description\\\":\\\"Setup monitoring\\\",\\\"_rid\\\":\\\"lV8dAK7u9cCUAAAAAAAAAA==\\\",\\\"_self\\\":\\\"dbs/lV8dAA==/colls/lV8dAK7u9cA=/docs/lV8dAK7u9cCUAAAAAAAAAA==/\\\",\\\"_etag\\\":\\\"\\\\\\\"0f007efc-0000-0800-0000-67f5fb920000\\\\\\\"\\\",\\\"_attachments\\\":\\\"attachments/\\\",\\\"_ts\\\":1744173970,\\\"_lsn\\\":160}]\""},"Metadata":{"sys":{"MethodName":"cosmosdbprocessor","UtcNow":"2025-04-09T04:46:10.723203Z","RandGuid":"0d00378b-6426-4af1-9fc0-0793f4ce3745"}}}`

rawStringData, err := trigger.ParseToRawString(payload)

type Task struct {
    ID          string `json:"id"`
    Description string `json:"description"`
}

var documents []Task
err := json.Unmarshal([]byte(rawStringData), &documents)

Error Handling (`cosmosdb_errors`)

The cosmosdb_errors package extracts status code and message from Cosmos DB SDK errors and returns a struct for easier downstream handling.

I expect to improve/add to this.

Example:

if err != nil {
    cosmosErr := cosmosdb_errors.GetError(err)
    if cosmosErr.Status == http.StatusNotFound {
        // Handle not found
    } else {
        // Handle other errors
    }
}

Conclusion

Like I mentioned, its still early days and the cosmosdb-go-sdk-helper package provides simple convenience functions for common tasks to help reduce boilerplate. I expect to keep adding to it gradually, so if you have any suggestions or features you'd like to see, please open an issue.