All Products
Search
Document Center

Tablestore:Write data

Last Updated:Feb 29, 2024

Tablestore allows you to write a single row of data, update a single row of data, and write multiple rows of data at the same time by calling different operations. To write data to a data table, you must specify the complete primary key information and the attribute columns that you want to add, delete, or modify. To write data to a highly concurrent application, you can configure row existence conditions or column conditions to update data based on the specified conditions.

Prerequisites

Write a single row of data

You can call the PutRow operation to write a row of data. If the row exists, Tablestore deletes all versions of data in all columns from the existing row and writes new data.

API operation

// @param PutRowRequest    Encapsulate the parameters required to call the PutRow operation. 
// @return PutRowResponse
PutRow(request *PutRowRequest) (*PutRowResponse, error)                    

Parameters

Parameter

Description

TableName

The name of the data table.

PrimaryKey

The primary key information about the row. The primary key information includes the name, type, and value of the primary key column.

Important
  • The number and types of primary key columns that you specify must be the same as the actual number and types of primary key columns in the table.

  • If a primary key column is an auto-increment primary key column, you do not need to specify a value for the primary key column. You need to only set the primary key column to an auto-increment primary key column. For more information, see Configure an auto-increment primary key column.

Columns

The attribute columns of the row. An attribute column is specified by parameters in the following sequence: the attribute column name, attribute column value (ColumnValue), attribute column type (ColumnType), and timestamp. The attribute column type and timestamp are optional.

  • The attribute column name is the name of the attribute column, and the attribute column type is the data type of the attribute column. For more information, see Naming conventions and data types.

    You can set the ColumnType parameter to ColumnType.INTEGER that specifies an INTEGER value, ColumnType.STRING that specifies a UTF-8 encoded STRING, ColumnType.BINARY that specifies a BINARY value, ColumnType.BOOLEAN that specifies a BOOLEAN value, or ColumnType.DOUBLE that specifies a DOUBLE value. If the attribute column type is BINARY, you must set the ColumnType parameter to ColumnType.BINARY. In other cases, you can leave the ColumnType parameter empty.

  • The timestamp is a data version number. You can use the data version number that is automatically generated by the system or specify a custom data version number. By default, if you do not specify a data version number, the data version number that is automatically generated by the system is used. For more information, see Data versions and TTL.

    • By default, the system uses the current UNIX timestamp as the data version number. The timestamp follows the UNIX time format. It is the number of milliseconds that have elapsed since 00:00:00 Thursday, January 1, 1970.

    • If you specify a version number, make sure that the version number is a 64-bit timestamp that is accurate to milliseconds and is in the valid version range.

Condition

The condition that you can configure to call the PutRow operation. You can configure a row existence condition or a condition based on column values. For more information, see Configure conditional update.

Examples

The following sample code provides an example on how to write a single row of data:

putRowRequest := new(tablestore.PutRowRequest)
putRowChange := new(tablestore.PutRowChange)
putRowChange.TableName = tableName
putPk := new(tablestore.PrimaryKey)
putPk.AddPrimaryKeyColumn("pk1", "pk1value1")
putPk.AddPrimaryKeyColumn("pk2", int64(2))
putPk.AddPrimaryKeyColumn("pk3", []byte("pk3"))
putRowChange.PrimaryKey = putPk
putRowChange.AddColumn("col1", "col1data1")
putRowChange.AddColumn("col2", int64(3))
putRowChange.AddColumn("col3", []byte("test"))
putRowChange.SetCondition(tablestore.RowExistenceExpectation_IGNORE)
putRowRequest.PutRowChange = putRowChange
_, err := client.PutRow(putRowRequest)

if err != nil {
    fmt.Println("putrow failed with error:", err)
} else {
    fmt.Println("putrow finished")
 }                    

To view the detailed sample code, visit PutRow@GitHub.

Update a single row of data

You can call the UpdateRow operation to update the data in a row. You can add attribute columns to a row, remove attribute columns from a row, delete a specific version of data from an attribute column, or update the value of an attribute column. If the row does not exist, a new row is inserted.

Note

If you call the UpdateRow operation only to remove columns from a row and the row does not exist, no row is inserted into the table.

API operation

// Update a row of data in the table. 
// @param UpdateRowRequest      Encapsulate the parameters required to call the UpdateRow operation. 
// @return UpdateRowResponse    The content of the response to the UpdateRow operation. 
UpdateRow(request *UpdateRowRequest) (*UpdateRowResponse, error)                    

Parameters

Parameter

Description

TableName

The name of the data table.

PrimaryKey

The primary key information about the row. The primary key information includes the name, type, and value of the primary key column.

Important

The number and types of primary key columns that you specify must be the same as the actual number and types of primary key columns in the table.

Columns

The attribute columns of the row.

  • When you add or modify an attribute column, you must specify the attribute column name and attribute column value. The attribute column value type and timestamp are optional.

    The attribute column name is the name of the attribute column, and the attribute column value type is the data type of the attribute column. For more information, see Naming conventions and data types.

    A timestamp is a data version number. You can use the data version number that is automatically generated by the system or specify a custom data version number. By default, if you do not specify a data version number, the data version number that is automatically generated by the system is used. For more information, see Data versions and TTL.

    • By default, the system uses the current UNIX timestamp as a data version number. A UNIX timestamp represents the number of milliseconds that have elapsed since January 1, 1970, 00:00:00 UTC.

    • If you specify a custom data version number, make sure that the version number is a 64-bit timestamp that is accurate to milliseconds and is in the valid version range.

  • To delete a specified version of data from an attribute column, you need to only specify the attribute column name and timestamp.

    The timestamp is a 64-bit integer in units of milliseconds, which specifies a version of data.

  • To remove an attribute column, you need to only specify the attribute column name.

    Note

    After you remove all attribute columns from a row, the row still exists. To delete a row, use the DeleteRow operation.

Condition

The condition that you can configure to call the UpdateRow operation. You can configure a row existence condition or a condition based on column values. For more information, see Configure conditional update.

Examples

The following sample code provides an example on how to update a single row of data:

updateRowRequest := new(tablestore.UpdateRowRequest)
updateRowChange := new(tablestore.UpdateRowChange)
updateRowChange.TableName = tableName
updatePk := new(tablestore.PrimaryKey)
updatePk.AddPrimaryKeyColumn("pk1", "pk1value1")
updatePk.AddPrimaryKeyColumn("pk2", int64(2))
updatePk.AddPrimaryKeyColumn("pk3", []byte("pk3"))
updateRowChange.PrimaryKey = updatePk
updateRowChange.DeleteColumn("col1")
updateRowChange.PutColumn("col2", int64(77))
updateRowChange.PutColumn("col4", "newcol3")
updateRowChange.SetCondition(tablestore.RowExistenceExpectation_EXPECT_EXIST)
updateRowRequest.UpdateRowChange = updateRowChange
_, err := client.UpdateRow(updateRowRequest)

if err != nil {
    fmt.Println("update failed with error:", err)
} else {
    fmt.Println("update row finished")
}                    

To view the detailed sample code, visit UpdateRow@GitHub.

Write multiple rows of data at the same time

You can call the BatchWriteRow operation to write multiple rows of data to one or more tables at a time.

The BatchWriteRow operation consists of multiple PutRow, UpdateRow, and DeleteRow operations. When you call the BatchWriteRow operation, the process of constructing a suboperation is the same as the process of calling the PutRow, UpdateRow, or DeleteRow operation.

When you call the BatchWriteRow operation, each PutRow, UpdateRow, or DeleteRow operation is separately performed and the response to each operation is separately returned by Tablestore.

Usage notes

  • When you call the BatchWriteRow operation to write multiple rows of data at the same time, some rows may fail to be written. In this case, Tablestore does not return exceptions. Tablestore returns BatchWriteRowResponse in which the indexes and error messages of the failed rows are included. Therefore, when you call the BatchWriteRow operation, make sure to check the return values to determine whether all rows are written. If you do not check the return values, the rows that fail to be written may be ignored.

    If the server detects that invalid parameters exist in some operations, an error message may return before the operations of the request are performed.

  • You can call the BatchWriteRow operation to write up to 4 MB of data in up to 200 rows at the same time.

API operation

// Add, delete, or update multiple rows of data in multiple tables. 
// @param BatchWriteRowRequest             Encapsulate the parameters required to call the BatchWriteRow operation. 
// @return  BatchWriteRowResponse          The content of the response to the BatchWriteRow operation. 
BatchWriteRow(request *BatchWriteRowRequest) (*BatchWriteRowResponse,error)                  

Examples

The following sample code provides an example on how to write 100 rows of data at the same time:

batchWriteReq := &tablestore.BatchWriteRowRequest{}
for i := 0; i < 100; i++ {
    putRowChange := new(tablestore.PutRowChange)
    putRowChange.TableName = tableName
    putPk := new(tablestore.PrimaryKey)
    putPk.AddPrimaryKeyColumn("pk1", "pk1value1")
    putPk.AddPrimaryKeyColumn("pk2", int64(i))
    putPk.AddPrimaryKeyColumn("pk3", []byte("pk3"))
    putRowChange.PrimaryKey = putPk
    putRowChange.AddColumn("col1", "fixvalue")
    putRowChange.SetCondition(tablestore.RowExistenceExpectation_IGNORE)
    batchWriteReq.AddRowChange(putRowChange)
}

response, err := client.BatchWriteRow(batchWriteReq)
if err != nil {
    fmt.Println("batch request failed with:", response)
} else {
    fmt.Println("batch write row finished")
}                   

To view the detailed sample code, visit BatchWriteRow@GitHub.

FAQ

References

  • To update data in a highly concurrent application based on the specified conditions, you can use the conditional update feature. For more information, see Configure conditional update.

  • To collect real-time statistics about online applications, such as the number of page views (PVs) on various topics, you can use the atomic counter feature. For more information, see Configure atomic counter.

  • To perform atomic operations to write one or more rows of data, you can use the local transaction feature. For more information, see Configure local transaction.

  • After data is written to a table, you can read or delete the data in the table based on your business requirements. For more information, see Read data and Delete data.