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

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. In contrast, DynamoDB only requires that a table has a primary key, but does not require you to define all of the attribute names and data types in advance. Individual items in a DynamoDB table can have any number of attributes, although there is a limit of 400 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. The primary key uniquely identifies each item, so that no two products in the table can have the same Id.

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.

Primary Key

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 the following two types of primary keys:

  • Hash Type Primary Key—The primary key is made of one attribute, a hash attribute. DynamoDB builds an unordered hash index on this primary key attribute. Each item in the table is uniquely identified by its hash key value.

  • Hash and Range Type Primary Key—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. Each item in the table is uniquely identified by the combination of its hash and range key values. It is possible for two items to have the same hash key value, but those two items must have different range key values.

You must define the data type for each primary key attribute: String, Number, or Binary.

Different applications will have different requirements for tables and primary keys. 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 could 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 5 global secondary indexes and 5 local secondary indexes per table. For more information, see Improving Data Access with Secondary Indexes in DynamoDB.

DynamoDB Data Types

Amazon DynamoDB supports the following data types:

  • Scalar types – Number, String, Binary, Boolean, and Null.

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

  • Document types – List and Map.

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 must be of type String, Number, or Binary.

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

Scalar Data Types


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 400 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 API actions. 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




Numbers can have up to 38 digits precision, and can be positive, negative, or zero.

  • Positive range: 1E-130 to 9.9999999999999999999999999999999999999E+125

  • Negative range: -9.9999999999999999999999999999999999999E+125 to -1E-130

In DynamoDB, numbers are represented as variable length. Leading and trailing zeroes are trimmed.

All 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.


If number precision is important, you should pass numbers to DynamoDB using strings that you convert from a number type. DynamoDB limits numbers to 38 digits. More than 38 digits will cause an error.




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 400 KB item size limit. Note that the length of the attribute must be greater than zero.

Client applications must encode binary values in base64 format. When DynamoDB receives the data from the client, it decodes the data into an unsigned byte array and uses that as the length of the attribute.

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




A Boolean type attribute can store either true or false.




Null represents an attribute with an unknown or undefined state.



Multi-Valued Data Types

DynamoDB also supports types that represent number sets, string sets and binary sets. Multi-valued attributes such as an Authors attribute in a book item and a Color attribute of a product item are examples of String Set type attributes. Because each of these types is a set, the values in each 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.


["Black", "Green" ,"Red"]

["42.2", "-19", "7.5", "3.14"]

["U3Vubnk=", "UmFpbnk=", "U25vd3k="]

Document Data Types

DynamoDB supports List and Map data types, which can be nested to represent complex data structures.

  • A List type contains an ordered collection of values.

  • A Map type contains an unordered collection of name-value pairs.

Lists and maps are ideal for storing JSON documents. The List data type is similar to a JSON array, and the Map data type is similar to a JSON object. There are no restrictions on the data types that can be stored in List or Map elements, and the elements do not have to be of the same type.

The following example shows a Map that contains a String, a Number, and a nested List (which itself contains another Map).


    Day: "Monday",
    UnreadEmails: 42,
    ItemsOnMyDesk: [
        "Coffee Cup",
            Pens: { Quantity : 3},
            Pencils: { Quantity : 2},
            Erasers: { Quantity : 1}


DynamoDB lets you access individual elements within lists and arrays, even if those elements are deeply nested. For more information, see Document Paths.