Write single or multiple rows of data - Tablestore - Centro de documentación de Alibaba Cloud

Tablestore ofrece tres operaciones para escribir datos en las tablas: PutRow, UpdateRow y BatchWriteRow.

Nota

Las filas son las unidades básicas de las tablas. Cada fila se compone de columnas de clave primaria y columnas de atributos opcionales. Los nombres y tipos de las columnas de clave primaria son iguales en todas las filas de una tabla. Las columnas de atributos pueden variar entre filas. Para obtener más información, consulte Overview.

Operaciones

Operación	Alcance	Comportamiento
PutRow	Una sola fila	Inserta una fila. Si ya existe una fila con la misma clave primaria, elimina todas las versiones de los datos de cada columna y escribe los nuevos datos.
UpdateRow	Una sola fila	Agrega, actualiza o quita columnas de atributos. También elimina una versión específica de los datos de una columna. Si la fila no existe, inserta una nueva (salvo que la solicitud solo quite columnas).
BatchWriteRow	Varias filas	Combina varias suboperaciones PutRow, UpdateRow y DeleteRow en una única solicitud, sobre una o más tablas. Cada suboperación se ejecuta y se responde de forma independiente.

Configuraciones comunes

Antes de escribir datos, configure las siguientes opciones opcionales para cualquier operación de escritura:

Número de versión de los datos: De forma predeterminada, Tablestore usa la marca de tiempo UNIX actual (milisegundos transcurridos desde el January 1, 1970, 00:00:00 UTC) como número de versión. Especifique un número de versión personalizado si lo necesita. Para obtener más información, consulte Data versions and TTL.
Actualización condicional: Establezca una condición de existencia de fila o una condición basada en los valores de las columnas. Para obtener más información, consulte Conditional updates.

Respuesta de PutRow

Si la operación se completa correctamente, Tablestore devuelve el número de unidades de capacidad (CU) consumidas.
Si falla, Tablestore devuelve un código de error (por ejemplo, por errores en la validación de parámetros, exceso de datos en la fila o fallos al comprobar la existencia de la fila).

Nota

Para obtener más información sobre los códigos de error, consulte Error codes.

Manejo de errores parciales en BatchWriteRow

Cuando algunas filas fallan en una solicitud BatchWriteRow, Tablestore no genera una excepción. En su lugar, devuelve un objeto BatchWriteRowResponse que contiene la información de las filas con errores. Llame siempre al método isAllSucceed para comprobar si todas las filas se escribieron correctamente.

Si el servidor detecta parámetros no válidos en algunas operaciones, puede devolver un error antes de ejecutar cualquiera de las operaciones de la solicitud.

BatchWriteRow también admite condiciones por operación. Configure las condiciones de actualización por separado para cada suboperación PutRow, UpdateRow o DeleteRow.

Uso de la consola de Tablestore

La consola de Tablestore permite insertar y actualizar una sola fila de datos.

Inicie sesión en la consola de Tablestore.
En la página Overview, busque la instancia deseada y haga clic en Manage Instance dentro de la columna Actions.
En la pestaña Tables de la sección Instance Details, haga clic en el nombre de la tabla correspondiente.
En la pestaña Query Data de la página Manage Table, inserte o actualice los datos.

Insertar una sola fila

Haga clic en Insert.
En el cuadro de diálogo Insert, introduzca los valores en la columna Primary Key Value.
Haga clic en el icono y configure los parámetros Name, Type, Value y Version. Para agregar varias columnas de atributos, haga clic en el icono cada vez que necesite añadir una columna y configurar sus parámetros.
Haga clic en OK.

Actualizar una sola fila

Seleccione la fila que desea actualizar y haga clic en Update.
En el cuadro de diálogo Update, modifique las columnas de atributos:
- Agregar una columna: Haga clic en el icono y configure los parámetros.
- Quitar una columna: Seleccione Delete All en la lista desplegable Actions.
- Eliminar una versión específica: Seleccione Delete en la lista desplegable Actions y elija el número de versión que desea eliminar.
- Actualizar un valor: Seleccione Update en la lista desplegable Actions y modifique el valor.
Haga clic en OK.

Uso del CLI de Tablestore

Insertar una fila

Ejecute el comando put. Para obtener más información, consulte Insert data.

El siguiente ejemplo inserta una fila cuya primera columna de clave primaria es 86 y la segunda es 6771. La fila tiene dos columnas de atributos de tipo STRING: name y country.

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

Actualizar una fila

Ejecute el comando update. Para obtener más información, consulte Update data.

El siguiente ejemplo actualiza la fila cuya primera columna de clave primaria es 86 y la segunda es 6771. La bandera --condition ignore inserta los datos sin importar si la fila existe o no. Si la fila existe, los datos nuevos sobrescriben a los anteriores.

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

Uso de los SDK de Tablestore

Escriba datos con cualquiera de los siguientes SDK: Tablestore SDK for Java, Tablestore SDK for Go, Tablestore SDK for Python, Tablestore SDK for Node.js, Tablestore SDK for .NET o Tablestore SDK for PHP.

Los ejemplos a continuación usan el SDK de Java.

Insertar una sola fila

PutRow admite números de versión generados por el sistema, números de versión personalizados y escrituras condicionales.

Número de versión generado por el sistema

Inserte una fila con 10 columnas de atributos, donde cada una almacena una versión de los datos. El sistema genera automáticamente los números de versión.

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 versión personalizado

Inserte una fila con 10 columnas de atributos, donde cada una almacena tres versiones de datos con números de versión 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));
}

Condición de existencia de fila

Inserte una fila con 10 columnas de atributos (tres versiones cada una) únicamente cuando la fila especificada no exista.

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

Condiciones de existencia de fila y de valor de columna

Inserte una fila con 10 columnas de atributos (tres versiones cada una) cuando la fila exista y el valor de Col0 sea mayor 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));
}

Actualizar una sola fila

UpdateRow admite actualizaciones sin condiciones y actualizaciones condicionales basadas en la existencia de la fila y en los valores de las columnas.

Actualización sin condiciones

Actualice varias columnas, elimine una versión específica de los datos de una columna y quite otra columna.

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

Condiciones de existencia de fila y de valor de columna

Actualice una fila cuando esta exista y el valor de Col0 sea mayor 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));
}

Escribir varias filas a la vez

El siguiente ejemplo envía una solicitud BatchWriteRow que contiene dos operaciones PutRow, una UpdateRow y una 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());
    }
}

Facturación

Las operaciones de escritura se cobran según el número de CU consumidas. Las CU de lectura y escritura medidas, así como las reservadas, se facturan por separado. El tipo de instancia determina qué clase de CU se consume.

Nota

Para obtener más información sobre los tipos de instancia y las CU, consulte Instances y Read and write throughput.

Cálculo de las CU de escritura

Operación	Fórmula
PutRow	Redondeo hacia arriba: (Tamaño de todas las columnas de clave primaria + Tamaño de las columnas de atributos insertadas) / 4 KB
UpdateRow	Redondeo hacia arriba: (Tamaño de todas las columnas de clave primaria + Tamaño de las columnas de atributos actualizadas) / 4 KB. Cuando se quita una columna, la longitud de su nombre cuenta como el tamaño de dicha columna.
DeleteRow (en BatchWriteRow)	Redondeo hacia arriba: Tamaño de todas las columnas de clave primaria / 4 KB

Cálculo de las CU de lectura

Las CU de lectura se consumen únicamente cuando el parámetro condition no está establecido en IGNORE.

Operación	Fórmula	Condición no cumplida
PutRow	Redondeo hacia arriba: Tamaño de todas las columnas de clave primaria / 4 KB	La operación falla. Consume 1 CU de escritura y 1 CU de lectura.
UpdateRow	Redondeo hacia arriba: Tamaño de todas las columnas de clave primaria / 4 KB	La operación falla. Consume 1 CU de escritura y 1 CU de lectura.
DeleteRow (en BatchWriteRow)	Redondeo hacia arriba: Tamaño de todas las columnas de clave primaria / 4 KB	La operación falla. Consume 1 CU de escritura y 1 CU de lectura.