Use Tablestore SDK for Java to write data - : Central de Documentação do Alibaba Cloud

Pré-requisitos

Cliente do Tablestore inicializado. Para obter mais informações, consulte Inicializar um cliente do Tablestore.
Tabela de dados criada em uma instância do Tablestore.

Métodos de gravação

Tablestore permite gravar uma única linha de dados, atualizar uma única linha e gravar várias linhas simultaneamente chamando diferentes operações. A tabela a seguir descreve as diferenças e os cenários aplicáveis de cada método.

Método de gravação	Descrição	Cenário
Gravar uma única linha de dados	Chame a operação PutRow para gravar uma única linha de dados.	Recomendado para cenários que exigem a gravação de um pequeno volume de dados.
Atualizar uma única linha de dados	Utilize a operação UpdateRow para atualizar uma única linha de dados.	Ideal quando é necessário atualizar poucos dados.
Gravar várias linhas de dados simultaneamente	Execute a operação BatchWriteRow para gravar várias linhas de dados em uma ou mais tabelas ao mesmo tempo.	Mais indicado para operações em massa de gravação, exclusão ou atualização, inclusive quando essas ações ocorrem de forma combinada.

Parâmetros

A tabela a seguir descreve os parâmetros configuráveis para gravar dados no Tablestore.

Parâmetro	Descrição
tableName	Nome da tabela de dados.
primaryKey	Informações da chave primária da tabela de dados, incluindo nome, tipo e valor de cada coluna de chave primária. Importante A quantidade e os tipos das colunas de chave primária especificados devem corresponder exatamente à quantidade e aos tipos reais definidos na tabela. Se uma coluna de chave primária for de incremento automático, defina seu valor como um espaço reservado (placeholder). Para obter mais informações, consulte Coluna de chave primária de incremento automático.
column	Informações sobre as colunas de atributo, incluindo nome, valor, tipo e timestamp de cada coluna. Os campos tipo e timestamp são opcionais. Nome da coluna de atributo. Deve ter entre 1 e 255 caracteres, contendo letras, dígitos e sublinhados (_). O nome diferencia maiúsculas de minúsculas e não pode começar com um dígito. Tipo da coluna de atributo. Pode ser String, Integer, Binary, Floating-point ou Boolean. O timestamp representa o número da versão dos dados. O sistema gera esse número automaticamente, mas você também pode definir um número de versão personalizado. Para obter mais informações, consulte Número de versão. Nota Para excluir uma coluna de atributo, especifique apenas o nome da coluna. Para excluir uma versão específica de dados de uma coluna de atributo, informe o nome da coluna e o timestamp. Após excluir todas as colunas de atributo de uma linha, a linha ainda permanece existente. Para remover a linha completamente, chame a operação DeleteRow. Para obter mais informações, consulte Excluir dados.
condition	Condição necessária para a gravação dos dados. Pode ser uma condição de existência de linha ou baseada em valores de colunas. Para obter mais informações, consulte Usar atualizações condicionais.

Gravar uma única linha de dados

Chame a operação PutRow para gravar uma única linha de dados. Se a linha já existir, a operação PutRow exclui todas as versões de dados de todas as colunas da linha existente e, em seguida, grava os novos dados.

Nota

Neste exemplo, pkValue representa o valor da coluna de chave primária. Especifique pkValue conforme seus requisitos de negócio. Para gravar dados em uma tabela, forneça as informações completas da chave primária e os detalhes das colunas de atributo desejadas. Você também pode definir condições para a gravação, como permitir a escrita apenas se a linha especificada não existir.

Os exemplos de código a seguir demonstram como usar o número de versão gerado automaticamente pelo sistema, definir um número de versão personalizado e estabelecer condições para gravar dados na tabela:

Usar o número de versão de dados gerado automaticamente pelo sistema

O código abaixo ilustra a gravação de uma linha com 10 colunas de atributo, em que cada coluna armazena dados de apenas uma versão. Neste cenário, o sistema gera os números de versão automaticamente:

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key. 
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("your_primaryKey", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the data table. 
    RowPutChange rowPutChange = new RowPutChange("your_tableName", 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));
}

Especificar um número de versão de dados personalizado

Este exemplo mostra como gravar uma linha contendo 10 colunas de atributo, sendo que cada uma armazena dados de três versões 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("your_primaryKey", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the data table. 
    RowPutChange rowPutChange = new RowPutChange("your_tableName", 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));
}

Especificar uma condição de existência de linha

O trecho a seguir exemplifica a gravação de uma linha com 10 colunas de atributo (três versões cada) somente quando a linha especificada não existe. Números de versão personalizados são utilizados:

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

    // Specify a condition for the PutRow operation. In this example, data is written to the data table only when the specified row does 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));
}

Especificar simultaneamente uma condição de valor de coluna e de existência de linha

Este código demonstra como gravar uma linha com 10 colunas de atributo (três versões cada) apenas se a linha já existir e o valor da coluna Col0 for maior que 100. O exemplo utiliza números de versão personalizados:

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

    // Specify conditions for the PutRow operation. In this example, a row is written to the data table only when the row exists and the value of the Col0 column is 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 de dados

Utilize a operação UpdateRow para modificar uma única linha de dados. Essa operação permite atualizar o valor de uma coluna de atributo, adicionar ou remover colunas de atributo, ou excluir uma versão específica de dados de uma coluna. Caso a linha não exista, o sistema adiciona uma nova linha.

Nota

Se uma operação UpdateRow especificar apenas colunas para exclusão e a linha alvo não existir, nenhuma nova linha será adicionada à tabela de dados.

Os exemplos de código a seguir mostram como atualizar colunas específicas, excluir uma versão de dados da coluna Col1 e remover a coluna Col0, tanto com condições de atualização quanto sem condições:

Atualizar uma linha de dados sem especificar condições

Veja abaixo um exemplo de atualização de linha sem a definição de condições prévias:

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

    // Update specific 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("Col1", 1465373223000L);

    // Delete a column. 
    rowUpdateChange.deleteColumns("Col0");

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

Especificar condição de existência de linha ou baseada em valores de coluna para atualização

Este exemplo atualiza uma linha de dados somente se ela já existir e o valor da coluna Col0 for superior a 100:

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

    // Specify the conditions for the UpdateRow operation. In this example, a row of data is updated only if the row exists and the value of the Col0 column is 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 specific 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("Col1", 1465373223000L);

    // Delete a column. 
    rowUpdateChange.deleteColumns("Col0");

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

Gravar várias linhas de dados simultaneamente

Chame a operação BatchWriteRow para gravar múltiplas linhas de dados em uma ou mais tabelas ao mesmo tempo.

A operação BatchWriteRow agrupa diversas operações PutRow, UpdateRow e DeleteRow. Ao chamar BatchWriteRow, o processo de construção de cada suboperação segue a mesma lógica das chamadas individuais de PutRow, UpdateRow ou DeleteRow. O Tablestore executa cada operação PutRow, UpdateRow ou DeleteRow de forma independente e retorna respostas separadas para cada uma delas.

Nota

A operação BatchWriteRow não impõe limite máximo de requisições simultâneas. Configure a concorrência adequadamente conforme as especificações do cliente e a disponibilidade de recursos para garantir uma execução de código eficiente e estável.
Caso o servidor identifique parâmetros inválidos em alguma das operações, a chamada BatchWriteRow lançará uma exceção indicando parâmetro inválido. Nessa situação, nenhuma operação da solicitação será executada.
Durante a gravação em lote via BatchWriteRow, algumas linhas podem falhar. Quando isso ocorre, o Tablestore retorna um objeto BatchWriteRowResponse contendo os índices e as mensagens de erro das linhas com falha. Verifique sempre os valores retornados. Use o parâmetro isAllSucceed no BatchWriteRowResponse para confirmar se todas as linhas foram gravadas com sucesso nas tabelas.

O código a seguir exemplifica uma solicitação BatchWriteRow composta por duas operações PutRow, uma DeleteRow e uma UpdateRow:

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

    // Construct the first rowPutChange. 
    PrimaryKeyBuilder pk1Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk1Builder.addPrimaryKeyColumn("your_primaryKey", PrimaryKeyValue.fromString("pkValue1"));
    // Specify the name of the data table. 
    RowPutChange rowPutChange1 = new RowPutChange("your_tableName", 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 the second rowPutChange. 
    PrimaryKeyBuilder pk2Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk2Builder.addPrimaryKeyColumn("your_primaryKey", PrimaryKeyValue.fromString("pkValue2"));
    // Specify the name of the data table. 
    RowPutChange rowPutChange2 = new RowPutChange("your_tableName", 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("your_primaryKey", PrimaryKeyValue.fromString("pkValue3"));
    // Specify the name of the data table. 
    RowUpdateChange rowUpdateChange = new RowUpdateChange("your_tableName", pk3Builder.build());
    // Add columns. 
    for (int i = 0; i < 10; i++) {
        rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
    }
    // Delete a column. 
    rowUpdateChange.deleteColumns("Col0");
    // Add rowUpdateChange to the code of the batch operation. 
    batchWriteRowRequest.addRowChange(rowUpdateChange);

    // Construct rowDeleteChange. 
    PrimaryKeyBuilder pk4Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk4Builder.addPrimaryKeyColumn("your_primaryKey", PrimaryKeyValue.fromString("pkValue4"));
    // Specify the name of the data table. 
    RowDeleteChange rowDeleteChange = new RowDeleteChange("your_tableName", 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. In this example, only the retry request is constructed. 
         * We recommend that you use the custom retry policy in Tablestore SDKs as the retry method. This way, you can retry failed rows after batch operations are performed. After you specify the retry policy, you do not need to add retry code to call the operation. 
         */
        BatchWriteRowRequest retryRequest = batchWriteRowRequest.createRequestForRetry(response.getFailedRows());
    }
}

Perguntas frequentes

Referências

Para acessar códigos de exemplo sobre operações de dados no Tablestore, visite o repositório de código de exemplo no GitHub.
Para coletar estatísticas em tempo real de aplicações online, como o número de visualizações de página (PVs), utilize o recurso de contador atômico. Para obter mais informações, consulte Usar contadores atômicos.
Para executar operações atômicas de gravação em uma ou mais linhas, aproveite o recurso de transação local. Para saber mais, consulte Usar transações locais.