Operações básicas em tabelas do DynamoDB

De forma semelhante a outros sistemas de banco de dados, o Amazon DynamoDB armazena dados em tabelas. É possível gerenciar suas tabelas usando algumas operações básicas.

Criar uma tabela

Use a operação CreateTable para criar uma tabela no Amazon DynamoDB. Para criar a tabela, você deve fornecer as seguintes informações:

• Nome da tabela. O nome deve estar em conformidade com as regras de nomenclatura do DynamoDB e deve ser exclusivo para a conta atual e a região. AWS Por exemplo, você poderia criar uma tabela People no Leste dos EUA (Norte da Virgínia) e outra tabela People na Europa (Irlanda). No entanto, essas duas tabelas devem ser inteiramente diferente uma da outra. Para ter mais informações, consulte Tipos de dados compatíveis e regras de nomenclatura no Amazon DynamoDB.

• Chave primária. A chave primária pode consistir em um atributo (chave de partição) ou de dois atributos (chave de partição e chave de classificação). Você precisa fornecer os nomes de atributos, os tipos de dados e a função de cada um: HASH (para uma chave de partição) e RANGE (para uma chave de classificação). Para ter mais informações, consulte Chave primária.

• Configurações de throughput (para tabelas provisionadas). Se estiver usando o modo provisionado, você deve especificar as configurações de throughput de leitura e gravação inicial da tabela. Você pode modificar essas configurações mais tarde ou habilitar o Auto Scaling do DynamoDB para gerenciar as configurações para você. Para obter mais informações, consulte Gerenciar a capacidade de throughput automaticamente com o Auto Scaling do DynamoDB e Gerenciar configurações em tabelas com capacidade provisionada do DynamoDB.

Exemplo 1: criar uma tabela provisionada

O AWS CLI exemplo a seguir mostra como criar uma tabela (Music). A chave primária consiste em Artist (chave de partição) e SongTitle (chave de classificação), cada uma delas tem um tipo de dados de String. O throughput máximo da tabela é 10 unidades de capacidade de leitura e 5 unidades de capacidade de gravação.

aws dynamodb create-table \
    --table-name Music \
    --attribute-definitions \
        AttributeName=Artist,AttributeType=S \
        AttributeName=SongTitle,AttributeType=S \
    --key-schema \
        AttributeName=Artist,KeyType=HASH \
        AttributeName=SongTitle,KeyType=RANGE \
    --provisioned-throughput \
        ReadCapacityUnits=10,WriteCapacityUnits=5

A operação CreateTable retorna metadados para a tabela, conforme mostrado a seguir.

{
    "TableDescription": {
        "TableArn": "arn:aws:dynamodb:us-east-1:123456789012:table/Music",
        "AttributeDefinitions": [
            {
                "AttributeName": "Artist",
                "AttributeType": "S"
            },
            {
                "AttributeName": "SongTitle",
                "AttributeType": "S"
            }
        ],
        "ProvisionedThroughput": {
            "NumberOfDecreasesToday": 0,
            "WriteCapacityUnits": 5,
            "ReadCapacityUnits": 10
        },
        "TableSizeBytes": 0,
        "TableName": "Music",
        "TableStatus": "CREATING",
        "TableId": "12345678-0123-4567-a123-abcdefghijkl",
        "KeySchema": [
            {
                "KeyType": "HASH",
                "AttributeName": "Artist"
            },
            {
                "KeyType": "RANGE",
                "AttributeName": "SongTitle"
            }
        ],
        "ItemCount": 0,
        "CreationDateTime": 1542397215.37
    }
}

O elemento TableStatus indica o estado atual da tabela (CREATING). Pode demorar um pouco para criar a tabela, dependendo dos valores que você especificar para ReadCapacityUnits e WriteCapacityUnits. Valores maiores exigem que o DynamoDB aloque mais recursos para a tabela.

Exemplo 2: criar uma tabela sob demanda

Para criar a mesma tabela Music usando modo sob demanda.

aws dynamodb create-table \
    --table-name Music \
    --attribute-definitions \
        AttributeName=Artist,AttributeType=S \
        AttributeName=SongTitle,AttributeType=S \
    --key-schema \
        AttributeName=Artist,KeyType=HASH \
        AttributeName=SongTitle,KeyType=RANGE \
    --billing-mode=PAY_PER_REQUEST

A operação CreateTable retorna metadados para a tabela, conforme mostrado a seguir.

{
    "TableDescription": {
        "TableArn": "arn:aws:dynamodb:us-east-1:123456789012:table/Music",
        "AttributeDefinitions": [
            {
                "AttributeName": "Artist",
                "AttributeType": "S"
            },
            {
                "AttributeName": "SongTitle",
                "AttributeType": "S"
            }
        ],
        "ProvisionedThroughput": {
            "NumberOfDecreasesToday": 0,
            "WriteCapacityUnits": 0,
            "ReadCapacityUnits": 0
        },
        "TableSizeBytes": 0,
        "TableName": "Music",
        "BillingModeSummary": {
            "BillingMode": "PAY_PER_REQUEST"
        },
        "TableStatus": "CREATING",
        "TableId": "12345678-0123-4567-a123-abcdefghijkl",
        "KeySchema": [
            {
                "KeyType": "HASH",
                "AttributeName": "Artist"
            },
            {
                "KeyType": "RANGE",
                "AttributeName": "SongTitle"
            }
        ],
        "ItemCount": 0,
        "CreationDateTime": 1542397468.348
    }
}

Importante

Ao chamar DescribeTable em uma tabela sob demanda, as unidades de capacidade de leitura e unidades de capacidade de gravação são definidas como 0.

Exemplo 3: criar uma tabela usando a classe de tabela Standard-Infrequent Access do DynamoDB

Para criar a mesma tabela de Music usando a classe de tabela Standard-Infrequent Access (Padrão – Acesso Infrequente) do DynamoDB.

aws dynamodb create-table \
    --table-name Music \
    --attribute-definitions \
        AttributeName=Artist,AttributeType=S \
        AttributeName=SongTitle,AttributeType=S \
    --key-schema \
        AttributeName=Artist,KeyType=HASH \
        AttributeName=SongTitle,KeyType=RANGE \
    --provisioned-throughput \
        ReadCapacityUnits=10,WriteCapacityUnits=5 \
    --table-class STANDARD_INFREQUENT_ACCESS

A operação CreateTable retorna metadados para a tabela, conforme mostrado a seguir.

{
    "TableDescription": {
        "TableArn": "arn:aws:dynamodb:us-east-1:123456789012:table/Music",
        "AttributeDefinitions": [
            {
                "AttributeName": "Artist",
                "AttributeType": "S"
            },
            {
                "AttributeName": "SongTitle",
                "AttributeType": "S"
            }
        ],
        "ProvisionedThroughput": {
            "NumberOfDecreasesToday": 0,
            "WriteCapacityUnits": 5,
            "ReadCapacityUnits": 10
        },
        "TableClassSummary": {
            "LastUpdateDateTime": 1542397215.37,
            "TableClass": "STANDARD_INFREQUENT_ACCESS"
        },
        "TableSizeBytes": 0,
        "TableName": "Music",
        "TableStatus": "CREATING",
        "TableId": "12345678-0123-4567-a123-abcdefghijkl",
        "KeySchema": [
            {
                "KeyType": "HASH",
                "AttributeName": "Artist"
            },
            {
                "KeyType": "RANGE",
                "AttributeName": "SongTitle"
            }
        ],
        "ItemCount": 0,
        "CreationDateTime": 1542397215.37
    }
}

Descrever uma tabela

Para visualizar detalhes sobre uma tabela, use a operação DescribeTable. Você deve fornecer o nome da tabela. A saída de DescribeTable está no mesmo formato de CreateTable. Ela inclui o a marca de data e hora em que a tabela foi criada, o esquema de chaves, as configurações de throughput provisionado, o tamanho estimado e os índices secundários que estão presentes.

Importante

Ao chamar DescribeTable em uma tabela sob demanda, as unidades de capacidade de leitura e unidades de capacidade de gravação são definidas como 0.

exemplo

aws dynamodb describe-table --table-name Music

A tabela estará pronta para uso quando TableStatus tiver sido alterado de CREATING para ACTIVE.

nota

Se você emitir uma solicitação DescribeTable imediatamente após uma solicitação CreateTable, o DynamoDB poderá retornar um erro (ResourceNotFoundException). Isso ocorre porque DescribeTable usa uma consulta eventualmente consistente e os metadados da sua tabela podem não estar disponíveis nesse momento. Aguarde alguns segundos e, em seguida, tente a solicitação DescribeTable novamente.

Para fins de faturamento, os custos de armazenamento do DynamoDB incluem uma sobrecarga de 100 bytes por item. (Para obter mais informações, acesse a Preços do DynamoDB.) Esses 100 bytes extras por item são usados em cálculos da unidade de capacidade ou pela operação DescribeTable.

Atualizar uma tabela

A operação UpdateTable permite que você execute uma das seguintes ações:

• Modificar as configurações de throughput provisionad de uma tabela (para tabelas de modo provisionadas).

• Alterar o modo de capacidade de leitura/gravação de tabela.

• Manipular índices secundários globais na tabela (consulte Como usar índices secundários globais no DynamoDB).

• Habilite ou desabilite o DynamoDB Streams na tabela (consulte Capturar dados de alterações para o DynamoDB Streams).

exemplo

O AWS CLI exemplo a seguir mostra como modificar as configurações de taxa de transferência provisionada de uma tabela.

aws dynamodb update-table --table-name Music \
    --provisioned-throughput ReadCapacityUnits=20,WriteCapacityUnits=10

nota

Quando você emite uma solicitação UpdateTable, o status da tabela muda de AVAILABLE para UPDATING. A tabela permanecerá totalmente disponível para uso enquanto estiver UPDATING. Quando esse processo for concluído, o status da tabela mudará de UPDATING para AVAILABLE.

exemplo

O AWS CLI exemplo a seguir mostra como modificar o modo de capacidade de leitura/gravação de uma tabela para o modo sob demanda.

aws dynamodb update-table --table-name Music \
    --billing-mode PAY_PER_REQUEST

Excluir uma tabela

Você pode remover uma tabela não utilizada com a operação DeleteTable. Excluir uma tabela é uma operação irrecuperável.

exemplo

O AWS CLI exemplo a seguir mostra como excluir uma tabela.

aws dynamodb delete-table --table-name Music

Quando você emite uma solicitação DeleteTable, o status da tabela muda de ACTIVE para DELETING. A exclusão da tabela pode demorar um pouco, dependendo dos recursos que ela usa (como os dados armazenados e os streams ou índices da tabela).

Quando a operação DeleteTable é concluída, a tabela deixa de existir no DynamoDB.

Usar a proteção contra exclusão

É possível proteger uma tabela contra exclusão acidental com a propriedade de proteção contra exclusão. Habilitar essa propriedade para tabelas ajuda a garantir que elas não sejam excluídas acidentalmente durante as operações regulares de gerenciamento de tabelas pelos administradores. Isso ajudará a evitar interrupções nas operações empresariais normais.

O proprietário da tabela ou um administrador autorizado controla a propriedade de proteção contra exclusão de cada tabela. A propriedade de proteção contra exclusão de cada tabela está desativada por padrão. Isso inclui réplicas globais e tabelas restauradas com base em backups. Quando a proteção contra exclusão está desabilitada para uma tabela, ela pode ser excluída por qualquer usuário autorizado por uma política do Identity and Access Management (IAM). Quando a proteção contra exclusão está habilitada para uma tabela, ninguém pode excluí-la.

Para alterar essa configuração, acesse Configurações adicionais da tabela, navegue até o painel Proteção contra exclusão e selecione Ativar Proteção contra exclusão.

A propriedade de proteção contra exclusão é compatível com o console do DynamoDB, API, CLI/SDK e AWS CloudFormation. A API CreateTable é compatível com a propriedade de proteção contra exclusão no momento da criação da tabela, e a API UpdateTable é compatível com a alteração da propriedade de proteção contra exclusão para tabelas existentes.

nota

• Se uma AWS conta for excluída, todos os dados dessa conta, incluindo tabelas, ainda serão excluídos em 90 dias.

• Se o DynamoDB perder o acesso a uma chave gerenciada pelo cliente que foi usada para criptografar uma tabela, ela ainda será arquivada. O arquivamento requer um backup da tabela e a exclusão da original.

Nomes de tabela de listagem

A ListTables operação retorna os nomes das tabelas do DynamoDB para a conta AWS atual e a região.

exemplo

O AWS CLI exemplo a seguir mostra como listar os nomes das tabelas do DynamoDB.

aws dynamodb list-tables

Descrever cotas de throughput provisionado

A DescribeLimits operação retorna as cotas atuais de capacidade de leitura e gravação para a AWS conta corrente e a região.

exemplo

O AWS CLI exemplo a seguir mostra como descrever as cotas de taxa de transferência provisionadas atuais.

aws dynamodb describe-limits

A saída mostra as cotas superiores de unidades de capacidade de leitura e gravação para a AWS conta corrente e a região.

Para obter mais informações sobre essas cotas e como solicitar aumentos de cota, consulte Cotas padrão de throughput.