Escribir una fila - Tablestore - Centro de documentación de Alibaba Cloud

Utilice Tablestore SDK for Java para escribir o actualizar una fila en una tabla del modelo Wide Column.

Requisitos previos

Instale Tablestore SDK for Java e inicialice el cliente.

Descripción

Llame a putRow para escribir columnas de atributos en una fila identificada por su clave principal. Si la fila ya existe, Tablestore agrega o sobrescribe las versiones correspondientes de las columnas de atributos. Puede utilizar condition para controlar si se realiza la escritura.

public PutRowResponse putRow(PutRowRequest putRowRequest) throws TableStoreException, ClientException

A continuación se muestra un ejemplo que escribe una fila en la tabla put_row_demo con la columna de clave principal id establecida en row1 y la columna de atributo col1 establecida en 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"));

client.putRow(new PutRowRequest(rowPutChange));

Parámetros

PutRowRequest contiene los siguientes parámetros.

Nombre

Tipo

Descripción

rowChange (obligatorio)

RowPutChange

La configuración para escribir una fila.

transactionId (opcional)

String

El ID de la transacción local. Establezca este parámetro solo cuando escriba datos dentro de una transacción local.

Para obtener información sobre cómo obtener y utilizar el ID, consulte Use local transactions.

Cambio de fila

rowChange es de tipo RowPutChange y contiene los siguientes parámetros.

Nombre	Tipo	Descripción
tableName (obligatorio)	`String`	El nombre de la tabla.
primaryKey (obligatorio)	`PrimaryKey`	La clave principal de la fila. Los nombres, el orden y los tipos de las columnas de clave principal deben coincidir con el esquema de la tabla. Las columnas de clave principal admiten los tipos `STRING`, `INTEGER` y `BINARY`. Para una columna de clave principal de incremento automático, establezca el valor en `PrimaryKeyValue.AUTO_INCREMENT`.
columnsToPut (opcional)	`List<Column>`	Las columnas de atributos que se van a escribir. Llame a `addColumn` varias veces para agregar columnas una por una, o bien llame a `addColumns` para agregar varias columnas.
condition (opcional)	`Condition`	La condición de escritura. De forma predeterminada, Tablestore no comprueba si la fila existe. Para obtener información sobre cómo configurar la condición, consulte Use conditional updates.
returnType (opcional)	`ReturnType`	El tipo de retorno. El valor predeterminado es `RT_NONE`, que no devuelve información de la clave principal. Establezca este parámetro en `RT_PK` para devolver la clave principal completa, lo cual es útil para recuperar un valor de clave principal de incremento automático.

Columnas de atributos

Cada elemento en rowChange.columnsToPut[] es de tipo Column y contiene los siguientes parámetros.

Nombre	Tipo	Descripción
name (obligatorio)	`String`	El nombre de la columna de atributo.
value (obligatorio)	`ColumnValue`	El valor de la columna de atributo. Los tipos compatibles son `STRING`, `INTEGER`, `BINARY`, `DOUBLE` y `BOOLEAN`.
timestamp (opcional)	`long`	El número de versión de los datos. Unidad: milisegundos. Si no especifica este parámetro, el servidor genera el valor automáticamente.

Ejemplos

Escribir varias columnas de atributos

Este ejemplo muestra ambos enfoques: llamar a addColumn por cada columna, o pasar una List<Column> preparada en una sola llamada.

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 la versión de los datos

Utilice addColumn(name, value, timestamp) para establecer una versión personalizada de los datos al escribir la columna.

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));

Devolver la clave principal de una columna de incremento automático

Para una columna de clave principal de incremento automático, establezca el valor de la columna en el marcador de posición PrimaryKeyValue.AUTO_INCREMENT; el servidor generará el valor real durante la escritura. Para recuperar el valor generado en la respuesta, llame a setReturnType(ReturnType.RT_PK) antes de escribir y, posteriormente, llame a response.getRow() una vez que finalice la operación de escritura.

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());