Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

CreateTable method

Written by
Updated at April 24, 2026
View in Markdown

Creates a new table.

The method is asynchronous.
This means it changes a table status to CREATING and immediately returns the result. However, the table is actually being created in the background, and you can only use it after it becomes ACTIVE.

Request

The request contains data in JSON format.

{
   "AttributeDefinitions": [
      {
         "AttributeName": "string",
         "AttributeType": "string"
      }
   ],
   "BillingMode": "string",
   "GlobalSecondaryIndexes": [
      {
         "IndexName": "string",
         "KeySchema": [
            {
               "AttributeName": "string",
               "KeyType": "string"
            }
         ],
         "Projection": {
            "NonKeyAttributes": [ "string" ],
            "ProjectionType": "string"
         }
      }
   ],
   "KeySchema": [
      {
         "AttributeName": "string",
         "KeyType": "string"
      }
   ],
   "StreamSpecification": {
         "StreamEnabled": boolean,
         "StreamViewType": "string"
   },
    "TableName": "string"
}

Parameters

Parameter Description
AttributeDefinitions Array of attributes describing the key schema for the table and indexes.

Type: Array of AttributeDefinition type objects.
Required: Yes
GlobalSecondaryIndexes Array of attributes describing one or multiple global secondary indexes to create in the table. Each item consists of:
  • IndexName: It must be unique and at least three characters long. This is a required parameter.
  • KeySchema: Attributes that make up the index primary key.
  • Projection: Specifies attributes copied from the table into the index. Currently, the only supported ProjectionType is ALL.
  • NonKeyAttributes: List of one or multiple non-key attribute names that are projected to the secondary index.

Required: No
KeySchema Attributes that make up the primary key. These attributes should also be specified in AttributeDefinitions.
Each item consists of:
  • AttributeName.
  • KeyType: Key attribute role:
    • HASH: Partition key.
    • RANGE: Sort key.
For a simple primary key (partition key), specify only one attribute with the HASH role.
For a composite primary key (partition key + sort key), specify two attributes: the first one with the HASH role and the second with the RANGE role.

Type: Array of KeySchemaElement type objects.
Length: 1 to 2 items.
Required: Yes
StreamSpecification Description of the change data feed settings for a table:
  • StreamEnabled defines whether change data capture for the table is enabled.
  • StreamViewType defines the CDC type:
    • KEYS_ONLY: Only the primary key components and the change flag are written.
    • NEW_IMAGE: Any column values resulting from changes are written.
    • OLD_IMAGE: Any column values before changes are written.
    • NEW_AND_OLD_IMAGES: Combination of the NEW_IMAGE and OLD_IMAGE modes. Writes the values of all columns before and after the update.

    • Type: Object of the StreamSpecification type.
    Required: No
TableName Table name.
It may contain a path in the hierarchical directory structure in path/to/table format.

Type: String
Length: 3 to 255 characters.
Template: [a-zA-Z0-9_.-]+
Required: Yes

Response

If successful, HTTP code 200 is returned.
You will get data in JSON format.

{
   "TableDescription": {
      "ArchivalSummary": {
         "ArchivalBackupArn": "string",
         "ArchivalDateTime": number,
         "ArchivalReason": "string"
      },
      "AttributeDefinitions": [
         {
            "AttributeName": "string",
            "AttributeType": "string"
         }
      ],
      "BillingModeSummary": {
         "BillingMode": "string",
         "LastUpdateToPayPerRequestDateTime": number
      },
      "CreationDateTime": number,      
      "GlobalTableVersion": "string",
      "ItemCount": number,
      "KeySchema": [
         {
            "AttributeName": "string",
            "KeyType": "string"
         }
      ],
      "LatestStreamArn": "string",
      "LatestStreamLabel": "string",     
      "Replicas": [
         {             
            "KMSMainKeyId": "string",            
            "RegionName": "string",
            "ReplicaStatus": "string",
            "ReplicaStatusDescription": "string",
            "ReplicaStatusPercentProgress": "string"
         }
      ],
      "RestoreSummary": {
         "RestoreDateTime": number,
         "RestoreInProgress": boolean,
         "SourceBackupArn": "string",
         "SourceTableArn": "string"
      },
      "SSEDescription": {
         "InaccessibleEncryptionDateTime": number,
         "KMSMainKeyArn": "string",
         "SSEType": "string",
         "Status": "string"
      },
      "StreamSpecification": {
          "StreamEnabled": boolean,
          "StreamViewType": "string"
      },
      "TableArn": "string",
      "TableId": "string",
      "TableName": "string",
      "TableSizeBytes": number,
      "TableStatus": "string"
   }
}

Parameters

Parameter Description
TableDescription Properties of the created table.

Type: TableDescription type object.

Errors

Parameter Description
InternalServerError An internal error occurred on the server side.

HTTP status code: 500
LimitExceededException Table operations limit exceeded.
You can concurrently perform up to 50 operations on tables, including CreateTable, UpdateTable, DeleteTable, UpdateTimeToLive, RestoreTableFromBackup, and RestoreTableToPointInTime.

HTTP status code: 400
ResourceInUseException Attempting to create a table with the existing name.

HTTP status code: 400

There may be some common errors as well shared by all methods.

Previous
BatchWriteItem
Next
DeleteItem