Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Your First Table: Console and CLI

Create a DynamoDB table in the AWS console and with the AWS CLI, write and read your first items, and see what each command and its JSON mean.

This lesson walks through the first real session you would have with DynamoDB: create a table, put a few items in, read them back and clean up. The console and CLI steps are described as read-only code, because DynamoDB cannot run in this page. Each step also has a runnable Python stand-in that models what the command does, so you can see the effect of the typed JSON and the key schema.

You need an AWS account and a configured CLI only if you want to repeat the real steps. Nothing in this course requires it.

DynamoDB on-demand tables cost money per request and per gigabyte stored. A tiny practice table costs almost nothing, but delete it when you finish, and never leave test tables with a provisioned capacity you forgot about.

Creating a table in the console

In the AWS Management Console, open DynamoDB, choose Create table and fill in:

  1. Table name: for example Books.
  2. Partition key: Isbn, type String.
  3. Sort key (optional): leave empty for now.
  4. Table settings: keep the defaults, which use on-demand capacity.

Choose Create table. The status is CREATING for a few seconds and then ACTIVE. Only an active table accepts reads and writes. The console also has an Explore items view where you can add items with a form or paste JSON.

Creating the same table with the CLI

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

aws dynamodb wait table-exists --table-name Books

The wait command polls until the table is ACTIVE. The first command prints a TableDescription JSON document with the table status, the ARN and the key schema.

The stand-in below models the one thing that really matters when you create a table: the key schema decides what every later request must supply.

Python Stand-in: create-table builds a key schema

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.

Writing items with typed JSON

The low-level DynamoDB API wraps every value in a type tag: S for string, N for number (sent as a string), BOOL, L for list, M for map and so on. The CLI uses the same format.

Terminal
aws dynamodb put-item --table-name Books --item '{
  "Isbn":   {"S": "978-1-0000-0001-1"},
  "Title":  {"S": "The Quiet Index"},
  "Pages":  {"N": "312"},
  "InStock":{"BOOL": true}
}'

Numbers are sent as strings so that no precision is lost on the wire, but they are stored and compared as numbers. The SDK document interfaces hide these tags, which you meet in the SDK chapter later.

Python Stand-in: convert plain values to typed JSON

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.

Reading items back

Terminal
aws dynamodb get-item --table-name Books \
  --key '{"Isbn": {"S": "978-1-0000-0001-1"}}'

aws dynamodb scan --table-name Books

get-item needs the full primary key and returns one item (or an empty response when nothing matches). scan reads the whole table and is fine for a few practice items but a poor habit on real data, as the scan lesson explains.

Python Stand-in: put, get and scan on a small 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.

Notice that a missing item is an empty response, not an error. Your code must check for it.

Cleaning up

Terminal
aws dynamodb delete-item --table-name Books \
  --key '{"Isbn": {"S": "978-1-0000-0001-1"}}'

aws dynamodb delete-table --table-name Books

Deleting a table removes all its items, indexes and (after a short delay) its backups configuration. Deleting is not undoable unless you took a backup first, so check the table name twice.

Region, credentials and endpoints

Every CLI call needs credentials and a region. If a command says "table not found" for a table you just created, you are very likely talking to a different region. Check aws configure get region, or pass --region explicitly. A later lesson shows how local development points the CLI at a local endpoint instead.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What must you provide when creating a table besides its name?

    You declare the primary key and the types of attributes used in keys. All other attributes are free-form.
  2. 2. In the low-level API, how is the number 312 sent?

    Numbers use the N type tag and are transmitted as strings to avoid precision loss, though DynamoDB stores them as numbers.
  3. 3. What does get-item return when no item matches the key?

    A missing item is not an error. The response simply has no Item element, so your code must handle that case.
  4. 4. A command says the table does not exist right after you created it. What is the most likely cause?

    Tables belong to a region. A mismatch between the region you created it in and the region the CLI uses is the usual culprit.

Summary

  • A table is created with a name, a key schema, attribute definitions for key attributes and a billing mode.
  • Tables are CREATING for a short time before they become ACTIVE.
  • The low-level API and CLI use typed JSON (S, N, BOOL, L, M).
  • get-item needs the full key; a missing item yields an empty response.
  • Delete practice tables when you are done to avoid cost.

Next: DynamoDB vs Relational Databases