Tablestore provides the following single-row operations: PutRow, GetRow, UpdateRow, and DeleteRow.
Prerequisites
- The OTSClient instance is initialized. For more information, see Initialization.
- A data table is created. Data is written to the table.
PutRow
You can call this operation to insert a row of data. If the row already exists, this operation deletes the existing row (all columns and all versions of the original row), and then writes data to the row.
- API operations
// @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 table. PrimaryKey The primary key of the row. Note- The number and type of primary key columns configured must be consistent with those of primary key columns of the table.
- When the primary key column is an auto-increment column, you need only to set the value of the auto-increment column to the auto-increment primary key column. For more information, see Configure an auto-increment primary key column.
Columns The attribute column of the row. - Each item specifies the values in the following sequence: the attribute column name, attribute column value (ColumnValue), attribute column value type (ColumnType, which is optional), and timestamp (optional).
- ColumnType can be set to ColumnType.INTEGER, ColumnType.STRING, ColumnType.BINARY, ColumnType.BOOLEAN, and ColumnType.DOUBLE, which respectively indicate the INTEGER, STRING (UTF-8 encoded string), BINARY, BOOLEAN, and DOUBLE types. If the type is BINARY, the type must be specified. Otherwise, the type can be ignored.
- The timestamp is the version number of the data. For more information, see Max versions and TTL.
You can customize a version number or specify that the system generates the version number. If the timestamp is not set, the version number is generated by the system.
- The version number is calculated based on the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.
- When you choose to customize the version number, make sure that the version number is a 64-bit timestamp accurate to the millisecond within the valid version range.
Condition You can use conditional update to set row existence conditions or column-based conditions. For more information, see Configure conditional update. - Examples
The following code provides an example on how to insert a 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") }
For the detailed sample code, visit PutRow@GitHub.
GetRow
You can call this opertaion to read a row of data.
- If the row exists, the primary key columns and attribute columns of the row are returned.
- If the row does not exist, no row is returned and no error is reported.
- API operations
// Return a row of data in the table. // // @param GetRowRequest Encapsulate the parameters required to call the GetRow operation. // @return GetRowResponse The content of the response to the GetRow operation. GetRow(request *GetRowRequest) (*GetRowResponse, error)
- Parameters
Parameter Description TableName The name of the table. PrimaryKey The primary key of the row. Note The number and type of primary key columns configured must be consistent with those of primary key columns of the table.ColumnsToGet The set of columns to read. The column name can be the primary key column or attribute column. If you do not specify this parameter, all data in the row is returned.
Note- If you query a row of data, the system returns the data in all columns of the row. You can set the ColumnsToGet parameter to read the data only in specified columns. If col0 and col1 are added to ColumnsToGet, only the values of the col0 and col1 columns are returned.
- When ColumnsToGet and Filter are used at the same time, the columns specified by ColumnsToGet are returned. Then, the returned columns are filtered.
MaxVersion The maximum number of read versions. Note You must specify at least one of MaxVersion and TimeRange.- If you specify only MaxVersion, data of up to the specified number of versions is returned from the latest to the earliest.
- If you specify only TimeRange, all data within a range or a version of data is returned.
- If you specify both MaxVersion and TimeRange, data of up to the specified number of versions within the time range is returned from the latest to the earliest.
TimeRange Reads data within a range of versions or a specific version of data. For more information, see TimeRange. Note You must specify at least one of MaxVersion and TimeRange.- If you specify only MaxVersion, data of up to the specified number of versions is returned from the latest to the earliest.
- If you specify only TimeRange, all data within a range or a version of data is returned.
- If you specify both MaxVersion and TimeRange, data of up to the specified number of versions within the time range is returned from the latest to the earliest.
- To query data within a range, you must set Start and End. Start specifies the start timestamp. End indicates the end timestamp. The time range is a left-closed and right-open interval, which is [Start, End).
- To query data of a specific version, set Specific. Specific specifies a specific timestamp.
You can set one of Specific and [Start, End).
Valid values: [0, INT64.MAX). Unit: milliseconds.
Filter Filters the read results on the server side and returns only the rows of data that meet the conditions in the filter. For more information, see Configure filter. Note When ColumnsToGet and Filter are used at the same time, the columns specified by ColumnsToGet are returned. Then, the returned columns are filtered. - Examples
The following code provides an example on how to read a row of data:
getRowRequest := new(tablestore.GetRowRequest) criteria := new(tablestore.SingleRowQueryCriteria); putPk := new(tablestore.PrimaryKey) putPk.AddPrimaryKeyColumn("pk1", "pk1value1") putPk.AddPrimaryKeyColumn("pk2", int64(2)) putPk.AddPrimaryKeyColumn("pk3", []byte("pk3")) criteria.PrimaryKey = putPk getRowRequest.SingleRowQueryCriteria = criteria getRowRequest.SingleRowQueryCriteria.TableName = tableName getRowRequest.SingleRowQueryCriteria.MaxVersion = 1 getResp, err := client.GetRow(getRowRequest) if err ! = nil { fmt.Println("getrow failed with error:", err) } else { fmt.Println("get row col0 result is ",getResp.Columns[0].ColumnName, getResp.Columns[0].Value,) }
For the detailed sample code, visit GetRow@GitHub.
UpdateRow
- API operations
// Update a row of data in a 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 table. PrimaryKey The primary key of the row. Note The number and type of primary key columns configured must be consistent with those of primary key columns of the table.Columns The attribute column of the row. - To add an attribute column or update the value of an existing attribute column, you
must specify the name, value and type (optional) of the attribute column, and a timestamp
(optional).
The timestamp is the version number of the data. It can be automatically generated or customized. If you do not specify this parameter, Tablestore automatically generates a timestamp. For more information, see Max versions and TTL.
- The version number is calculated based on the number of milliseconds that have elapsed since 00:00:00 UTC on January 1, 1970.
- If you choose to specify the version number, ensure that the version number is a 64-bit timestamp accurate to the millisecond within the valid version range.
- You need only to set the name of the attribute column and the timestamp to delete
a specified version of data in an attribute column.
A timestamp is a 64-bit integer that indicates a specified version of data. Unit: milliseconds.
- You need only to set the name of the attribute column to delete an attribute column.
Note A row exists even if all attribute columns in the row are deleted. To delete a row, use the DeleteRow operation.
Condition You can use conditional update to set row existence conditions or column-based conditions. For more information, see Configure conditional update. - To add an attribute column or update the value of an existing attribute column, you
must specify the name, value and type (optional) of the attribute column, and a timestamp
(optional).
- Examples
The following code provides an example on how to update the data of a specified row:
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") }
For the detailed sample code, visit UpdateRow@GitHub.
DeleteRow
You can call this operation to delete a row of data. If the specified row does not exist, no change is made to the table.
- API operations
// Delete a row of data from a table. // @param DeleteRowRequest Encapsulate the parameters required to call the DeleteRow operation. // @return DeleteRowResponse The content of the response to the DeleteRow operation. DeleteRow(request *DeleteRowRequest) (*DeleteRowResponse, error)
- Parameters
Parameter Description TableName The name of the table. PrimaryKey The primary key of the row. Note The number and type of primary key columns configured must be consistent with those of primary key columns of the table.Condition You can use conditional update to set row existence conditions or column-based conditions. For more information, see Configure conditional update. - Examples
The following code provides an example on how to delete a row of data:
deleteRowReq := new(tablestore.DeleteRowRequest) deleteRowReq.DeleteRowChange = new(tablestore.DeleteRowChange) deleteRowReq.DeleteRowChange.TableName = tableName deletePk := new(tablestore.PrimaryKey) deletePk.AddPrimaryKeyColumn("pk1", "pk1value1") deletePk.AddPrimaryKeyColumn("pk2", int64(2)) deletePk.AddPrimaryKeyColumn("pk3", []byte("pk3")) deleteRowReq.DeleteRowChange.PrimaryKey = deletePk deleteRowReq.DeleteRowChange.SetCondition(tablestore.RowExistenceExpectation_EXPECT_EXIST) clCondition1 := tablestore.NewSingleColumnCondition("col2", tablestore.CT_EQUAL, int64(3)) deleteRowReq.DeleteRowChange.SetColumnCondition(clCondition1) _, err := client.DeleteRow(deleteRowReq) if err ! = nil { fmt.Println("delete failed with error:", err) } else { fmt.Println("delete row finished") }
For the detailed sample code, visit DeleteRow@GitHub.