Skip to content

Commit 90a9226

Browse files
andrewmathew1Andrew Mathew
andrewmathew1
and
Andrew Mathew
authored
Added Autoscale Throughput Samples (#43619)
* added samples for autoscale throughput * removed manual autoscale sample * removed manual autoscale sample from description * got rid of concurrent throughput example * added comment suggestion --------- Co-authored-by: Andrew Mathew <andrewmathew@microsoft.com>
1 parent 09f0066 commit 90a9226

File tree

2 files changed

+552
-0
lines changed

2 files changed

+552
-0
lines changed

‎sdk/cosmos/azure-cosmos/samples/autoscale_throughput_management.py‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
# -------------------------------------------------------------------------
2+
# Copyright (c) Microsoft Corporation. All rights reserved.
3+
# Licensed under the MIT License. See License.txt in the project root for
4+
# license information.
5+
# --------------------------------------------------------------------------
6+
7+
"""
8+
FILE: autoscale_throughput_management.py
9+
10+
DESCRIPTION:
11+
This sample demonstrates how to manage autoscale throughput settings for
12+
Azure Cosmos DB databases and containers. Autoscale allows you to automatically
13+
scale throughput based on usage, providing cost optimization and performance flexibility.
14+
15+
Key concepts covered:
16+
- Creating databases and containers with autoscale throughput
17+
- Reading autoscale throughput settings
18+
- Updating autoscale maximum throughput
19+
- Understanding autoscale increment percentage
20+
21+
USAGE:
22+
python autoscale_throughput_management.py
23+
24+
Set the environment variables with your own values before running:
25+
1) ACCOUNT_HOST - the Cosmos DB account endpoint
26+
2) ACCOUNT_KEY - the Cosmos DB account primary key
27+
"""
28+
29+
import azure.cosmos.cosmos_client as cosmos_client
30+
import azure.cosmos.exceptions as exceptions
31+
from azure.cosmos.partition_key import PartitionKey
32+
from azure.cosmos import ThroughputProperties
33+
34+
import config
35+
36+
# ----------------------------------------------------------------------------------------------------------
37+
# Prerequisites -
38+
#
39+
# 1. An Azure Cosmos account -
40+
# https://docs.microsoft.com/azure/cosmos-db/create-sql-api-python#create-a-database-account
41+
#
42+
# 2. Microsoft Azure Cosmos PyPi package -
43+
# https://pypi.python.org/pypi/azure-cosmos/
44+
# ----------------------------------------------------------------------------------------------------------
45+
# Sample - demonstrates autoscale throughput management for databases and containers
46+
# ----------------------------------------------------------------------------------------------------------
47+
# Note -
48+
#
49+
# Running this sample will create (and delete) multiple Containers on your account.
50+
# Each time a Container is created the account will be billed for 1 hour of usage based on
51+
# the provisioned throughput (RU/s) of that account.
52+
# ----------------------------------------------------------------------------------------------------------
53+
54+
HOST = config.settings['host']
55+
MASTER_KEY = config.settings['master_key']
56+
DATABASE_ID = config.settings['database_id']
57+
CONTAINER_ID = config.settings['container_id']
58+
59+
60+
def create_database_with_autoscale(client, database_id):
61+
"""
62+
Create a database with autoscale throughput.
63+
Setting throughput settings, like autoscale, on a database level is *not* recommended,
64+
and should only be done if you are aware of the implications of shared throughput across containers.
65+
66+
Autoscale throughput automatically scales between 10% and 100% of the maximum throughput
67+
based on your workload demands.
68+
69+
Args:
70+
client: CosmosClient instance
71+
database_id: ID for the database
72+
"""
73+
print("\nCreate Database with Autoscale Throughput")
74+
print("=" * 70)
75+
76+
try:
77+
# Create database with autoscale - max throughput of 4000 RU/s
78+
# The database will scale between 400 RU/s (10%) and 4000 RU/s (100%)
79+
database = client.create_database(
80+
id=database_id,
81+
offer_throughput=ThroughputProperties(
82+
auto_scale_max_throughput=4000,
83+
auto_scale_increment_percent=0
84+
)
85+
)
86+
87+
print(f"Database '{database_id}' created with autoscale")
88+
print(f" - Maximum throughput: 4000 RU/s")
89+
print(f" - Minimum throughput: 400 RU/s (10% of max)")
90+
print(f" - Auto-scales based on usage between min and max")
91+
92+
return database
93+
94+
except exceptions.CosmosResourceExistsError:
95+
print(f"Database '{database_id}' already exists")
96+
return client.get_database_client(database_id)
97+
98+
99+
def create_container_with_autoscale(database, container_id):
100+
"""
101+
Create a container with autoscale throughput.
102+
103+
Container-level autoscale provides dedicated throughput for a specific container,
104+
independent of the database throughput.
105+
106+
Args:
107+
database: DatabaseProxy instance
108+
container_id: ID for the container
109+
"""
110+
print("\nCreate Container with Autoscale Throughput")
111+
print("=" * 70)
112+
113+
try:
114+
# Create container with autoscale - max throughput of 5000 RU/s
115+
# auto_scale_increment_percent=0 means default scaling behavior
116+
container = database.create_container(
117+
id=container_id,
118+
partition_key=PartitionKey(path='/id'),
119+
offer_throughput=ThroughputProperties(
120+
auto_scale_max_throughput=5000,
121+
auto_scale_increment_percent=0
122+
)
123+
)
124+
125+
print(f"Container '{container_id}' created with autoscale")
126+
print(f" - Maximum throughput: 5000 RU/s")
127+
print(f" - Minimum throughput: 500 RU/s (10% of max)")
128+
print(f" - Scales automatically based on workload")
129+
130+
return container
131+
132+
except exceptions.CosmosResourceExistsError:
133+
print(f"Container '{container_id}' already exists")
134+
return database.get_container_client(container_id)
135+
136+
137+
def read_autoscale_throughput(database, container):
138+
"""
139+
Read and display autoscale throughput settings for database and container.
140+
141+
The throughput properties reveal:
142+
- Whether autoscale is enabled
143+
- Maximum throughput setting
144+
- Current throughput (if available)
145+
146+
Args:
147+
database: DatabaseProxy instance
148+
container: ContainerProxy instance
149+
"""
150+
print("\nRead Autoscale Throughput Settings")
151+
print("=" * 70)
152+
153+
try:
154+
# Read database throughput
155+
db_offer = database.get_throughput()
156+
print(f"\nDatabase '{database.id}' throughput:")
157+
158+
autopilot_settings = db_offer.properties.get('content', {}).get('offerAutopilotSettings')
159+
if autopilot_settings:
160+
max_throughput = autopilot_settings.get('maxThroughput')
161+
print(f" - Autoscale enabled: Yes")
162+
print(f" - Maximum throughput: {max_throughput} RU/s")
163+
print(f" - Minimum throughput: {max_throughput // 10} RU/s")
164+
print(f" - Increment percent: {autopilot_settings.get('autoUpgradePolicy', {}).get('throughputPolicy', {}).get('incrementPercent', 0)}")
165+
else:
166+
throughput = db_offer.properties.get('content', {}).get('offerThroughput')
167+
print(f" - Autoscale enabled: No")
168+
print(f" - Manual throughput: {throughput} RU/s")
169+
170+
except exceptions.CosmosHttpResponseError as e:
171+
print(f"Database throughput error: {e.message}")
172+
173+
try:
174+
# Read container throughput
175+
container_offer = container.get_throughput()
176+
print(f"\nContainer '{container.id}' throughput:")
177+
178+
autopilot_settings = container_offer.properties.get('content', {}).get('offerAutopilotSettings')
179+
if autopilot_settings:
180+
max_throughput = autopilot_settings.get('maxThroughput')
181+
print(f" - Autoscale enabled: Yes")
182+
print(f" - Maximum throughput: {max_throughput} RU/s")
183+
print(f" - Minimum throughput: {max_throughput // 10} RU/s")
184+
else:
185+
throughput = container_offer.properties.get('content', {}).get('offerThroughput')
186+
print(f" - Autoscale enabled: No")
187+
print(f" - Manual throughput: {throughput} RU/s")
188+
189+
except exceptions.CosmosHttpResponseError as e:
190+
print(f"Container throughput error: {e.message}")
191+
192+
193+
def update_autoscale_max_throughput(container, new_max_throughput):
194+
"""
195+
Update the maximum throughput for an autoscale-enabled container.
196+
197+
This changes the upper limit of the autoscale range. The minimum throughput
198+
will automatically adjust to 10% of the new maximum.
199+
200+
Args:
201+
container: ContainerProxy instance
202+
new_max_throughput: New maximum throughput in RU/s
203+
"""
204+
print("\nUpdate Autoscale Maximum Throughput")
205+
print("=" * 70)
206+
207+
try:
208+
# Update autoscale max throughput
209+
new_throughput = ThroughputProperties(
210+
auto_scale_max_throughput=new_max_throughput,
211+
auto_scale_increment_percent=0
212+
)
213+
214+
updated_offer = container.replace_throughput(new_throughput)
215+
216+
autopilot_settings = updated_offer.properties.get('content', {}).get('offerAutopilotSettings')
217+
if autopilot_settings:
218+
max_throughput = autopilot_settings.get('maxThroughput')
219+
print(f"Container '{container.id}' autoscale updated:")
220+
print(f" - New maximum throughput: {max_throughput} RU/s")
221+
print(f" - New minimum throughput: {max_throughput // 10} RU/s")
222+
print(f" - Autoscale will now scale within this new range")
223+
else:
224+
print(f"Warning: Updated offer does not contain autoscale settings")
225+
226+
except exceptions.CosmosHttpResponseError as e:
227+
print(f"Error updating autoscale throughput: {e.message}")
228+
229+
def run_sample():
230+
"""
231+
Run the autoscale throughput management sample.
232+
"""
233+
print('=' * 70)
234+
print('Azure Cosmos DB - Autoscale Throughput Management Sample')
235+
print('=' * 70)
236+
237+
# Initialize client
238+
client = cosmos_client.CosmosClient(HOST, {'masterKey': MASTER_KEY})
239+
240+
try:
241+
# 1. Create database with autoscale
242+
database = create_database_with_autoscale(client, DATABASE_ID + '_autoscale')
243+
244+
# 2. Create container with autoscale
245+
container = create_container_with_autoscale(database, CONTAINER_ID + '_autoscale')
246+
247+
# 3. Read autoscale settings
248+
read_autoscale_throughput(database, container)
249+
250+
# 4. Update autoscale max throughput
251+
update_autoscale_max_throughput(container, 6000)
252+
253+
# 5. Read updated settings
254+
read_autoscale_throughput(database, container)
255+
256+
# Cleanup
257+
print("\n" + "=" * 70)
258+
print("Cleaning up resources...")
259+
print("=" * 70)
260+
261+
database.delete_container(container.id)
262+
print(f"Deleted container: {container.id}")
263+
264+
client.delete_database(database.id)
265+
print(f"Deleted database: {database.id}")
266+
267+
except exceptions.CosmosHttpResponseError as e:
268+
print(f"\nError: {e.message}")
269+
270+
print('\n' + '=' * 70)
271+
print('Sample completed!')
272+
print('=' * 70)
273+
274+
275+
if __name__ == '__main__':
276+
run_sample()

0 commit comments

Comments
 (0)