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

throughput.mddocs/

Throughput Management

Throughput management allows you to configure and manage Request Units (RU/s) provisioning for databases and containers in manual or autoscale mode.

ThroughputProperties Type

type ThroughputProperties struct {
    // ETag contains the entity etag of the throughput information.
    ETag *azcore.ETag
    // LastModified contains the last modified time of the throughput information.
    LastModified time.Time

    // Has unexported fields.
}

Describes the throughput configuration of a resource. Must be initialized through the available constructors.

Throughput Constructors

NewManualThroughputProperties

func NewManualThroughputProperties(throughput int32) ThroughputProperties

Returns a ThroughputProperties object configured for manual (provisioned) throughput.

Parameters:

  • throughput - The provisioned throughput in RU/s (minimum 400, increments of 100)

Returns: ThroughputProperties configured for manual mode

NewAutoscaleThroughputProperties

func NewAutoscaleThroughputProperties(startingMaxThroughput int32) ThroughputProperties

Returns a ThroughputProperties object configured for autoscale mode.

Parameters:

  • startingMaxThroughput - The maximum throughput in RU/s (minimum 1000, increments of 1000)

Returns: ThroughputProperties configured for autoscale mode

NewAutoscaleThroughputPropertiesWithIncrement

func NewAutoscaleThroughputPropertiesWithIncrement(startingMaxThroughput int32, incrementPercentage int32) ThroughputProperties

Returns a ThroughputProperties object configured for autoscale mode with auto-upgrade increment.

Parameters:

  • startingMaxThroughput - The maximum throughput in RU/s
  • incrementPercentage - The auto upgrade max throughput increment percentage

Returns: ThroughputProperties configured for autoscale with increment

ThroughputProperties Methods

ManualThroughput

func (tp *ThroughputProperties) ManualThroughput() (int32, bool)

Returns the provisioned throughput in manual mode.

Returns:

  • int32 - The throughput value in RU/s
  • bool - True if configured for manual mode, false otherwise

AutoscaleMaxThroughput

func (tp *ThroughputProperties) AutoscaleMaxThroughput() (int32, bool)

Returns the configured max throughput on autoscale mode.

Returns:

  • int32 - The maximum throughput value in RU/s
  • bool - True if configured for autoscale mode, false otherwise

AutoscaleIncrement

func (tp *ThroughputProperties) AutoscaleIncrement() (int32, bool)

Returns the configured percent increment on autoscale mode.

Returns:

  • int32 - The increment percentage
  • bool - True if increment is configured, false otherwise

MarshalJSON

func (tp *ThroughputProperties) MarshalJSON() ([]byte, error)

Implements the json.Marshaler interface.

UnmarshalJSON

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

Implements the json.Unmarshaler interface.

Response and Options Types

ThroughputResponse

type ThroughputResponse struct {
    // ThroughputProperties contains the unmarshalled response body in ThroughputProperties format.
    ThroughputProperties *ThroughputProperties
    Response
    // IsReplacePending returns the state of a throughput update.
    IsReplacePending bool
    // MinThroughput is minimum throughput in measurement of request units per second in the Azure Cosmos service.
    MinThroughput *int32
}

Response from a throughput operation.

Fields:

  • ThroughputProperties - The throughput configuration
  • IsReplacePending - True if a throughput update is in progress
  • MinThroughput - The minimum allowed throughput for the resource
  • Response - Base response fields (request charge, activity ID)

ThroughputOptions

type ThroughputOptions struct {
    // IfMatchEtag If-Match (ETag) associated with the request.
    IfMatchEtag *azcore.ETag
    // IfNoneMatchEtag If-None-Match (ETag) associated with the request.
    IfNoneMatchEtag *azcore.ETag
}

Options for throughput operations including conditional requests.

Throughput Operations

Database Throughput Operations

ReadThroughput

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

Retrieves the provisioned throughput information for the database.

ReplaceThroughput

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

Updates the provisioned throughput for the database.

Container Throughput Operations

ReadThroughput

func (c *ContainerClient) ReadThroughput(
    ctx context.Context,
    o *ThroughputOptions) (ThroughputResponse, error)

Retrieves the provisioned throughput information for the container.

ReplaceThroughput

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

Updates the provisioned throughput for the container.

Usage Examples

Create Database with Manual Throughput

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

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

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)
}

fmt.Printf("Created database with 400 RU/s\n")

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)
}

fmt.Printf("Created database with autoscale max 4000 RU/s\n")

Create Container with Manual Throughput

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

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

containerProperties := azcosmos.ContainerProperties{
    ID: "items",
    PartitionKeyDefinition: azcosmos.PartitionKeyDefinition{
        Paths: []string{"/category"},
    },
}

response, err := database.CreateContainer(context.Background(), containerProperties, options)
if err != nil {
    panic(err)
}

fmt.Printf("Created container with 400 RU/s\n")

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)
}

fmt.Printf("Minimum throughput: %d RU/s\n", *throughputResponse.MinThroughput)

Read Container Throughput

container, _ := database.NewContainer("items")

throughputResponse, err := container.ReadThroughput(context.Background(), nil)
if err != nil {
    panic(err)
}

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

Update Database Throughput (Scale Up)

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

// Scale 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 database throughput to 1000 RU/s\n")
fmt.Printf("RU charge: %f\n", response.RequestCharge)

Update Container Throughput (Scale Down)

container, _ := database.NewContainer("items")

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

fmt.Printf("Updated container throughput to 400 RU/s\n")

Convert Manual to Autoscale

container, _ := database.NewContainer("items")

// Convert from manual to autoscale with max 4000 RU/s
autoscaleThroughput := azcosmos.NewAutoscaleThroughputProperties(4000)
response, err := container.ReplaceThroughput(context.Background(), autoscaleThroughput, nil)
if err != nil {
    panic(err)
}

fmt.Printf("Converted to autoscale mode\n")

Convert Autoscale to Manual

container, _ := database.NewContainer("items")

// Convert from autoscale to manual 1000 RU/s
manualThroughput := azcosmos.NewManualThroughputProperties(1000)
response, err := container.ReplaceThroughput(context.Background(), manualThroughput, nil)
if err != nil {
    panic(err)
}

fmt.Printf("Converted to manual mode\n")

Update Autoscale Max Throughput

container, _ := database.NewContainer("items")

// Increase autoscale max from 4000 to 10000 RU/s
newAutoscale := azcosmos.NewAutoscaleThroughputProperties(10000)
response, err := container.ReplaceThroughput(context.Background(), newAutoscale, nil)
if err != nil {
    panic(err)
}

fmt.Printf("Updated autoscale max to 10000 RU/s\n")

Check Throughput Update Status

container, _ := database.NewContainer("items")

throughputResponse, err := container.ReadThroughput(context.Background(), nil)
if err != nil {
    panic(err)
}

if throughputResponse.IsReplacePending {
    fmt.Printf("Throughput update in progress...\n")
} else {
    fmt.Printf("Throughput update complete\n")
}

Autoscale with Increment Percentage

// Create with auto-upgrade increment
throughput := azcosmos.NewAutoscaleThroughputPropertiesWithIncrement(4000, 10)
options := &azcosmos.CreateDatabaseOptions{
    ThroughputProperties: &throughput,
}

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

fmt.Printf("Created with autoscale and 10%% auto-upgrade increment\n")

Shared Database Throughput

// Create database with throughput
throughput := azcosmos.NewManualThroughputProperties(1000)
options := &azcosmos.CreateDatabaseOptions{
    ThroughputProperties: &throughput,
}

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

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

// Create container without throughput (shares database throughput)
containerProperties := azcosmos.ContainerProperties{
    ID: "items",
    PartitionKeyDefinition: azcosmos.PartitionKeyDefinition{
        Paths: []string{"/category"},
    },
}

containerResponse, err := database.CreateContainer(context.Background(), containerProperties, nil)
if err != nil {
    panic(err)
}

fmt.Printf("Container shares database throughput\n")

Dedicated Container Throughput

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

// Create container with dedicated throughput
throughput := azcosmos.NewManualThroughputProperties(400)
options := &azcosmos.CreateContainerOptions{
    ThroughputProperties: &throughput,
}

containerProperties := azcosmos.ContainerProperties{
    ID: "dedicatedItems",
    PartitionKeyDefinition: azcosmos.PartitionKeyDefinition{
        Paths: []string{"/category"},
    },
}

response, err := database.CreateContainer(context.Background(), containerProperties, options)
if err != nil {
    panic(err)
}

fmt.Printf("Container has dedicated 400 RU/s throughput\n")

Throughput Planning Example

// Calculate required throughput based on workload
// Rule of thumb: 1 RU ≈ 1 KB document read
// 1 RU ≈ 5-10 KB document write

expectedReadsPerSec := 100
expectedWritesPerSec := 50
avgDocSizeKB := 5

// Rough estimate
readRUs := expectedReadsPerSec * 1
writeRUs := expectedWritesPerSec * (avgDocSizeKB / 5)
totalRUs := readRUs + writeRUs

// Add buffer (20%)
requiredRUs := int32(float64(totalRUs) * 1.2)

// Round up to nearest 100
requiredRUs = ((requiredRUs + 99) / 100) * 100

// Ensure minimum 400 RU/s
if requiredRUs < 400 {
    requiredRUs = 400
}

fmt.Printf("Recommended throughput: %d RU/s\n", requiredRUs)

throughput := azcosmos.NewManualThroughputProperties(requiredRUs)
// Use throughput for database or container creation

Dynamic Throughput Scaling

container, _ := database.NewContainer("items")

// Monitor request charge and scale accordingly
response, _ := container.ReadItem(context.Background(), pk, "item1", nil)
fmt.Printf("Request charge: %f RU\n", response.RequestCharge)

// If experiencing rate limiting (429 errors), scale up
throughputResp, _ := container.ReadThroughput(context.Background(), nil)
currentRUs, _ := throughputResp.ThroughputProperties.ManualThroughput()

if currentRUs < 1000 {
    newThroughput := azcosmos.NewManualThroughputProperties(currentRUs + 100)
    container.ReplaceThroughput(context.Background(), newThroughput, nil)
    fmt.Printf("Scaled up to %d RU/s\n", currentRUs+100)
}