# aws dynamodb describe-table

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws dynamodb describe-table --table-name my-table returns a table's metadata: status, key schema, attribute types, billing mode and capacity, secondary indexes, approximate item count and size, stream settings and ARNs. It is the quickest way to find the key names you need for get-item and query.

## What the command does

It reads the table definition from the control plane. No item data is returned and no read capacity is consumed, so it is safe to run against busy production tables. Everything sits under a single `Table` object.

## Syntax

```
aws dynamodb describe-table --table-name <table-name-or-arn>
```

## Worked examples

**Key schema and attribute types**, the usual first question when a query fails:

```
aws dynamodb describe-table --table-name orders \
  --query "Table.{keys:KeySchema,types:AttributeDefinitions}"
```

`KeyType` `HASH` is the partition key, `RANGE` the sort key; `AttributeType` is `S`, `N` or `B`.

**Status, billing mode and approximate size:**

```
aws dynamodb describe-table --table-name orders \
  --query "Table.[TableStatus,BillingModeSummary.BillingMode,ItemCount,TableSizeBytes]" \
  --output text
```

**Indexes and their state**, useful while a new GSI is backfilling:

```
aws dynamodb describe-table --table-name orders \
  --query "Table.GlobalSecondaryIndexes[].[IndexName,IndexStatus,Backfilling]" \
  --output table
```

**Provisioned capacity** on a provisioned-mode table:

```
aws dynamodb describe-table --table-name orders \
  --query "Table.ProvisionedThroughput.[ReadCapacityUnits,WriteCapacityUnits]"
```

**Stream ARN** for wiring up a Lambda trigger:

```
aws dynamodb describe-table --table-name orders \
  --query "Table.LatestStreamArn" --output text
```

**Wait until a new or updated table is ready:**

```
aws dynamodb wait table-exists --table-name orders
```

## Using it in an investigation

When an application reports throttling or validation errors against a table, three answers from this command settle most of the questions. First, `KeySchema` and `AttributeDefinitions` tell you whether the code is sending the right key names and types. Second, `BillingModeSummary` and `ProvisionedThroughput` tell you whether the table can throttle on its own capacity at all, or whether you should be looking at on-demand limits and hot partitions instead. Third, the `GlobalSecondaryIndexes` list shows each index's own capacity and status; a GSI that cannot keep up throttles writes to the base table too.

Save the full output before you change anything, so you have a record of the previous settings:

```
aws dynamodb describe-table --table-name orders > orders-table-$(date +%Y%m%d%H%M).json
```

## Fields worth knowing

| Field | Meaning |
|---|---|
| `TableStatus` | `CREATING`, `UPDATING`, `DELETING`, `ACTIVE`, and states such as `INACCESSIBLE_ENCRYPTION_CREDENTIALS` or `ARCHIVED` when a KMS key has been disabled. |
| `ItemCount`, `TableSizeBytes` | Approximate. DynamoDB refreshes them roughly every six hours, so they will not reflect writes you just made. |
| `BillingModeSummary` | `PAY_PER_REQUEST` (on-demand) or `PROVISIONED`. Missing on some older tables, which means provisioned. |
| `DeletionProtectionEnabled` | If true, delete-table fails until you turn it off with update-table. |
| `StreamSpecification`, `LatestStreamArn` | Whether streams are on, which view type, and the ARN to consume. |
| `TableClassSummary` | `STANDARD` or `STANDARD_INFREQUENT_ACCESS`. |
| `Replicas` | Present for global tables, listing each replica Region and its status. |

## Gotchas

- **ResourceNotFoundException usually means the wrong Region or account**, not a deleted table; see [ResourceNotFoundException](https://cloudconsole.dev/errors/dynamodb-resourcenotfound).
- **TTL and backups are not here.** Use `aws dynamodb describe-time-to-live` and `aws dynamodb describe-continuous-backups` for those settings.
- **Output is not valid create-table input.** It contains read-only fields such as `TableStatus`, `TableArn` and `CreationDateTime`. Strip them before reusing it as a template.
- **Auto scaling settings are elsewhere.** Provisioned capacity shows the current values; the scaling targets live in Application Auto Scaling.

## Questions

### How do I find the partition key of a DynamoDB table from the CLI?

Run aws dynamodb describe-table --table-name my-table --query "Table.KeySchema". The entry with KeyType HASH is the partition key; RANGE is the sort key.

### Why is ItemCount in describe-table wrong?

It is an approximation updated about every six hours. For an exact figure run a scan with --select COUNT, which reads and bills for the whole table.

### How do I check if a DynamoDB table exists in a script?

Run describe-table and check the exit code, or use aws dynamodb wait table-exists, which polls until the table is ACTIVE and fails after its timeout.

## When this happens away from your desk

When a table starts throttling, its billing mode and indexes are the first things to check. CloudConsole is built to show DynamoDB tables and their alarms on a phone.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [aws dynamodb describe-table (AWS CLI Command Reference)](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html)
- [DescribeTable (Amazon DynamoDB API Reference)](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)

## Related

- [aws dynamodb create-table](https://cloudconsole.dev/cli/dynamodb-create-table)
- [aws dynamodb query](https://cloudconsole.dev/cli/dynamodb-query)
- [ResourceNotFoundException: Requested resource not found (DynamoDB)](https://cloudconsole.dev/errors/dynamodb-resourcenotfound)
- [aws dynamodb update-time-to-live](https://cloudconsole.dev/cli/dynamodb-update-time-to-live)
- [CloudWatch alarm for DynamoDB WriteThrottleEvents (table)](https://cloudconsole.dev/alarms/dynamodb-writethrottleevents)
- [aws dynamodb batch-write-item](https://cloudconsole.dev/cli/dynamodb-batch-write-item)

---

Source: https://cloudconsole.dev/cli/dynamodb-describe-table

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
