Amazon DynamoDB
Developer Guide (API Version 2012-08-10)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

DynamoDB Data Model

Data Model Concepts - Tables, Items, and Attributes

The DynamoDB data model concepts include tables, items and attributes.

In Amazon DynamoDB, a database is a collection of tables. A table is a collection of items and each item is a collection of attributes.

In a relational database, a table has a predefined schema such as the table name, primary key, list of its column names and their data types. All records stored in the table must have the same set of columns. DynamoDB is a NoSQL database: Except for the required primary key, an DynamoDB table is schema-less. Individual items in an DynamoDB table can have any number of attributes, although there is a limit of 64 KB on the item size. An item size is the sum of lengths of its attribute names and values (binary and UTF-8 lengths).

Each attribute in an item is a name-value pair. An attribute can be single-valued or multi-valued set. For example, a book item can have title and authors attributes. Each book has one title but can have many authors. The multi-valued attribute is a set; duplicate values are not allowed.

For example, consider storing a catalog of products in DynamoDB. You can create a table, ProductCatalog, with the Id attribute as its primary key.

ProductCatalog ( Id, ... )

You can store various kinds of product items in the table. The following table shows sample items.

Example items
   Id = 101                                       
   ProductName = "Book 101 Title"
   ISBN = "111-1111111111"
   Authors = [ "Author 1", "Author 2" ]
   Price = -2
   Dimensions = "8.5 x 11.0 x 0.5"
   PageCount = 500
   InPublication = 1
   ProductCategory = "Book" 
   Id = 201 
   ProductName = "18-Bicycle 201"
   Description = "201 description"
   BicycleType = "Road"
   Brand = "Brand-Company A"
   Price = 100
   Gender = "M"
   Color = [ "Red", "Black" ]
   ProductCategory = "Bike"
   Id = 202 
   ProductName = "21-Bicycle 202"
   Description = "202 description"
   BicycleType = "Road"
   Brand = "Brand-Company A"
   Price = 200
   Gender = "M"
   Color = [ "Green", "Black" ]
   ProductCategory = "Bike"

In the example, the ProductCatalog table has one book item and two bicycle items. Item 101 is a book with many attributes including the Authors multi-valued attribute. Item 201 and 202 are bikes, and these items have a Color multi-valued attribute. The Id is the only required attribute. Note that attribute values are shown using JSON-like syntax for illustration purposes.

DynamoDB does not allow null or empty string attribute values.

Primary Key

When you create a table, in addition to the table name, you must specify the primary key of the table. DynamoDB supports the following two types of primary keys:

  • Hash Type Primary Key—In this case the primary key is made of one attribute, a hash attribute. DynamoDB builds an unordered hash index on this primary key attribute. In the preceding example, the hash attribute for the ProductCatalog table is Id.

  • Hash and Range Type Primary Key—In this case, the primary key is made of two attributes. The first attribute is the hash attribute and the second one is the range attribute. DynamoDB builds an unordered hash index on the hash primary key attribute and a sorted range index on the range primary key attribute. For example, Amazon Web Services maintains several forums (see Discussion Forums). Each forum has many threads of discussion and each thread has many replies. You can potentially model this by creating the following three tables:

    Table NamePrimary Key TypeHash Attribute NameRange Attribute Name
    Forum ( Name, ... )Hash


    Thread (ForumName, Subject, ... )Hash and Range



    Reply ( Id, ReplyDateTime, ... )Hash and Range



    In this example, both the Thread and Reply tables have primary key of the hash and range type. For the Thread table, each forum name can have one or more subjects. In this case, ForumName is the hash attribute and Subject is the range attribute.

    The Reply table has Id as the hash attribute and ReplyDateTime as the range attribute. The reply Id identifies the thread to which the reply belongs. When designing DynamoDB tables you have to take into account the fact that DynamoDB does not support cross-table joins. For example, the Reply table stores both the forum name and subject values in the Id attribute. If you have a thread reply item, you can then parse the Id attribute to find the forum name and subject and use the information to query the Thread or the Forum tables. This developer guide uses these tables to illustrate DynamoDB functionality. For information about these tables and sample data stored in these tables, see Example Tables and Data.

Secondary Indexes

When you create a table with a hash-and-range key, you can optionally define one or more secondary indexes on that table. A secondary index lets you query the data in the table using an alternate key, in addition to queries against the primary key.

With the Reply table, you can query data items by Id (hash) or by Id and ReplyDateTime (hash and range). Now suppose you had an attribute in the table—PostedBy—with the user ID of the person who posted each reply. With a secondary index on PostedBy, you could query the data by Id (hash) and PostedBy (range). Such a query would let you retrieve all the replies posted by a particular user in a thread, with maximum efficiency and without having to access any other items.

DynamoDB supports two kinds of secondary indexes:

  • Local secondary index — an index that has the same hash key as the table, but a different range key.

  • Global secondary index — an index with a hash and range key that can be different from those on the table.

You can define up to five local secondary indexes and five global secondary indexes per table. For more information, see Improving Data Access with Secondary Indexes.

DynamoDB Data Types

Amazon DynamoDB supports the following data types:

  • Scalar data types—Number, String, and Binary.

  • Multi-valued types—String Set, Number Set, and Binary Set.

For example, in the ProductCatalog table, the Id is a number type attribute and Authors is a String Set type attribute. Note that primary key attributes can be any scalar types, but not multi-valued types.

The following are descriptions of each data type, along with examples. Note that the examples use JSON syntax.


Strings are Unicode with UTF8 binary encoding. There is no upper limit to the string size when you assign it to an attribute except when the attribute is part of the primary key. For more information, see Limits in DynamoDB. Also, the length of the attribute is constrained by the 64 KB item size limit. Note that the length of the attribute must be greater than zero.

String value comparison is used when returning ordered results in the Query and Scan APIs. Comparison is based on ASCII character code values. For example, "a" is greater that "A" , and "aa" is greater than "B". For a list of code values, see


{"S": "Bicycle"}


Numbers are positive or negative exact-value decimals and integers. A number can have up to 38 digits of precision after the decimal point, and can be between 10^-128 to 10^+126. The representation in DynamoDB is of variable length. Leading and trailing zeroes are trimmed.

Serialized numbers are sent to DynamoDB as String types, which maximizes compatibility across languages and libraries, however DynamoDB handles them as the Number type for mathematical operations.


{"N": "300"}


Binary type attributes can store any binary data, for example, compressed data, encrypted data, or images. DynamoDB treats each byte of the binary data as unsigned when it compares binary values, for example, when evaluating query expressions.

There is no upper limit to the length of the binary value when you assign it to an attribute except when the attribute is part of the primary key. For more information, see Limits in DynamoDB. Also, the length of the attribute is constrained by the 64 KB item size limit. Note that the length of the attribute must be greater than zero.

The following example is a binary attribute, using Base64-encoded text.


{"B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"}

String, Number, and Binary Sets

DynamoDB also supports number sets, string sets and binary sets. Multi-valued attributes such as Authors attribute in a book item and Color attribute of a product item are examples of string set type attributes. Because it is a set, the values in the set must be unique. Attribute sets are not ordered; the order of the values returned in a set is not preserved. DynamoDB does not support empty sets.


{"SS": ["Black","Green","Red"] }

{"NS": ["42.2","-19","7.5", "3.14"] }

{"BS": ["U3Vubnk=","UmFpbnk=","U25vd3k="] }