Table Operations

Table Operations

Overview

DynamoDbLite supports the full lifecycle of DynamoDB table management: creation with key schemas and indexes, deletion, description, listing, and updates (GSI modifications). See Working with Tables in the AWS docs.

CreateTableAsync

Creates a new table with the specified key schema, attribute definitions, and optional indexes.

Signatures

Task<CreateTableResponse> CreateTableAsync(CreateTableRequest request, CancellationToken ct = default)

Task<CreateTableResponse> CreateTableAsync(
    string tableName,
    List<KeySchemaElement> keySchema,
    List<AttributeDefinition> attributeDefinitions,
    ProvisionedThroughput provisionedThroughput,
    CancellationToken ct = default)

Parameters

• TableName (required) — name of the table to create
• KeySchema (required) — exactly one HASH key, optionally one RANGE key
• AttributeDefinitions (required) — type definitions for all key attributes (table + index keys)
• ProvisionedThroughput — read/write capacity (stored but not enforced)
• GlobalSecondaryIndexes — up to 5 GSIs (see Secondary Indexes)
• LocalSecondaryIndexes — up to 5 LSIs (must share the table's partition key)
• Tags — up to 50 key-value tags (see Tags and Admin)

Example

await client.CreateTableAsync(new CreateTableRequest
{
    TableName = "Orders",
    KeySchema =
    [
        new KeySchemaElement { AttributeName = "CustomerId", KeyType = KeyType.HASH },
        new KeySchemaElement { AttributeName = "OrderId", KeyType = KeyType.RANGE }
    ],
    AttributeDefinitions =
    [
        new AttributeDefinition { AttributeName = "CustomerId", AttributeType = ScalarAttributeType.S },
        new AttributeDefinition { AttributeName = "OrderId", AttributeType = ScalarAttributeType.S }
    ],
    ProvisionedThroughput = new ProvisionedThroughput
    {
        ReadCapacityUnits = 5,
        WriteCapacityUnits = 5
    }
});

Validation

• Key schema must have exactly one HASH key and at most one RANGE key
• All key attribute names must appear in AttributeDefinitions
• Attribute definitions must exactly cover all referenced key attributes (table + indexes)
• Duplicate table names throw ResourceInUseException
• GSI limit: 5 per table; LSI limit: 5 per table

Parity notes

• Table status is immediately ACTIVE (no CREATING phase)
• Provisioned throughput is stored but not enforced (no throttling)

DeleteTableAsync

Deletes a table and all its data, indexes, TTL configuration, and tags.

Signatures

Task<DeleteTableResponse> DeleteTableAsync(DeleteTableRequest request, CancellationToken ct = default)
Task<DeleteTableResponse> DeleteTableAsync(string tableName, CancellationToken ct = default)

Example

await client.DeleteTableAsync("Orders");

Behavior

• Deletes all items in the table
• Drops all index tables (GSI + LSI)
• Removes TTL configuration
• Removes all tags
• Throws ResourceNotFoundException if the table doesn't exist
• Deletion is synchronous — the table is gone before the call returns. The response carries TableStatus.DELETING to satisfy the DeleteTableResponse contract; no polling is needed.

DescribeTableAsync

Returns metadata about a table including key schema, indexes, item count, and size.

Signatures

Task<DescribeTableResponse> DescribeTableAsync(DescribeTableRequest request, CancellationToken ct = default)
Task<DescribeTableResponse> DescribeTableAsync(string tableName, CancellationToken ct = default)

Example

var response = await client.DescribeTableAsync("Orders");
var description = response.Table;

Console.WriteLine(description.TableName);       // "Orders"
Console.WriteLine(description.TableStatus);      // ACTIVE
Console.WriteLine(description.ItemCount);        // current item count
Console.WriteLine(description.TableSizeBytes);   // sum of item_json lengths
Console.WriteLine(description.TableArn);         // arn:aws:dynamodb:local:000000000000:table/Orders

Returned fields

Field	Description
TableName	Table name
TableStatus	Always ACTIVE
KeySchema	Partition and sort key definitions
AttributeDefinitions	Attribute type definitions
ProvisionedThroughput	Stored throughput values
CreationDateTime	When the table was created
ItemCount	Exact count (updated on every write)
TableSizeBytes	Sum of JSON payload lengths
TableArn	arn:aws:dynamodb:local:000000000000:table/{name}
GlobalSecondaryIndexes	GSI descriptions (if any)
LocalSecondaryIndexes	LSI descriptions (if any)

Parity notes

• ItemCount and TableSizeBytes are exact (DynamoDB updates these approximately every 6 hours)
• TableArn uses a local format with account 000000000000

ListTablesAsync

Returns table names with optional pagination.

Signatures

Task<ListTablesResponse> ListTablesAsync(CancellationToken ct = default)
Task<ListTablesResponse> ListTablesAsync(string exclusiveStartTableName, CancellationToken ct = default)
Task<ListTablesResponse> ListTablesAsync(string exclusiveStartTableName, int? limit, CancellationToken ct = default)
Task<ListTablesResponse> ListTablesAsync(int? limit, CancellationToken ct = default)
Task<ListTablesResponse> ListTablesAsync(ListTablesRequest request, CancellationToken ct = default)

Example

// List all tables
var response = await client.ListTablesAsync();
foreach (var name in response.TableNames)
    Console.WriteLine(name);

// Paginate with limit
var page = await client.ListTablesAsync(new ListTablesRequest { Limit = 10 });
while (page.LastEvaluatedTableName is not null)
{
    page = await client.ListTablesAsync(page.LastEvaluatedTableName, 10);
}

Parity notes

• Default limit is 100 (matches DynamoDB)
• Tables are returned in alphabetical order

UpdateTableAsync

Modifies an existing table. Supports GSI creation (with backfill), GSI deletion, and provisioned-throughput updates (accepted but not enforced).

Signatures

Task<UpdateTableResponse> UpdateTableAsync(UpdateTableRequest request, CancellationToken ct = default)
Task<UpdateTableResponse> UpdateTableAsync(string tableName, ProvisionedThroughput throughput, CancellationToken ct = default)

Example: Add a GSI

await client.UpdateTableAsync(new UpdateTableRequest
{
    TableName = "Orders",
    AttributeDefinitions =
    [
        new AttributeDefinition { AttributeName = "CustomerId", AttributeType = ScalarAttributeType.S },
        new AttributeDefinition { AttributeName = "OrderId", AttributeType = ScalarAttributeType.S },
        new AttributeDefinition { AttributeName = "Status", AttributeType = ScalarAttributeType.S }
    ],
    GlobalSecondaryIndexUpdates =
    [
        new GlobalSecondaryIndexUpdate
        {
            Create = new CreateGlobalSecondaryIndexAction
            {
                IndexName = "StatusIndex",
                KeySchema =
                [
                    new KeySchemaElement { AttributeName = "Status", KeyType = KeyType.HASH }
                ],
                Projection = new Projection { ProjectionType = ProjectionType.ALL }
            }
        }
    ]
});

Example: Delete a GSI

await client.UpdateTableAsync(new UpdateTableRequest
{
    TableName = "Orders",
    GlobalSecondaryIndexUpdates =
    [
        new GlobalSecondaryIndexUpdate
        {
            Delete = new DeleteGlobalSecondaryIndexAction { IndexName = "StatusIndex" }
        }
    ]
});

Behavior

• GSI Create: creates the index table and backfills all existing items synchronously
• GSI Delete: drops the index table and updates metadata
• Throughput Update: accepted but has no effect (no throttling)

Parity notes

• GSI creation is synchronous (no CREATING status transition)
• Backfill happens immediately within the same call
• LSIs must be defined at table creation (matches DynamoDB)

Next steps

• Item Operations — reading and writing data
• Secondary Indexes — adding GSIs and LSIs