Skip to main content

tables

Creates, updates, deletes, gets or lists a tables resource.

Overview​

Nametables
TypeResource
Idaws.dynamodb.tables

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
archival_summaryobjectContains information about the table archive.
attribute_definitionsarrayAn array of AttributeDefinition objects. Each of these objects describes one attribute in the table and index key schema. Each AttributeDefinition object in this array is composed of: AttributeName - The name of the attribute. AttributeType - The data type for the attribute.
billing_mode_summaryobjectContains the details for the read/write capacity mode.
creation_date_timestring (date-time)The date and time when the table was created, in UNIX epoch time format.
deletion_protection_enabledbooleanIndicates whether deletion protection is enabled (true) or disabled (false) on the table.
global_secondary_indexesarrayThe global secondary indexes, if any, on the table. Each index is scoped to a given partition key value. Each element is composed of: Backfilling - If true, then the index is currently in the backfilling phase. Backfilling occurs only when a new global secondary index is added to the table. It is the process by which DynamoDB populates the new index with data from the table. (This attribute does not appear for indexes that were created during a CreateTable operation.) You can delete an index that is being created during the Backfilling phase when IndexStatus is set to CREATING and Backfilling is true. You can't delete the index that is being created when IndexStatus is set to CREATING and Backfilling is false. (This attribute does not appear for indexes that were created during a CreateTable operation.) IndexName - The name of the global secondary index. IndexSizeBytes - The total size of the global secondary index, in bytes. DynamoDB updates this value approximately every six hours. Recent changes might not be reflected in this value. IndexStatus - The current status of the global secondary index: CREATING - The index is being created. UPDATING - The index is being updated. DELETING - The index is being deleted. ACTIVE - The index is ready for use. ItemCount - The number of items in the global secondary index. DynamoDB updates this value approximately every six hours. Recent changes might not be reflected in this value. KeySchema - Specifies the complete index key schema. The attribute names in the key schema must be between 1 and 255 characters (inclusive). The key schema must begin with the same partition key as the table. Projection - Specifies attributes that are copied (projected) from the table into the index. These are in addition to the primary key attributes and index key attributes, which are automatically projected. Each attribute specification is composed of: ProjectionType - One of the following: KEYS_ONLY - Only the index and primary keys are projected into the index. INCLUDE - In addition to the attributes described in KEYS_ONLY, the secondary index will include other non-key attributes that you specify. ALL - All of the table attributes are projected into the index. NonKeyAttributes - A list of one or more non-key attribute names that are projected into the secondary index. The total count of attributes provided in NonKeyAttributes, summed across all of the secondary indexes, must not exceed 100. If you project the same attribute into two different indexes, this counts as two distinct attributes when determining the total. This limit only applies when you specify the ProjectionType of INCLUDE. You still can specify the ProjectionType of ALL to project all attributes from the source table, even if the table has more than 100 attributes. ProvisionedThroughput - The provisioned throughput settings for the global secondary index, consisting of read and write capacity units, along with data about increases and decreases. If the table is in the DELETING state, no information about indexes will be returned.
global_table_settings_replication_modestringIndicates one of the settings synchronization modes for the global table: ENABLED: Indicates that the settings synchronization mode for the global table is enabled. DISABLED: Indicates that the settings synchronization mode for the global table is disabled. ENABLED_WITH_OVERRIDES: This mode is set by default for a same account global table. Indicates that certain global table settings can be overridden. (ENABLED, DISABLED, ENABLED_WITH_OVERRIDES)
global_table_versionstringRepresents the version of global tables in use, if the table is replicated across Amazon Web Services Regions.
global_table_witnessesarrayThe witness Region and its current status in the MRSC global table. Only one witness Region can be configured per MRSC global table.
item_countinteger (int64)The number of items in the specified table. DynamoDB updates this value approximately every six hours. Recent changes might not be reflected in this value.
key_schemaarrayThe primary key structure for the table. Each KeySchemaElement consists of: AttributeName - The name of the attribute. KeyType - The role of the attribute: HASH - partition key RANGE - sort key The partition key of an item is also known as its hash attribute. The term "hash attribute" derives from DynamoDB's usage of an internal hash function to evenly distribute data items across partitions, based on their partition key values. The sort key of an item is also known as its range attribute. The term "range attribute" derives from the way DynamoDB stores items with the same partition key physically close together, in sorted order by the sort key value. For more information about primary keys, see Primary Key in the Amazon DynamoDB Developer Guide.
latest_stream_arnstringThe Amazon Resource Name (ARN) that uniquely identifies the latest stream for this table.
latest_stream_labelstringA timestamp, in ISO 8601 format, for this stream. Note that LatestStreamLabel is not a unique identifier for the stream, because it is possible that a stream from another table might have the same timestamp. However, the combination of the following three elements is guaranteed to be unique: Amazon Web Services customer ID Table name StreamLabel
local_secondary_indexesarrayRepresents one or more local secondary indexes on the table. Each index is scoped to a given partition key value. Tables with one or more local secondary indexes are subject to an item collection size limit, where the amount of data within a given item collection cannot exceed 10 GB. Each element is composed of: IndexName - The name of the local secondary index. KeySchema - Specifies the complete index key schema. The attribute names in the key schema must be between 1 and 255 characters (inclusive). The key schema must begin with the same partition key as the table. Projection - Specifies attributes that are copied (projected) from the table into the index. These are in addition to the primary key attributes and index key attributes, which are automatically projected. Each attribute specification is composed of: ProjectionType - One of the following: KEYS_ONLY - Only the index and primary keys are projected into the index. INCLUDE - Only the specified table attributes are projected into the index. The list of projected attributes is in NonKeyAttributes. ALL - All of the table attributes are projected into the index. NonKeyAttributes - A list of one or more non-key attribute names that are projected into the secondary index. The total count of attributes provided in NonKeyAttributes, summed across all of the secondary indexes, must not exceed 100. If you project the same attribute into two different indexes, this counts as two distinct attributes when determining the total. This limit only applies when you specify the ProjectionType of INCLUDE. You still can specify the ProjectionType of ALL to project all attributes from the source table, even if the table has more than 100 attributes. IndexSizeBytes - Represents the total size of the index, in bytes. DynamoDB updates this value approximately every six hours. Recent changes might not be reflected in this value. ItemCount - Represents the number of items in the index. DynamoDB updates this value approximately every six hours. Recent changes might not be reflected in this value. If the table is in the DELETING state, no information about indexes will be returned.
multi_region_consistencystringIndicates one of the following consistency modes for a global table: EVENTUAL: Indicates that the global table is configured for multi-Region eventual consistency (MREC). STRONG: Indicates that the global table is configured for multi-Region strong consistency (MRSC). If you don't specify this field, the global table consistency mode defaults to EVENTUAL. For more information about global tables consistency modes, see Consistency modes in DynamoDB developer guide. (EVENTUAL, STRONG)
on_demand_throughputobjectThe maximum number of read and write units for the specified on-demand table. If you use this parameter, you must specify MaxReadRequestUnits, MaxWriteRequestUnits, or both.
provisioned_throughputobjectThe provisioned throughput settings for the table, consisting of read and write capacity units, along with data about increases and decreases.
replicasarrayRepresents replicas of the table.
restore_summaryobjectContains details for the restore.
sse_descriptionobjectThe description of the server-side encryption status on the specified table.
stream_specificationobjectThe current DynamoDB Streams configuration for the table.
table_arnstringThe Amazon Resource Name (ARN) that uniquely identifies the table.
table_class_summaryobjectContains details of the table class.
table_idstringA unique identifier for the table, in UUID format, generated by DynamoDB when the table is created. (pattern: <code>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}</code>)
table_namestringThe name of the table. (pattern: <code>[a-zA-Z0-9_.-]+</code>)
table_size_bytesinteger (int64)The total size of the specified table, in bytes. DynamoDB updates this value approximately every six hours. Recent changes might not be reflected in this value.
table_statusstringThe current state of the table: CREATING - The table is being created. UPDATING - The table/index configuration is being updated. The table/index remains available for data operations when UPDATING. DELETING - The table is being deleted. ACTIVE - The table is ready for use. INACCESSIBLE_ENCRYPTION_CREDENTIALS - The KMS key used to encrypt the table in inaccessible. Table operations may fail due to failure to use the KMS key. DynamoDB will initiate the table archival process when a table's KMS key remains inaccessible for more than seven days. ARCHIVING - The table is being archived. Operations are not allowed until archival is complete. ARCHIVED - The table has been archived. See the ArchivalReason for more information. (CREATING, UPDATING, DELETING, ACTIVE, INACCESSIBLE_ENCRYPTION_CREDENTIALS, ARCHIVING, ARCHIVED, REPLICATION_NOT_AUTHORIZED)
vector_indexesarrayThe vector indexes, if any, on the table. Each element is composed of: IndexName - The name of the vector index. IndexStatus - The current status of the vector index: CREATING, ACTIVE, or DELETING. Backfilling - Specifies whether the index is currently backfilling. During backfill, SearchVectors operations might return incomplete results. VectorAttribute - The attribute that contains vector embeddings. Dimensions - The number of dimensions in each vector. DistanceFunction - The distance function used to calculate similarity (COSINE, EUCLIDEAN, or DOT_PRODUCT). SearchSchema - The partition key and inline filter attributes for the vector index. Projection - Specifies attributes that are copied (projected) from the table into the vector index. IndexArn - The Amazon Resource Name (ARN) that uniquely identifies the index. IndexSizeBytes - The total size of the vector index, in bytes. Amazon DynamoDB updates this value approximately every six hours. Recent changes might not be reflected in this value. ItemCount - The number of items indexed in the vector index. Amazon DynamoDB updates this value approximately every six hours. Recent changes might not be reflected in this value.
warm_throughputobjectDescribes the warm throughput value of the base table.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_tableselectregionReturns information about the table, including the current status of the table, when it was created, the primary key schema, and any indexes on the table. If you issue a DescribeTable request immediately after a CreateTable request, DynamoDB might return a ResourceNotFoundException. This is because DescribeTable uses an eventually consistent query, and the metadata for your table might not be available at that moment. Wait for a few seconds, and then try the DescribeTable request again.
list_tablesselectregionReturns an array of table names associated with the current account and endpoint. The output from ListTables is paginated, with each page returning a maximum of 100 table names.
create_tableinsertregion, TableNameThe CreateTable operation adds a new table to your account. In an Amazon Web Services account, table names must be unique within each Region. That is, you can have two tables with same name if you create the tables in different Regions. CreateTable is an asynchronous operation. Upon receiving a CreateTable request, DynamoDB immediately returns a response with a TableStatus of CREATING. After the table is created, DynamoDB sets the TableStatus to ACTIVE. You can perform read and write operations only on an ACTIVE table. You can optionally define secondary indexes on the new table, as part of the CreateTable operation. If you want to create multiple tables with secondary indexes on them, you must create the tables sequentially. Only one table with secondary indexes can be in the CREATING state at any given time. You can use the DescribeTable action to check the table status.
update_tableupdateregion, TableNameModifies the provisioned throughput settings, global secondary indexes, or DynamoDB Streams settings for a given table. You can only perform one of the following operations at once: Modify the provisioned throughput settings of the table. Remove a global secondary index from the table. Create a new global secondary index on the table. After the index begins backfilling, you can use UpdateTable to perform other operations. UpdateTable is an asynchronous operation; while it's executing, the table status changes from ACTIVE to UPDATING. While it's UPDATING, you can't issue another UpdateTable request. When the table returns to the ACTIVE state, the UpdateTable operation is complete.
delete_tabledeleteregionThe DeleteTable operation deletes a table and all of its items. After a DeleteTable request, the specified table is in the DELETING state until DynamoDB completes the deletion. If the table is in the ACTIVE state, you can delete it. If a table is in CREATING or UPDATING states, then DynamoDB returns a ResourceInUseException. If the specified table does not exist, DynamoDB returns a ResourceNotFoundException. If table is already in the DELETING state, no error is returned. DynamoDB might continue to accept data read and write operations, such as GetItem and PutItem, on a table in the DELETING state until the table deletion is complete. For the full list of table states, see TableStatus. When you delete a table, any indexes on that table are also deleted. If you have DynamoDB Streams enabled on the table, then the corresponding stream on that table goes into the DISABLED state, and the stream is automatically deleted after 24 hours. Use the DescribeTable action to check the status of the table.
disable_kinesis_streaming_destinationexecregion, TableName, StreamArnStops replication from the DynamoDB table to the Kinesis data stream. This is done without deleting either of the resources.
enable_kinesis_streaming_destinationexecregion, TableName, StreamArnStarts table data replication to the specified Kinesis data stream at a timestamp chosen during the enable workflow. If this operation doesn't return results immediately, use DescribeKinesisStreamingDestination to check if streaming to the Kinesis data stream is ACTIVE.
export_table_to_point_in_timeexecregion, TableArn, S3BucketExports table data to an S3 bucket. The table must have point in time recovery enabled, and you can export data from any time within the point in time recovery window.
queryexecregion, TableNameYou must provide the name of the partition key attribute and a single value for that attribute. Query returns all items with that partition key value. Optionally, you can provide a sort key attribute and use a comparison operator to refine the search results. Use the KeyConditionExpression parameter to provide a specific value for the partition key. The Query operation will return all of the items from the table or index with that partition key value. You can optionally narrow the scope of the Query operation by specifying a sort key value and a comparison operator in KeyConditionExpression. To further refine the Query results, you can optionally provide a FilterExpression. A FilterExpression determines which items within the results should be returned to you. All of the other results are discarded. A Query operation always returns a result set. If no matching items are found, the result set will be empty. Queries that do not return results consume the minimum number of read capacity units for that type of read operation. DynamoDB calculates the number of read capacity units consumed based on item size, not on the amount of data that is returned to an application. The number of capacity units consumed will be the same whether you request all of the attributes (the default behavior) or just some of them (using a projection expression). The number will also be the same whether or not you use a FilterExpression. Query results are always sorted by the sort key value. If the data type of the sort key is Number, the results are returned in numeric order; otherwise, the results are returned in order of UTF-8 bytes. By default, the sort order is ascending. To reverse the order, set the ScanIndexForward parameter to false. A single Query operation will read up to the maximum number of items set (if using the Limit parameter) or a maximum of 1 MB of data and then apply any filtering to the results using FilterExpression. If LastEvaluatedKey is present in the response, you will need to paginate the result set. For more information, see Paginating the Results in the Amazon DynamoDB Developer Guide. FilterExpression is applied after a Query finishes, but before the results are returned. A FilterExpression cannot contain partition key or sort key attributes. You need to specify those attributes in the KeyConditionExpression. A Query operation can return an empty result set and a LastEvaluatedKey if all the items read for the page of results are filtered out. You can query a table, a local secondary index, or a global secondary index. For a query on a table or on a local secondary index, you can set the ConsistentRead parameter to true and obtain a strongly consistent result. Global secondary indexes support eventually consistent reads only, so do not specify ConsistentRead when querying a global secondary index.
restore_table_from_backupexecregion, TargetTableName, BackupArnCreates a new table from an existing backup. Any number of users can execute up to 50 concurrent restores (any type of restore) in a given account. You can call RestoreTableFromBackup at a maximum rate of 10 times per second. You must manually set up the following on the restored table: Auto scaling policies IAM policies Amazon CloudWatch metrics and alarms Tags Stream settings Time to Live (TTL) settings
restore_table_to_point_in_timeexecregion, TargetTableNameRestores the specified table to the specified point in time within EarliestRestorableDateTime and LatestRestorableDateTime. You can restore your table to any point in time in the last 35 days. You can set the recovery period to any value between 1 and 35 days. Any number of users can execute up to 50 concurrent restores (any type of restore) in a given account. When you restore using point in time recovery, DynamoDB restores your table data to the state based on the selected date and time (day:hour:minute:second) to a new table. Along with data, the following are also included on the new restored table using point in time recovery: Global secondary indexes (GSIs) Local secondary indexes (LSIs) Provisioned read and write capacity Encryption settings All these settings come from the current settings of the source table at the time of restore. You must manually set up the following on the restored table: Auto scaling policies IAM policies Amazon CloudWatch metrics and alarms Tags Stream settings Time to Live (TTL) settings Point in time recovery settings
scanexecregion, TableNameThe Scan operation returns one or more items and item attributes by accessing every item in a table or a secondary index. To have DynamoDB return fewer items, you can provide a FilterExpression operation. If the total size of scanned items exceeds the maximum dataset size limit of 1 MB, the scan completes and results are returned to the user. The LastEvaluatedKey value is also returned and the requestor can use the LastEvaluatedKey to continue the scan in a subsequent operation. Each scan response also includes number of items that were scanned (ScannedCount) as part of the request. If using a FilterExpression, a scan result can result in no items meeting the criteria and the Count will result in zero. If you did not use a FilterExpression in the scan request, then Count is the same as ScannedCount. Count and ScannedCount only return the count of items specific to a single scan request and, unless the table is less than 1MB, do not represent the total number of items in the table. A single Scan operation first reads up to the maximum number of items set (if using the Limit parameter) or a maximum of 1 MB of data and then applies any filtering to the results if a FilterExpression is provided. If LastEvaluatedKey is present in the response, pagination is required to complete the full table scan. For more information, see Paginating the Results in the Amazon DynamoDB Developer Guide. Scan operations proceed sequentially; however, for faster performance on a large table or secondary index, applications can request a parallel Scan operation by providing the Segment and TotalSegments parameters. For more information, see Parallel Scan in the Amazon DynamoDB Developer Guide. By default, a Scan uses eventually consistent reads when accessing the items in a table. Therefore, the results from an eventually consistent Scan may not include the latest item changes at the time the scan iterates through each item in the table. If you require a strongly consistent read of each item as the scan iterates through the items in the table, you can set the ConsistentRead parameter to true. Strong consistency only relates to the consistency of the read at the item level. DynamoDB does not provide snapshot isolation for a scan operation when the ConsistentRead parameter is set to true. Thus, a DynamoDB scan operation does not guarantee that all reads in a scan see a consistent snapshot of the table when the scan operation was requested.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Returns information about the table, including the current status of the table, when it was created, the primary key schema, and any indexes on the table. If you issue a DescribeTable request immediately after a CreateTable request, DynamoDB might return a ResourceNotFoundException. This is because DescribeTable uses an eventually consistent query, and the metadata for your table might not be available at that moment. Wait for a few seconds, and then try the DescribeTable request again.

SELECT
archival_summary,
attribute_definitions,
billing_mode_summary,
creation_date_time,
deletion_protection_enabled,
global_secondary_indexes,
global_table_settings_replication_mode,
global_table_version,
global_table_witnesses,
item_count,
key_schema,
latest_stream_arn,
latest_stream_label,
local_secondary_indexes,
multi_region_consistency,
on_demand_throughput,
provisioned_throughput,
replicas,
restore_summary,
sse_description,
stream_specification,
table_arn,
table_class_summary,
table_id,
table_name,
table_size_bytes,
table_status,
vector_indexes,
warm_throughput
FROM aws.dynamodb.tables
WHERE region = '{{ region }}' -- required
;

INSERT examples​

The CreateTable operation adds a new table to your account. In an Amazon Web Services account, table names must be unique within each Region. That is, you can have two tables with same name if you create the tables in different Regions. CreateTable is an asynchronous operation. Upon receiving a CreateTable request, DynamoDB immediately returns a response with a TableStatus of CREATING. After the table is created, DynamoDB sets the TableStatus to ACTIVE. You can perform read and write operations only on an ACTIVE table. You can optionally define secondary indexes on the new table, as part of the CreateTable operation. If you want to create multiple tables with secondary indexes on them, you must create the tables sequentially. Only one table with secondary indexes can be in the CREATING state at any given time. You can use the DescribeTable action to check the table status.

INSERT INTO aws.dynamodb.tables (
AttributeDefinitions,
TableName,
KeySchema,
LocalSecondaryIndexes,
GlobalSecondaryIndexes,
BillingMode,
ProvisionedThroughput,
StreamSpecification,
SSESpecification,
Tags,
TableClass,
DeletionProtectionEnabled,
WarmThroughput,
ResourcePolicy,
OnDemandThroughput,
GlobalTableSourceArn,
GlobalTableSettingsReplicationMode,
VectorIndexes,
region
)
SELECT 
'{{ AttributeDefinitions }}',
'{{ TableName }}' /* required */,
'{{ KeySchema }}',
'{{ LocalSecondaryIndexes }}',
'{{ GlobalSecondaryIndexes }}',
'{{ BillingMode }}',
'{{ ProvisionedThroughput }}',
'{{ StreamSpecification }}',
'{{ SSESpecification }}',
'{{ Tags }}',
'{{ TableClass }}',
{{ DeletionProtectionEnabled }},
'{{ WarmThroughput }}',
'{{ ResourcePolicy }}',
'{{ OnDemandThroughput }}',
'{{ GlobalTableSourceArn }}',
'{{ GlobalTableSettingsReplicationMode }}',
'{{ VectorIndexes }}',
'{{ region }}'
RETURNING
table_description
;

UPDATE examples​

Modifies the provisioned throughput settings, global secondary indexes, or DynamoDB Streams settings for a given table. You can only perform one of the following operations at once: Modify the provisioned throughput settings of the table. Remove a global secondary index from the table. Create a new global secondary index on the table. After the index begins backfilling, you can use UpdateTable to perform other operations. UpdateTable is an asynchronous operation; while it's executing, the table status changes from ACTIVE to UPDATING. While it's UPDATING, you can't issue another UpdateTable request. When the table returns to the ACTIVE state, the UpdateTable operation is complete.

UPDATE aws.dynamodb.tables
SET 
AttributeDefinitions = '{{ AttributeDefinitions }}',
TableName = '{{ TableName }}',
BillingMode = '{{ BillingMode }}',
ProvisionedThroughput = '{{ ProvisionedThroughput }}',
GlobalSecondaryIndexUpdates = '{{ GlobalSecondaryIndexUpdates }}',
StreamSpecification = '{{ StreamSpecification }}',
SSESpecification = '{{ SSESpecification }}',
ReplicaUpdates = '{{ ReplicaUpdates }}',
TableClass = '{{ TableClass }}',
DeletionProtectionEnabled = {{ DeletionProtectionEnabled }},
MultiRegionConsistency = '{{ MultiRegionConsistency }}',
GlobalTableWitnessUpdates = '{{ GlobalTableWitnessUpdates }}',
OnDemandThroughput = '{{ OnDemandThroughput }}',
WarmThroughput = '{{ WarmThroughput }}',
GlobalTableSettingsReplicationMode = '{{ GlobalTableSettingsReplicationMode }}',
VectorIndexUpdates = '{{ VectorIndexUpdates }}'
WHERE 
region = '{{ region }}' --required
AND TableName = '{{ TableName }}' --required
RETURNING
table_description;

DELETE examples​

The DeleteTable operation deletes a table and all of its items. After a DeleteTable request, the specified table is in the DELETING state until DynamoDB completes the deletion. If the table is in the ACTIVE state, you can delete it. If a table is in CREATING or UPDATING states, then DynamoDB returns a ResourceInUseException. If the specified table does not exist, DynamoDB returns a ResourceNotFoundException. If table is already in the DELETING state, no error is returned. DynamoDB might continue to accept data read and write operations, such as GetItem and PutItem, on a table in the DELETING state until the table deletion is complete. For the full list of table states, see TableStatus. When you delete a table, any indexes on that table are also deleted. If you have DynamoDB Streams enabled on the table, then the corresponding stream on that table goes into the DISABLED state, and the stream is automatically deleted after 24 hours. Use the DescribeTable action to check the status of the table.

DELETE FROM aws.dynamodb.tables
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Stops replication from the DynamoDB table to the Kinesis data stream. This is done without deleting either of the resources.

EXEC aws.dynamodb.tables.disable_kinesis_streaming_destination 
@region='{{ region }}' --required 
@@json=
'{
"TableName": "{{ TableName }}", 
"StreamArn": "{{ StreamArn }}", 
"EnableKinesisStreamingConfiguration": "{{ EnableKinesisStreamingConfiguration }}"
}'
;
Last updated on