Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Tables, Items and Attributes

Understand the three building blocks of DynamoDB: tables, items and attributes, how they compare to rows and columns, and what a table schema really fixes.

Three words carry most of DynamoDB's vocabulary: table, item and attribute. They look like the table, row and column of a relational database, and the comparison is a useful starting point. It stops being accurate quickly, though, and the places where it breaks are the places beginners trip. This lesson builds the vocabulary precisely so the later lessons on keys and queries make sense.

Tables

A table is a collection of items. You create it in one AWS region, give it a name that is unique within your account and that region, and declare its primary key. That is all the schema you provide. You do not declare other columns, types for them, or foreign keys.

Some facts worth knowing early:

  • A table lives in one region, though global tables can replicate it to several.
  • Table names are 3 to 255 characters: letters, digits, underscore, hyphen and dot.
  • A default account can create several hundred tables per region, which is far more than most applications need. Many designs use only one table per application.
  • Each table has its own capacity settings, indexes, stream and backup configuration.

Items

An item is one record in a table. It is a bag of attributes, and it is identified by its primary key: no two items in a table share the same key. Putting an item whose key already exists replaces the old one.

JSON
{
  "OrderId": "o-5001",
  "Customer": "Amina",
  "Total": 42.5,
  "Lines": [
    { "Sku": "pen", "Qty": 3 },
    { "Sku": "ink", "Qty": 1 }
  ],
  "Paid": false
}

Each item can be up to 400 KB. That sounds generous until you store arrays that grow forever, so keep unbounded lists in their own items, a pattern covered in the data modeling chapter.

Attributes

An attribute is a name and a value. The value has a type: string, number, boolean, binary, null, list, map or one of three set types (see Attribute data types). Attributes may be nested: a map can hold lists, which can hold maps, up to 32 levels deep.

Two rules matter right away:

  1. Every item must contain the key attributes, with the correct type.
  2. Every other attribute is optional and may differ from item to item.

Because of rule 2, DynamoDB tables often hold several kinds of items together. A customer, an order and an invoice can all sit in one table, told apart by their key values. That idea is the foundation of single-table design.

Comparing with relational terms

Relational DynamoDB Important difference
Database Account and region There is no "database" container to create
Table Table Only the key is declared up front
Row Item Items can have different attributes
Column Attribute Created by writing, never by ALTER TABLE
Primary key Primary key Also decides where data is stored
Foreign key, join Nothing You model relationships in the keys

A model of the schema rule

The stand-in below enforces exactly what a DynamoDB table enforces: the key attributes must be present, everything else is free. It is a teaching model, not an API client.

Python Stand-in: a table that only checks its key

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Three items, three different shapes, one table. The write without a key is rejected, which is the only validation the real service performs for you.

Several kinds of items in one table

Because attributes are free-form, a table can mix entity types. The usual technique is a Type attribute (or a prefix in the key value) so your code knows what it got back.

Python Stand-in: mixing entity types in one table

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The prefixes CUSTOMER#, ORDER# and PRODUCT# are only a naming convention. DynamoDB sees plain strings. Later lessons show how well-chosen prefixes let one query return several related item types at once.

How this looks in the real API

The real service describes a table with a key schema and attribute definitions. Only attributes used in keys or indexes appear in the definitions. This is read-only code, shown to make the vocabulary concrete.

Terminal
aws dynamodb create-table \
  --table-name Orders \
  --attribute-definitions AttributeName=OrderId,AttributeType=S \
  --key-schema AttributeName=OrderId,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

HASH marks the partition key. Notice that Customer, Total and Lines are not declared anywhere.

Common mistakes

  • Assuming a "NULL" column exists. An absent attribute and a null attribute are different things. If you write no Paid attribute, it simply is not there.
  • Treating a table like a relational database. One table per entity, with joins in application code, usually performs badly and costs more. Think about access patterns first.
  • Putting everything in one giant item. The 400 KB limit and the cost of rewriting large items make this a trap.
  • Inconsistent attribute names. Nothing stops Total in one item and total in another. Decide on a convention and a validation layer in your code.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which part of an item's shape must be declared when you create a table?

    A table schema fixes just the primary key. All other attributes are created simply by writing items that contain them.
  2. 2. What happens when you put an item whose key already exists?

    PutItem replaces the whole item unless you add a condition expression. Merging attributes is the job of UpdateItem.
  3. 3. Which statement about attributes is true?

    Only the key attributes are required. Other attributes may be missing or different in each item, and maps and lists can nest.
  4. 4. Why do many designs add a prefix like ORDER# to key values?

    Prefixes are a convention. They let different entity types live in the same table and be recognised by key value.

Summary

  • A table holds items; the only schema is its primary key.
  • An item is a set of attributes, identified by a unique key, with a size limit of 400 KB.
  • Attributes are typed values that may be nested and that differ from item to item.
  • Writing an item with an existing key replaces it.
  • One table can hold several entity types, usually separated by key conventions.

Next: Your First Table: Console and CLI