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

CreateTable

Important

This section refers to API version 2011-12-05, which is deprecated and should not be used for new applications.

For documentation on the current low-level API, see the Amazon DynamoDB API Reference.

Description

The CreateTable operation adds a new table to your account.

The table name must be unique among those associated with the AWS Account issuing the request, and the AWS region that receives the request (such as dynamodb.us-west-2.amazonaws.com). Each DynamoDB endpoint is entirely independent. For example, if you have two tables called "MyTable," one in dynamodb.us-west-2.amazonaws.com and one in dynamodb.us-west-1.amazonaws.com, they are completely independent and do not share any data.

The CreateTable operation triggers an asynchronous workflow to begin creating the table. DynamoDB immediately returns the state of the table (CREATING) until the table is in the ACTIVE state. Once the table is in the ACTIVE state, you can perform data plane operations.

Use the DescribeTables operation to check the status of the table.

Requests

Syntax

// This header is abbreviated. 
// For a sample of a complete header, see DynamoDB Low-Level API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.CreateTable 
content-type: application/x-amz-json-1.0 

{"TableName":"Table1",
    "KeySchema":
        {"HashKeyElement":{"AttributeName":"AttributeName1","AttributeType":"S"},
        "RangeKeyElement":{"AttributeName":"AttributeName2","AttributeType":"N"}},
    "ProvisionedThroughput":{"ReadCapacityUnits":5,"WriteCapacityUnits":10}
}
Name Description Required
TableName

The name of the table to create.

Allowed characters are a-z, A-Z, 0-9, '_' (underscore), '-' (dash), and '.' (dot). Names can be between 3 and 255 characters long.

Type: String

Yes
KeySchema

The primary key (simple or composite) structure for the table. A name-value pair for the HashKeyElement is required, and a name-value pair for the RangeKeyElement is optional (only required for composite primary keys). For more information about primary keys, see Primary Key.

Primary key element names can be between 1 and 255 characters long with no character restrictions.

Possible values for the AttributeType are "S" (string), "N" (numeric), or "B" (binary).

Type: Map of HashKeyElement, or HashKeyElement and RangeKeyElement for a composite primary key.

Yes
ProvisionedThroughput New throughput for the specified table, consisting of values for ReadCapacityUnits and WriteCapacityUnits. For details, see Specifying Read and Write Requirements for Tables.

Note

For current maximum/minimum values, see Limits in DynamoDB.

Type: Array

Yes
ProvisionedThroughput: ReadCapacityUnits

Sets the minimum number of consistent ReadCapacityUnits consumed per second for the specified table before DynamoDB balances the load with other operations.

Eventually consistent read operations require less effort than a consistent read operation, so a setting of 50 consistent ReadCapacityUnits per second provides 100 eventually consistent ReadCapacityUnits per second.

Type: Number

Yes
ProvisionedThroughput: WriteCapacityUnitsSets the minimum number of WriteCapacityUnits consumed per second for the specified table before DynamoDB balances the load with other operations.

Type: Number

Yes

Responses

Syntax

HTTP/1.1 200 OK
x-amzn-RequestId: CSOC7TJPLR0OOKIRLGOHVAICUFVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 311
Date: Tue, 12 Jul 2011 21:31:03 GMT

{"TableDescription":
    {"CreationDateTime":1.310506263362E9,
    "KeySchema":
        {"HashKeyElement":{"AttributeName":"AttributeName1","AttributeType":"S"},
        "RangeKeyElement":{"AttributeName":"AttributeName2","AttributeType":"N"}},
    "ProvisionedThroughput":{"ReadCapacityUnits":5,"WriteCapacityUnits":10},
    "TableName":"Table1",
    "TableStatus":"CREATING"
    }
}
Name Description
TableDescription A container for the table properties.
CreationDateTime

Date when the table was created in UNIX epoch time.

Type: Number

KeySchema

The primary key (simple or composite) structure for the table. A name-value pair for the HashKeyElement is required, and a name-value pair for the RangeKeyElement is optional (only required for composite primary keys). For more information about primary keys, see Primary Key .

Type: Map of HashKeyElement, or HashKeyElement and RangeKeyElement for a composite primary key.

ProvisionedThroughput

Throughput for the specified table, consisting of values for ReadCapacityUnits and WriteCapacityUnits. See Specifying Read and Write Requirements for Tables.

Type: Array

ProvisionedThroughput :ReadCapacityUnits

The minimum number of ReadCapacityUnits consumed per second before DynamoDB. balances the load with other operations

Type: Number

ProvisionedThroughput :WriteCapacityUnits

The minimum number of ReadCapacityUnits consumed per second before WriteCapacityUnits. balances the load with other operations

Type: Number

TableName

The name of the created table.

Type: String

TableStatus

The current state of the table (CREATING). Once the table is in the ACTIVE state, you can put data in it.

Use the DescribeTables API to check the status of the table.

Type: String

Special Errors

Error Description
ResourceInUseException Attempt to recreate an already existing table.
LimitExceededException

The number of simultaneous table requests (cumulative number of tables in the CREATING, DELETING or UPDATING state) exceeds the maximum allowed.

Note

For current maximum/minimum values, see Limits in DynamoDB.

.

Examples

The following example creates a table with a composite primary key containing a string and a number. For examples using the AWS SDK, see Working with Tables in DynamoDB.

Sample Request

// This header is abbreviated. 
// For a sample of a complete header, see DynamoDB Low-Level API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.CreateTable 
content-type: application/x-amz-json-1.0


{"TableName":"comp-table",
    "KeySchema":
        {"HashKeyElement":{"AttributeName":"user","AttributeType":"S"},
        "RangeKeyElement":{"AttributeName":"time","AttributeType":"N"}},
    "ProvisionedThroughput":{"ReadCapacityUnits":5,"WriteCapacityUnits":10}
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: CSOC7TJPLR0OOKIRLGOHVAICUFVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 311
Date: Tue, 12 Jul 2011 21:31:03 GMT

{"TableDescription":
    {"CreationDateTime":1.310506263362E9,
    "KeySchema":
        {"HashKeyElement":{"AttributeName":"user","AttributeType":"S"},
        "RangeKeyElement":{"AttributeName":"time","AttributeType":"N"}},
    "ProvisionedThroughput":{"ReadCapacityUnits":5,"WriteCapacityUnits":10},
    "TableName":"comp-table",
    "TableStatus":"CREATING"
    }
}