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

Naming Rules and Data Types

This section describes the DynamoDB naming rules and the various data types that DynamoDB supports.

Naming Rules

Tables, attributes, and other objects in DynamoDB must have names. Names should be meaningful and concise—for example, names such as Products, Books, and Authors are self-explanatory.

The following are the naming rules for DynamoDB:

  • All names must be encoded using UTF-8, and are case-sensitive.

  • Table names and index names must be between 3 and 255 characters long, and can contain only the following characters:

    • a-z

    • A-Z

    • 0-9

    • _ (underscore)

    • - (dash)

    • . (dot)

  • Attribute names must be between 1 and 255 characters long.

Reserved Words and Special Characters

Like many other database management systems, DynamoDB has a list of reserved words and special characters.

  • For a complete list of reserved words in DynamoDB, see Reserved Words in DynamoDB.

  • The following characters have special meanings in DynamoDB: # (hash) and : (colon)

Even though DynamoDB allows you to use these reserved words and special characters for naming purposes, we recommend that you avoid doing so because you will need to define placeholder variables whenever you use these names in an expression.

For more information, see Using Placeholders for Attribute Names and Values.

Data Types

DynamoDB supports many different data types for attributes within a table. They can be categorized as follows:

  • Scalar Types – A scalar type can represent exactly one value. The scalar types are number, string, binary, Boolean, and null.

  • Document Types – A document type can represent a complex structure with nested attributes—such as you would find in a JSON document. The document types are list and map.

  • Set Types – A set type can represent multiple scalar values. The set types are string set, number set, and binary set.

When you create a table or a secondary index, you must specify the names and data types of each primary key attribute (partition key and sort key). Furthermore, each primary key attribute must be defined as type string, number, or binary.

DynamoDB is a NoSQL database, and is schemaless, which means that, other than the primary key attributes, you do not need to define any attributes or data types at table creation time. By comparison, relational databases require you to define the names and data types of each column when you create a table.

The following are descriptions of each data type, along with examples in JSON format.

Scalar Types

The scalar types are number, string, binary, Boolean, and null.

String

Strings are Unicode with UTF-8 binary encoding. The length of a string must be greater than zero, and is constrained by the maximum DynamoDB item size limit of 400 KB.

If you define a primary key attribute as a string type attribute, the following additional constraints apply:

  • For a simple primary key, the maximum length of the first attribute value (the partition key) is 2048 bytes.

  • For a composite primary key, the maximum length of the second attribute value (the sort key) is 1024 bytes.

DynamoDB collates and compares strings using the bytes of the underlying UTF-8 string encoding. For example, "a" (0x61) is greater that "A" (0x41), and "¿" (0xC2BF) is greater than "z" (0x7A).

Example


"Bicycle"
                        

You can use the String data type to represent a date or a timestamp. One way to do this is by using ISO 8601 strings, as shown in these examples:

  • 2016-02-15

  • 2015-12-21T17:42:34Z

  • 20150311T122706Z

For more information, see http://en.wikipedia.org/wiki/ISO_8601.

Number

Numbers can be positive, negative, or zero. Numbers can have up to 38 digits precision—exceeding this will result in an exception.

  • 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 across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

Note

If number precision is important, you should pass numbers to DynamoDB using strings that you convert from number type.

Example


300
                        

You can use the Number data type to represent a date or a timestamp. One way to do this is by using epoch time—the number of seconds since 00:00:00 UTC on 1 January 1970. For example, the epoch time 1437136300 represents 12:31:40 UTC on 17 July 2015.

For more information, see http://en.wikipedia.org/wiki/Unix_time.

Binary

Binary type attributes can store any binary data, such as compressed text, encrypted data, or images. Whenever DynamoDB compares binary values, it treats each byte of the binary data as unsigned.

The length of a binary attribute must be greater than zero, and is constrained by the maximum DynamoDB item size limit of 400 KB.

If you define a primary key attribute as a binary type attribute, the following additional constraints apply:

  • For a simple primary key, the maximum length of the first attribute value (the partition key) is 2048 bytes.

  • For a composite primary key, the maximum length of the second attribute value (the sort key) is 1024 bytes.

Your applications must encode binary values in base64-encoded format before sending them to DynamoDB. Upon receipt of these values, DynamoDB decodes the data into an unsigned byte array and uses that as the length of the binary attribute.

Example

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


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
                        

Document Types

The document types are list and map. These data types can be nested within each other, to represent complex data structures up to 32 levels deep.

There is no limit on the number of values in a list or a map, as long as the item containing the values fits within the DynamoDB item size limit (400 KB).

List

A list type attribute can store an ordered collection of values. Lists are enclosed in square brackets: [ ... ]

A list is similar to a JSON array. There are no restrictions on the data types that can be stored in a list element, and the elements in a list element do not have to be of the same type.

The following example shows a list that contains two strings and a number.

Example


FavoriteThings: ["Cookies", "Coffee", 3.14159]
                    

Note

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

Map

A map type attribute can store an unordered collection of name-value pairs. Maps are enclosed in curly braces: { ... }

A map is similar to a JSON object. There are no restrictions on the data types that can be stored in a map element, and the elements in a map do not have to be of the same type.

Maps are ideal for storing JSON documents in DynamoDB. The following example shows a map that contains a string, a number, and a nested list that 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 work with individual elements within Maps, even if those elements are deeply nested. For more information, see Document Paths.

Sets

DynamoDB supports types that represent sets of Number, String, or Binary values. All of the elements within a set must be of the same type. For example, an attribute of type Number Set can only contain numbers; String Set can only contain strings; and so on.

There is no limit on the number of values in a Set, as long as the item containing the values fits within the DynamoDB item size limit (400 KB).

Each value within a set must be unique. The order of the values within a set are not preserved; therefore, your applications must not rely on any particular order of elements within the set. Finally, DynamoDB does not support empty sets.

Example (String Set, Number Set, and Binary Set)


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

[42.2, -19, 7.5, 3.14]

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