Gravar uma linha - Tablestore SDK for Java - Tablestore: Central de Documentação do Alibaba Cloud

Pré-requisitos

Instale o Tablestore SDK for Java e inicialize o cliente.

Descrição

public PutRowResponse putRow(PutRowRequest putRowRequest) throws TableStoreException, ClientException

Grava ou atualiza uma única linha. Se a linha existir, o parâmetro condition determina se a operação deve sobrescrever, acrescentar ou rejeitar a gravação.

O exemplo a seguir grava uma linha na tabela put_row_demo com a coluna de chave primária id definida como row1 e a coluna de atributo col1 definida como val1.

String tableName = "put_row_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
PrimaryKey primaryKey = primaryKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);
rowPutChange.addColumn("col1", ColumnValue.fromString("val1"));

PutRowResponse response = client.putRow(new PutRowRequest(rowPutChange));
System.out.println("RequestId: " + response.getRequestId());
System.out.println("Write CU: " + response.getConsumedCapacity().getCapacityUnit().getWriteCapacityUnit());

Parâmetros principais:

tableName (obrigatório): o nome da tabela para gravar.
primaryKey (obrigatório): a chave primária. Os nomes e os valores das colunas devem corresponder ao esquema de chave primária da tabela.
columnsToPut (opcional): a lista de colunas de atributos. Adicione colunas chamando addColumn.

Parâmetros

PutRowRequest encapsula um RowPutChange que contém os parâmetros de gravação:

Nome	Tipo	Descrição
tableName (obrigatório)	String	O nome da tabela para gravar.
primaryKey (obrigatório)	PrimaryKey	A chave primária, incluindo nomes e valores de colunas. Os tipos de dados compatíveis são STRING, INTEGER e BINARY. O número e os tipos de colunas de chave primária devem corresponder ao esquema de chave primária da tabela. Para uma coluna de chave primária de auto-incremento, defina o valor da coluna como o espaço reservado. Para obter mais informações, consulte Coluna de chave primária de auto-incremento.
columnsToPut (opcional)	List<Column>	A lista de colunas de atributos. Adicione colunas individualmente chamando `addColumn` várias vezes, ou passe uma `List<Column>` em uma única chamada. Os tipos de dados compatíveis são STRING, INTEGER, BINARY, DOUBLE e BOOLEAN. Por padrão, a versão dos dados (timestamp) é gerada pelo servidor. Para definir uma versão personalizada, passe `timestamp` como terceiro argumento para `addColumn`. Para obter mais informações, consulte Versão dos dados.
condition (opcional)	Condition	A condição de gravação. Por padrão, a gravação sobrescreve qualquer linha existente. Para obter mais informações, consulte Gravação condicional.
returnType (opcional)	ReturnType	O tipo de retorno, definido com `setReturnType`. RT_NONE (padrão): nenhum dado é retornado. RT_PK: retorna as colunas de chave primária. Normalmente usado para recuperar valores de colunas de auto-incremento. RT_AFTER_MODIFY: retorna os valores de colunas modificados. Normalmente usado com contadores atômicos.

Exemplos

Gravar várias colunas de atributos

O exemplo mostra ambas as abordagens: chamar addColumn por coluna e passar uma List<Column> preparada em uma única chamada.

String tableName = "put_row_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row2"));
PrimaryKey primaryKey = primaryKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);

// Option 1: Add columns one at a time with addColumn
rowPutChange.addColumn("name", ColumnValue.fromString("Alice"));
rowPutChange.addColumn("age", ColumnValue.fromLong(30));
rowPutChange.addColumn("active", ColumnValue.fromBoolean(true));

// Option 2: Pass a List<Column> in a single call
List<Column> columns = new ArrayList<>();
columns.add(new Column("score", ColumnValue.fromDouble(95.5)));
columns.add(new Column("city", ColumnValue.fromString("Hangzhou")));
rowPutChange.addColumns(columns);

client.putRow(new PutRowRequest(rowPutChange));

Especificar a versão dos dados

Use addColumn(name, value, timestamp) para definir uma versão de dados personalizada ao gravar a coluna.

String tableName = "put_row_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row3"));
PrimaryKey primaryKey = primaryKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);

long timestamp = System.currentTimeMillis();
rowPutChange.addColumn("col1", ColumnValue.fromString("val1"), timestamp);

client.putRow(new PutRowRequest(rowPutChange));

Retornar a chave primária de uma coluna de auto-incremento

Para uma coluna de chave primária de auto-incremento, defina o valor da coluna como o espaço reservado PrimaryKeyValue.AUTO_INCREMENT — o servidor gera o valor real no momento da gravação. Para recuperar o valor gerado na resposta, chame setReturnType(ReturnType.RT_PK) antes de gravar e, em seguida, chame response.getRow() após o retorno da gravação.

String tableName = "put_row_auto_inc_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("partition_key", PrimaryKeyValue.fromString("pk1"));
primaryKeyBuilder.addPrimaryKeyColumn("auto_id", PrimaryKeyValue.AUTO_INCREMENT);
PrimaryKey primaryKey = primaryKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);
rowPutChange.addColumn("payload", ColumnValue.fromString("hello"));
rowPutChange.setReturnType(ReturnType.RT_PK);

PutRowResponse response = client.putRow(new PutRowRequest(rowPutChange));
Row returnedRow = response.getRow();
System.out.println("Returned PK: " + returnedRow.getPrimaryKey());

Referências

Operações em lote de linhas