Note

You are viewing the documentation for an older version of boto (boto2).

Boto3, the next version of Boto, is now stable and recommended for general use. It can be used side-by-side with Boto in the same project, so it is easy to start using Boto3 in your existing projects as well as new projects. Going forward, API updates and all new feature work will be focused on Boto3.

For more information, see the documentation for boto3.

Migrating from DynamoDB v1 to DynamoDB v2

For the v2 release of AWS’ DynamoDB, the high-level API for interacting via boto was rewritten. Since there were several new features added in v2, people using the v1 API may wish to transition their code to the new API. This guide covers the high-level APIs.

Creating New Tables

DynamoDB v1:

>>> import boto.dynamodb
>>> conn = boto.dynamodb.connect_to_region()
>>> message_table_schema = conn.create_schema(
...     hash_key_name='forum_name',
...     hash_key_proto_value=str,
...     range_key_name='subject',
...     range_key_proto_value=str
... )
>>> table = conn.create_table(
...     name='messages',
...     schema=message_table_schema,
...     read_units=10,
...     write_units=10
... )

DynamoDB v2:

>>> from boto.dynamodb2.fields import HashKey
>>> from boto.dynamodb2.fields import RangeKey
>>> from boto.dynamodb2.table import Table

>>> table = Table.create('messages', schema=[
...     HashKey('forum_name'),
...     RangeKey('subject'),
... ], throughput={
...     'read': 10,
...     'write': 10,
... })

Using an Existing Table

DynamoDB v1:

>>> import boto.dynamodb
>>> conn = boto.dynamodb.connect_to_region()
# With API calls.
>>> table = conn.get_table('messages')

# Without API calls.
>>> message_table_schema = conn.create_schema(
...     hash_key_name='forum_name',
...     hash_key_proto_value=str,
...     range_key_name='subject',
...     range_key_proto_value=str
... )
>>> table = conn.table_from_schema(
...     name='messages',
...     schema=message_table_schema)

DynamoDB v2:

>>> from boto.dynamodb2.table import Table
# With API calls.
>>> table = Table('messages')

# Without API calls.
>>> from boto.dynamodb2.fields import HashKey
>>> from boto.dynamodb2.table import Table
>>> table = Table('messages', schema=[
...     HashKey('forum_name'),
...     HashKey('subject'),
... ])

Updating Throughput

DynamoDB v1:

>>> import boto.dynamodb
>>> conn = boto.dynamodb.connect_to_region()
>>> table = conn.get_table('messages')
>>> conn.update_throughput(table, read_units=5, write_units=15)

DynamoDB v2:

>>> from boto.dynamodb2.table import Table
>>> table = Table('messages')
>>> table.update(throughput={
...     'read': 5,
...     'write': 15,
... })

Deleting a Table

DynamoDB v1:

>>> import boto.dynamodb
>>> conn = boto.dynamodb.connect_to_region()
>>> table = conn.get_table('messages')
>>> conn.delete_table(table)

DynamoDB v2:

>>> from boto.dynamodb2.table import Table
>>> table = Table('messages')
>>> table.delete()

Creating an Item

DynamoDB v1:

>>> import boto.dynamodb
>>> conn = boto.dynamodb.connect_to_region()
>>> table = conn.get_table('messages')
>>> item_data = {
...     'Body': 'http://url_to_lolcat.gif',
...     'SentBy': 'User A',
...     'ReceivedTime': '12/9/2011 11:36:03 PM',
... }
>>> item = table.new_item(
...     # Our hash key is 'forum'
...     hash_key='LOLCat Forum',
...     # Our range key is 'subject'
...     range_key='Check this out!',
...     # This has the
...     attrs=item_data
... )

DynamoDB v2:

>>> from boto.dynamodb2.table import Table
>>> table = Table('messages')
>>> item = table.put_item(data={
...     'forum_name': 'LOLCat Forum',
...     'subject': 'Check this out!',
...     'Body': 'http://url_to_lolcat.gif',
...     'SentBy': 'User A',
...     'ReceivedTime': '12/9/2011 11:36:03 PM',
... })

Getting an Existing Item

DynamoDB v1:

>>> table = conn.get_table('messages')
>>> item = table.get_item(
...     hash_key='LOLCat Forum',
...     range_key='Check this out!'
... )

DynamoDB v2:

>>> table = Table('messages')
>>> item = table.get_item(
...     forum_name='LOLCat Forum',
...     subject='Check this out!'
... )

Updating an Item

DynamoDB v1:

>>> item['a_new_key'] = 'testing'
>>> del item['a_new_key']
>>> item.put()

DynamoDB v2:

>>> item['a_new_key'] = 'testing'
>>> del item['a_new_key']

# Conditional save, only if data hasn't changed.
>>> item.save()

# Forced full overwrite.
>>> item.save(overwrite=True)

# Partial update (only changed fields).
>>> item.partial_save()

Deleting an Item

DynamoDB v1:

>>> item.delete()

DynamoDB v2:

>>> item.delete()

Querying

DynamoDB v1:

>>> import boto.dynamodb
>>> conn = boto.dynamodb.connect_to_region()
>>> table = conn.get_table('messages')
>>> from boto.dynamodb.condition import BEGINS_WITH
>>> items = table.query('Amazon DynamoDB',
...                     range_key_condition=BEGINS_WITH('DynamoDB'),
...                     request_limit=1, max_results=1)
>>> for item in items:
>>>     print item['Body']

DynamoDB v2:

>>> from boto.dynamodb2.table import Table
>>> table = Table('messages')
>>> items = table.query_2(
...     forum_name__eq='Amazon DynamoDB',
...     subject__beginswith='DynamoDB',
...     limit=1
... )
>>> for item in items:
>>>     print item['Body']

Scans

DynamoDB v1:

>>> import boto.dynamodb
>>> conn = boto.dynamodb.connect_to_region()
>>> table = conn.get_table('messages')

# All items.
>>> items = table.scan()

# With a filter.
>>> items = table.scan(scan_filter={'Replies': GT(0)})

DynamoDB v2:

>>> from boto.dynamodb2.table import Table
>>> table = Table('messages')

# All items.
>>> items = table.scan()

# With a filter.
>>> items = table.scan(replies__gt=0)

Batch Gets

DynamoDB v1:

>>> import boto.dynamodb
>>> conn = boto.dynamodb.connect_to_region()
>>> table = conn.get_table('messages')
>>> from boto.dynamodb.batch import BatchList
>>> the_batch = BatchList(conn)
>>> the_batch.add_batch(table, keys=[
...     ('LOLCat Forum', 'Check this out!'),
...     ('LOLCat Forum', 'I can haz docs?'),
...     ('LOLCat Forum', 'Maru'),
... ])
>>> results = conn.batch_get_item(the_batch)

# (Largely) Raw dictionaries back from DynamoDB.
>>> for item_dict in response['Responses'][table.name]['Items']:
...     print item_dict['Body']

DynamoDB v2:

>>> from boto.dynamodb2.table import Table
>>> table = Table('messages')
>>> results = table.batch_get(keys=[
...     {'forum_name': 'LOLCat Forum', 'subject': 'Check this out!'},
...     {'forum_name': 'LOLCat Forum', 'subject': 'I can haz docs?'},
...     {'forum_name': 'LOLCat Forum', 'subject': 'Maru'},
... ])

# Lazy requests across pages, if paginated.
>>> for res in results:
...     # You get back actual ``Item`` instances.
...     print item['Body']

Batch Writes

DynamoDB v1:

>>> import boto.dynamodb
>>> conn = boto.dynamodb.connect_to_region()
>>> table = conn.get_table('messages')
>>> from boto.dynamodb.batch import BatchWriteList
>>> from boto.dynamodb.item import Item

# You must manually manage this so that your total ``puts/deletes`` don't
# exceed 25.
>>> the_batch = BatchList(conn)
>>> the_batch.add_batch(table, puts=[
...     Item(table, 'Corgi Fanciers', 'Sploots!', {
...         'Body': 'Post your favorite corgi-on-the-floor shots!',
...         'SentBy': 'User B',
...         'ReceivedTime': '2013/05/02 10:56:45 AM',
...     }),
...     Item(table, 'Corgi Fanciers', 'Maximum FRAPS', {
...         'Body': 'http://internetvideosite/watch?v=1247869',
...         'SentBy': 'User C',
...         'ReceivedTime': '2013/05/01 09:15:25 PM',
...     }),
... ], deletes=[
...     ('LOLCat Forum', 'Off-topic post'),
...     ('LOLCat Forum', 'They be stealin mah bukket!'),
... ])
>>> conn.batch_write_item(the_writes)

DynamoDB v2:

>>> from boto.dynamodb2.table import Table
>>> table = Table('messages')

# Uses a context manager, which also automatically handles batch sizes.
>>> with table.batch_write() as batch:
...     batch.delete_item(
...         forum_name='LOLCat Forum',
...         subject='Off-topic post'
...     )
...     batch.put_item(data={
...         'forum_name': 'Corgi Fanciers',
...         'subject': 'Sploots!',
...         'Body': 'Post your favorite corgi-on-the-floor shots!',
...         'SentBy': 'User B',
...         'ReceivedTime': '2013/05/02 10:56:45 AM',
...     })
...     batch.put_item(data={
...         'forum_name': 'Corgi Fanciers',
...         'subject': 'Sploots!',
...         'Body': 'Post your favorite corgi-on-the-floor shots!',
...         'SentBy': 'User B',
...         'ReceivedTime': '2013/05/02 10:56:45 AM',
...     })
...     batch.delete_item(
...         forum_name='LOLCat Forum',
...         subject='They be stealin mah bukket!'
...     )