Menu
Amazon DynamoDB
Developer Guide (API Version 2012-08-10)

The DynamoDB API

To work with DynamoDB, your application will need to use a few simple API operations. The following is a summary of these operations, organized by category.

Control Plane

Control plane operations let you create and manage DynamoDB tables. They also let you work with indexes, streams, and other objects that are dependent on tables.

  • CreateTable – Creates a new table. Optionally, you can create one or more secondary indexes, and enable DynamoDB Streams for the table.

  • DescribeTable– Returns information about a table, such as its primary key schema, throughput settings, index information, and so on.

  • ListTables – Returns the names of all of your tables in a list.

  • UpdateTable – Modifies the settings of a table or its indexes, creates or remove new indexes on a table, or modifies DynamoDB Streams settings for a table.

  • DeleteTable – Removes a table and all of its dependent objects from DynamoDB.

Data Plane

Data plane operations let you perform create, read, update, and delete (also called CRUD) actions on data in a table. Some of the data plane operations also let you read data from a secondary index.

Creating Data

  • PutItem – Writes a single item to a table. You must specify the primary key attributes, but you don't have to specify other attributes.

  • BatchWriteItem – Writes up to 25 items to a table. This is more efficient than calling PutItem multiple times because your application only needs a single network round trip to write the items. Note that you can also use BatchWriteItem for deleting multiple items from one or more tables.

Reading Data

  • GetItem – Retrieves a single item from a table. You must specify the primary key for the item that you want. You can retrieve the entire item, or just a subset of its attributes.

  • BatchGetItem – Retrieves up to 100 items from one or more tables. This is more efficient than calling GetItem multiple times because your application only needs a single network round trip to read the items.

  • Query – Retrieves all of the items that have a specific partition key. You must specify the partition key value. You can retrieve entire items, or just a subset of their attributes. Optionally, you can apply a condition to the sort key values, so that you only retrieve a subset of the data that has the same partition key. You can use this operation on a table, provided that the table has both a partition key and a sort key. You can also use this operation on an index, provided that the index has both a partition key and a sort key.

  • Scan – Retrieves all of the items in the specified table or index. You can retrieve entire items, or just a subset of their attributes. Optionally, you can apply a filtering condition to return only the values that you are interested in and discard the rest.

Updating Data

  • UpdateItem – Modifies one or more attributes in an item. You must specify the primary key for the item that you want to modify. You can add new attributes, as well as modify or remove existing attributes. You can also perform conditional updates, so that the update is only successful when a user-defined condition is met. Optionally, you can implement an atomic counter, which increments or decrements a numeric attribute without interfering with other write requests.

Deleting Data

  • DeleteItem – Deletes a single item from a table. You must specify the primary key for the item that you want to delete.

  • BatchWriteItem – Deletes up to 25 items from one or more tables. This is more efficient than calling DeleteItem multiple times because your application only needs a single network round trip to delete the items. Note that you can also use BatchWriteItem for adding multiple items to one or more tables.

DynamoDB Streams

DynamoDB Streams operations let you enable or disable a stream on a table, and allow access to the data modification records contained in a stream.

  • ListStreams – Returns a list of all your streams, or just the stream for a specific table.

  • DescribeStream – Returns information about a stream, such as its Amazon Resource Name (ARN) and where your application can begin reading the first few stream records.

  • GetShardIterator – Returns a shard iterator, which is a data structure that your application uses to retrieve the records from the stream.

  • GetRecords – Retrieves one or more stream records, using a given shard iterator.