Amazon DynamoDB
Developer Guide (API Version 2012-08-10)
Did this page help you?  Yes | No |  Tell us about it...
« 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.

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, a DynamoDB table is schema-less. 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.

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

    Name

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

    ForumName

    Subject

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

    Id

    ReplyDateTime

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

String

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 http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters.

Example

"Bicycle"

Number

Numbers are positive or negative exact-value decimals and integers. A number can have up to 38 digits of precision, 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.

Example

300

Binary

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.

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

Example

"dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"

Boolean

A Boolean type attribute can store either true or false.

Example

true

Null

Null represents an attribute with an unknown or undefined state.

Example

NULL

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.

Examples

["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).

Example

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

Note

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