DynamoDB Core Components
In DynamoDB, tables, items, and attributes are the core components that you work with. A table is a collection of items, and each item is a collection of attributes. DynamoDB uses primary keys to uniquely identify each item in a table and secondary indexes to provide more querying flexibility. You can use DynamoDB Streams to capture data modification events in DynamoDB tables.
There are limits in DynamoDB. For more information, see Limits in DynamoDB.
Tables, Items, and Attributes
The basic DynamoDB components are:
Tables – Similar to other database systems, DynamoDB stores data in tables. A table is a collection of data. For example, see the example table called
People(shown following) that you could use to store personal contact information.
Items – Each table contains multiple items. An item is a group of attributes that is uniquely identifiable among all of the other items. Items in DynamoDB are similar in many ways to rows, records, or tuples in other database systems. In the example
Peopletable, each item represents a person.
Attributes – Each item is composed of one or more attributes. An attribute is a fundamental data element, something that does not need to be broken down any further. Attributes in DynamoDB are similar in many ways to fields or columns in other database systems. For example, an item in the example
Peopletable contains attributes called
FirstName, and so on.
The following diagram shows a table named
People with some example items and attributes.
Note the following about the
Each item in the table has a unique identifier, or primary key that distinguishes the item from all of the others in the table. In the
Peopletable, the primary key consists of one attribute (
Other than the primary key, the
Peopletable is schemaless, which means that neither the attributes nor their data types need to be defined beforehand. Each item can have its own distinct attributes.
Most of the attributes are scalar, which means that they can have only one value. Strings and numbers are common examples of scalars.
Some of the items have a nested attribute (
Address). DynamoDB supports nested attributes up to 32 levels deep.
The following is another example table named
Music that you could use to keep
track of your music collection.
Note the following about the
The primary key for
Musicconsists of two attributes (
SongTitle). Each item in the table must have these two attributes. The combination of
SongTitledistinguishes each item in the table from all of the others.
Other than the primary key, the
Musictable is schemaless, which means that neither the attributes nor their data types need to be defined beforehand. Each item can have its own distinct attributes.
One of the items has a nested attribute (
PromotionInfo), which contains other nested attributes. DynamoDB supports nested attributes up to 32 levels deep.
For more information, see Working with Tables in DynamoDB.
When you create a table, in addition to the table name, you must specify the primary key of the table. The primary key uniquely identifies each item in the table, so that no two items can have the same key.
DynamoDB supports two different kinds of primary keys:
Partition key – A simple primary key, composed of one attribute known as the partition key.
DynamoDB uses the partition key's value as input to an internal hash function. The output from the hash function determines the partition (physical storage internal to DynamoDB) in which the item will be stored.
In a table that has only a partition key, no two items can have the same partition key value.
Peopletable described in Tables, Items, and Attributes is an example of a table with a simple primary key (
PersonID). You can access any item in the
Peopletable immediately by providing the
PersonIdvalue for that item.
Partition key and sort key – Referred to as a composite primary key, this type of key is composed of two attributes. The first attribute is the partition key, and the second attribute is the sort key.
DynamoDB uses the partition key value as input to an internal hash function. The output from the hash function determines the partition (physical storage internal to DynamoDB) in which the item will be stored. All items with the same partition key are stored together, in sorted order by sort key value.
In a table that has a partition key and a sort key, it is possible for two items to have the same partition key value—however, those two items must have different sort key values.
Musictable described in Tables, Items, and Attributes is an example of a table with a composite primary key (
SongTitle). You can access any item in the
Musictable immediately, if you provide the
SongTitlevalues for that item.
A composite primary key gives you additional flexibility when querying data. For example, if you provide only the value for
Artist, DynamoDB would retrieve all of the songs by that artist. You could even provide a value for
Artistand a range of
SongTitlevalues, to retrieve only a subset of songs by a particular artist.
The partition key of an item is also known as its hash attribute. The term hash attribute derives from DynamoDB's usage of an internal hash function to evenly distribute data items across partitions, based on their partition key values.
The sort key of an item is also known as its range attribute. The term range attribute derives from the way DynamoDB stores items with the same partition key physically close together, in sorted order by the sort key value.
Each primary key attribute must be a scalar (meaning that it can only hold a single value). The only data types allowed for primary key attributes are string, number, or binary. There are no such restrictions for other, non-key attributes.
You can create one or more secondary indexes on a table. A secondary index lets you query the data in the table using an alternate key, in addition to queries against the primary key. DynamoDB does not require that you use indexes, but they give your applications more flexibility when it comes to querying your data.
DynamoDB supports two kinds of indexes:
Global secondary index – an index with a partition key and sort key that can be different from those on the table.
Local secondary index – an index that has the same partition key as the table, but a different sort key.
You can define up to 5 global secondary indexes and 5 local secondary indexes per table.
In the example
Music table shown previously, you can
query data items by
Artist (partition key) or by
SongTitle (partition key
and sort key). What if you also wanted to query the data by
AlbumTitle? To do this, you could create
an index on these attributes, and then you could query the index in much the same
way as you'd query the
The following diagram shows the example
Music table, with a new index
Note the following about the
Every index belongs to a table, which is called the base table for the index. In the preceding example,
Musicis the base table for the
DynamoDB maintains indexes automatically. When you add, update, or delete an item in the base table, DynamoDB adds, updates, or deletes the corresponding item in any indexes that belong to that table.
When you create an index, you specify which attributes will be copied, or projected, from the base table to the index. At a minimum, DynamoDB will project the key attributes from the base table into the index. This is the case with
GenreAlbumTitle, where only the key attributes from the
Musictable are projected into the index.
You can query the
GenreAlbumTitle index to find all of the
albums of a particular genre (for example, all of the
Rock albums). You can also query the
index to find all of the albums within a particular genre, but only for those with
certain album titles (for example, all of the
Country albums with titles that start with the letter
For more information, see Improving Data Access with Secondary Indexes.
DynamoDB Streams is an optional feature that captures data modification events in DynamoDB tables. The data about these events appear in the stream in near real time, and in the order that the events occurred.
Each event is represented by a stream record. If you enable a stream on a table, DynamoDB Streams will write a stream record whenever one of the following events occurs:
If a new item is added to the table, the stream captures an image of the entire item, including all of its attributes.
If an item is updated, the stream captures the "before" and "after" image of any attributes that were modified in the item.
If an item is deleted from the table, the stream captures an image of the entire item before it was deleted.
Each stream record also contains the name of the table, the event timestamp, and other metadata. Stream records have a lifetime of 24 hours; after that, they are automatically removed from the stream.
You can use DynamoDB Streams together with AWS Lambda to create a
trigger—code that executes automatically whenever an
event of interest appears in a stream. For example, consider a
Customers table that contains customer information for a
company. Suppose you want to send an email to each new customer, to welcome them.
You could enable a stream on that table, and then associate the stream with a Lambda
function. The Lambda function would execute whenever a new stream record appears, but
only process new items added to the
Customers table. For any
item that has an
EmailAddress attribute, the Lambda function
would invoke Amazon Simple Email Service (Amazon SES) to send an email to that address.
The following diagram illustrates this scenario.
In this example, note that the last customer, Craig Roe, will not
receive an email because he does not have an
In addition to triggers, DynamoDB Streams enables powerful solutions such as data replication within and across AWS regions, materialized views of data in DynamoDB tables, data analysis using Amazon Kinesis materialized views, and much more.
For more information, see Capturing Table Activity with DynamoDB Streams.