Оффлайн
- Регистрация
- 1 Мар 2015
- Сообщения
- 1,481
- Баллы
- 155
When using the , I often find myself writing boilerplate code for various operations. This includes database/container operations, querying, and more. (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
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 . 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 uses an ordered sequence of mechanisms for authentication (including environment variables, managed identity, Azure CLI credential etc.).
client, err := auth.GetCosmosDBClient("", 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. ) without changing anything else.
client, err := auth.GetCosmosDBClient("", 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)
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)
indexMetrics, err := metrics.ParseIndexMetrics("base64-encoded-index-metrics")
fmt.Println(indexMetrics)
Azure Functions Triggers (functions/trigger)
When using Azure Cosmos DB triggers with (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.
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.
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.
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 . 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 uses an ordered sequence of mechanisms for authentication (including environment variables, managed identity, Azure CLI credential etc.).
client, err := auth.GetCosmosDBClient("", 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. ) without changing anything else.
client, err := auth.GetCosmosDBClient("", 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)
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)
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 (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.
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.