Todos os produtos
Search
Central de documentação

Tablestore:Write data

Última atualização: Jul 03, 2026

O Tablestore oferece três operações para gravar dados em tabelas: PutRow, UpdateRow e BatchWriteRow.

Nota

As linhas são as unidades básicas das tabelas. Cada linha consiste em colunas de chave primária e colunas de atributo opcionais. Os nomes e tipos das colunas de chave primária são idênticos em todas as linhas de uma tabela, enquanto as colunas de atributo podem variar entre linhas. Para mais informações, consulte Visão geral.

Operações

Operação

Escopo

Comportamento

PutRow

Linha única

Insere uma linha. Se já existir uma linha com a mesma chave primária, exclui todas as versões de dados de todas as colunas e grava os novos dados.

UpdateRow

Linha única

Adiciona, atualiza ou remove colunas de atributo. Exclui uma versão específica de dados de uma coluna. Caso a linha não exista, insere uma nova linha (exceto se a solicitação apenas remover colunas).

BatchWriteRow

Múltiplas linhas

Combina várias suboperações PutRow, UpdateRow e DeleteRow em uma única solicitação, abrangendo uma ou mais tabelas. O sistema executa e responde a cada suboperação de forma independente.

Configurações comuns

Antes de gravar dados, configure as seguintes opções opcionais para qualquer operação de escrita:

  • Número da versão dos dados: Por padrão, o Tablestore utiliza o timestamp UNIX atual (milissegundos desde January 1, 1970, 00:00:00 UTC) como número da versão. Especifique um número de versão personalizado, se necessário. Para mais informações, consulte Versões de dados e TTL.

  • Atualização condicional: Defina uma condição de existência de linha ou baseada em valores de coluna. Para mais informações, consulte Atualizações condicionais.

Resposta do PutRow

  • Em caso de sucesso, o Tablestore retorna o número de unidades de capacidade (CUs) consumidas.

  • Em caso de falha, o Tablestore retorna um código de erro (por exemplo, falha na validação de parâmetros, excesso de dados na linha ou falha na verificação de existência da linha).

Nota

Para mais informações sobre códigos de erro, consulte Códigos de erro.

Tratamento de falhas parciais no BatchWriteRow

Quando algumas linhas falham em uma solicitação BatchWriteRow, o Tablestore não lança exceção. Em vez disso, retorna um BatchWriteRowResponse com informações sobre as linhas que falharam. Sempre chame o método isAllSucceed para verificar se todas as linhas foram gravadas com sucesso.

Se o servidor detectar parâmetros inválidos em algumas operações, poderá retornar um erro antes de executar qualquer operação da solicitação.

O BatchWriteRow também suporta condições por operação. Configure condições de atualização separadamente para cada suboperação PutRow, UpdateRow ou DeleteRow.

Use the Tablestore console

O console do Tablestore permite inserir e atualizar uma única linha de dados.

  1. Faça login no Tablestore console.

  2. Na página Overview, localize a instância desejada e clique em Manage Instance na coluna Actions.

  3. Na aba Tables da página Instance Details, clique no nome da tabela desejada.

  4. Na aba Query Data da página Manage Table, insira ou atualize os dados.

Inserir uma única linha

  1. Clique em Insert.

  2. Na caixa de diálogo Insert, insira os valores na coluna Primary Key Value.

  3. Clique no ícone image e configure os parâmetros Name, Type, Value e Version. Para adicionar várias colunas de atributo, clique no ícone image sempre que precisar adicionar uma coluna e configurar seus parâmetros.

  4. Clique em OK.

Atualizar uma única linha

  1. Selecione a linha a ser atualizada e clique em Update.

  2. Na caixa de diálogo Update, modifique as colunas de atributo:

    • Adicionar uma coluna: Clique no ícone image e configure os parâmetros.

    • Remover uma coluna: Selecione Delete All na lista suspensa Actions.

    • Excluir uma versão específica: Selecione Delete na lista suspensa Actions e escolha o número da versão a excluir.

    • Atualizar um valor: Selecione Update na lista suspensa Actions e modifique o valor.

  3. Clique em OK.

Use the Tablestore CLI

Inserir uma linha

Execute o comando put. Para mais informações, consulte Inserir dados.

O exemplo a seguir insere uma linha em que a primeira coluna de chave primária é 86 e a segunda é 6771. A linha possui duas colunas de atributo STRING: name e country.

put --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]'

Atualizar uma linha

Execute o comando update. Para mais informações, consulte Atualizar dados.

O exemplo a seguir atualiza a linha em que a primeira coluna de chave primária é 86 e a segunda é 6771. O sinalizador --condition ignore insere dados independentemente da existência da linha. Se a linha já existir, os novos dados sobrescreverão os existentes.

update --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]' --condition ignore

Use Tablestore SDKs

Grave dados utilizando qualquer um dos seguintes SDKs: Tablestore SDK for Java, Tablestore SDK for Go, Tablestore SDK for Python, Tablestore SDK for Node.js, Tablestore SDK for .NET ou Tablestore SDK for PHP.

Os exemplos a seguir utilizam o SDK para Java.

Inserir uma única linha

O PutRow suporta números de versão gerados pelo sistema, números de versão personalizados e gravações condicionais.

Número de versão gerado pelo sistema

Insira uma linha com 10 colunas de atributo, cada uma armazenando uma versão de dados. O sistema gera automaticamente os números de versão.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Add attribute columns.
    for (int i = 0; i < 10; i++) {
        rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Número de versão personalizado

Insira uma linha com 10 colunas de atributo, cada uma armazenando três versões de dados com números de versão personalizados.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Add attribute columns.
    long ts = System.currentTimeMillis();
    for (int i = 0; i < 10; i++) {
        for (int j = 0; j < 3; j++) {
            rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
        }
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Condição de existência de linha

Insira uma linha com 10 colunas de atributo (três versões cada) somente quando a linha especificada não existir.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Specify a row existence condition that expects the specified row to not exist.
    rowPutChange.setCondition(new Condition(RowExistenceExpectation.EXPECT_NOT_EXIST));

    // Add attribute columns.
    long ts = System.currentTimeMillis();
    for (int i = 0; i < 10; i++) {
        for (int j = 0; j < 3; j++) {
            rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
        }
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Condições de existência de linha e valor de coluna

Insira uma linha com 10 colunas de atributo (três versões cada) quando a linha existir e o valor de Col0 for maior que 100.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Specify a row existence condition and a column-based condition that expect the specified row to exist and the value of the Col0 column to be greater than 100.
    Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
    condition.setColumnCondition(new SingleColumnValueCondition("Col0",
            SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
    rowPutChange.setCondition(condition);

    // Add attribute columns.
    long ts = System.currentTimeMillis();
    for (int i = 0; i < 10; i++) {
        for (int j = 0; j < 3; j++) {
            rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
        }
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Atualizar uma única linha

O UpdateRow suporta atualizações incondicionais e condicionais baseadas na existência da linha e nos valores das colunas.

Atualização sem condições

Atualize várias colunas, exclua uma versão específica de dados de uma coluna e remova uma coluna.

private static void updateRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowUpdateChange rowUpdateChange = new RowUpdateChange("<TABLE_NAME>", primaryKey);

    // Update columns.
    for (int i = 0; i < 10; i++) {
        rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
    }

    // Delete a specific version of data from a column.
    rowUpdateChange.deleteColumn("Col10", 1465373223000L);

    // Remove a column.
    rowUpdateChange.deleteColumns("Col11");

    client.updateRow(new UpdateRowRequest(rowUpdateChange));
}

Condições de existência de linha e valor de coluna

Atualize uma linha quando ela existir e o valor de Col0 for maior que 100.

private static void updateRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowUpdateChange rowUpdateChange = new RowUpdateChange("<TABLE_NAME>", primaryKey);

    // Specify a row existence condition and a column-based condition that expect the specified row to exist and the value of the Col0 column to be greater than 100.
    Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
    condition.setColumnCondition(new SingleColumnValueCondition("Col0",
            SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
    rowUpdateChange.setCondition(condition);

    // Update columns.
    for (int i = 0; i < 10; i++) {
        rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
    }

    // Delete a specific version of data from a column.
    rowUpdateChange.deleteColumn("Col10", 1465373223000L);

    // Remove a column.
    rowUpdateChange.deleteColumns("Col11");

    client.updateRow(new UpdateRowRequest(rowUpdateChange));
}

Gravar várias linhas simultaneamente

O exemplo a seguir envia uma solicitação BatchWriteRow contendo duas operações PutRow, uma operação UpdateRow e uma operação DeleteRow.

private static void batchWriteRow(SyncClient client) {
    BatchWriteRowRequest batchWriteRowRequest = new BatchWriteRowRequest();

    // Construct rowPutChange1.
    PrimaryKeyBuilder pk1Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk1Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk1"));
    // Specify the name of the data table.
    RowPutChange rowPutChange1 = new RowPutChange("<TABLE_NAME>", pk1Builder.build());
    // Add columns.
    for (int i = 0; i < 10; i++) {
        rowPutChange1.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
    }
    // Add rowPutChange1 to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowPutChange1);

    // Construct rowPutChange2.
    PrimaryKeyBuilder pk2Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk2Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk2"));
    // Specify the name of the data table.
    RowPutChange rowPutChange2 = new RowPutChange("<TABLE_NAME>", pk2Builder.build());
    // Add columns.
    for (int i = 0; i < 10; i++) {
        rowPutChange2.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
    }
    // Add rowPutChange2 to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowPutChange2);

    // Construct rowUpdateChange.
    PrimaryKeyBuilder pk3Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk3Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk3"));
    // Specify the name of the data table.
    RowUpdateChange rowUpdateChange = new RowUpdateChange("<TABLE_NAME>", pk3Builder.build());
    // Add columns.
    for (int i = 0; i < 10; i++) {
        rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
    }
    // Remove a column.
    rowUpdateChange.deleteColumns("Col10");
    // Add rowUpdateChange to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowUpdateChange);

    // Construct rowDeleteChange.
    PrimaryKeyBuilder pk4Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk4Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk4"));
    // Specify the name of the data table.
    RowDeleteChange rowDeleteChange = new RowDeleteChange("<TABLE_NAME>", pk4Builder.build());
    // Add rowDeleteChange to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowDeleteChange);

    BatchWriteRowResponse response = client.batchWriteRow(batchWriteRowRequest);

    System.out.println("Whether all operations are successful:" + response.isAllSucceed());
    if (!response.isAllSucceed()) {
        for (BatchWriteRowResponse.RowResult rowResult : response.getFailedRows()) {
            System.out.println("Failed rows:" + batchWriteRowRequest.getRowChange(rowResult.getTableName(), rowResult.getIndex()).getPrimaryKey());
            System.out.println("Cause of failures:" + rowResult.getError());
        }
        /**
         * You can use the createRequestForRetry method to construct another request to retry the operations on failed rows. Only the retry request is constructed here.
         * We recommend that you use the custom retry policy in Tablestore SDKs as the retry method. This feature allows you to retry failed rows after batch operations. After you set the retry policy, you do not need to add retry code to call the operation.
         */
        BatchWriteRowRequest retryRequest = batchWriteRowRequest.createRequestForRetry(response.getFailedRows());
    }
}

Faturamento

As operações de escrita são cobradas com base no número de CUs consumidas. As CUs de leitura e escrita medidas e as CUs de leitura e escrita reservadas têm cobrança separada. O tipo de instância determina qual tipo de CU é consumido.

Nota

Para mais informações sobre tipos de instância e CUs, consulte Instâncias e Throughput de leitura e escrita.

Cálculo de CU de escrita

Operação

Fórmula

PutRow

Arredondado para cima: (Tamanho de todas as colunas de chave primária + Tamanho das colunas de atributo inseridas) / 4 KB

UpdateRow

Arredondado para cima: (Tamanho de todas as colunas de chave primária + Tamanho das colunas de atributo atualizadas) / 4 KB. Para operações de remoção de coluna, o comprimento do nome da coluna conta como o tamanho da coluna.

DeleteRow (no BatchWriteRow)

Arredondado para cima: Tamanho de todas as colunas de chave primária / 4 KB

Cálculo de CU de leitura

As CUs de leitura são consumidas apenas quando o parâmetro condition não está definido como IGNORE.

Operação

Fórmula

Condição não atendida

PutRow

Arredondado para cima: Tamanho de todas as colunas de chave primária / 4 KB

A operação falha. Consome 1 CU de escrita e 1 CU de leitura.

UpdateRow

Arredondado para cima: Tamanho de todas as colunas de chave primária / 4 KB

A operação falha. Consome 1 CU de escrita e 1 CU de leitura.

DeleteRow (no BatchWriteRow)

Arredondado para cima: Tamanho de todas as colunas de chave primária / 4 KB

A operação falha. Consome 1 CU de escrita e 1 CU de leitura.