Tablestore provides the following single-row operations: PutRow, GetRow, UpdateRow, and DeleteRow.

Prerequisites

  • The OTSClient instance is initialized. For more information, see Initialize a Tablestore client.
  • A data table is created. Data is written to the table.

PutRow

You can call this operation to insert a row. If the row you want to insert exists, the PutRow operation deletes all versions of data from all columns in the existing row and then inserts a new row.

  • 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 configured number and types of primary key columns must be consistent with the actual number and types 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 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 value type (ColumnType, which is optional), and timestamp (optional).
    • You can set ColumnType to ColumnType.INTEGER, ColumnType.STRING, ColumnType.BINARY, ColumnType.BOOLEAN, or ColumnType.DOUBLE, which separately indicates INTEGER, STRING (a UTF-8 encoded string), BINARY, BOOLEAN, or DOUBLE. If you want to set the column value type to BINARY, you must set ColumnType to ColumnType.BINARY. If you want to use other types of column values, the setting of ColumnType is optional.
    • A timestamp is the data version number. For more information, see Max versions and TTL.

      You can customize a data version number or use the data version number generated by Tablestore. If you do not specify this parameter, the data version number generated by the system is used.

      • The version number generated by Tablestore is calculated based on the number of milliseconds that have elapsed since 00:00:00 UTC on January 1, 1970.
      • When 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.
    Condition You can use conditional update to set a row existence condition or columns-based conditions for the row. 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 operation to read a row of data.

The following results of the read request may be returned:
  • 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.
  • 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 configured number and types of primary key columns must be consistent with the actual number and types of primary key columns of the table.
    ColumnsToGet The names of the columns to read. You can specify the names of the primary key columns and the names of attribute columns.

    If you do not specify this parameter, all data in the row is returned.

    Note
    • By default, Tablestore returns the data from all columns of the row when you query a 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 versions that can be read.
    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 Specifies a range of versions to read or a version of data to read. 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).

    The timestamp used for the value of time_range ranges from 0 to INT64.MAX. Unit: milliseconds.

    Filter You can set filter conditions to filter the queried results on the server side. Only rows that meet the specified filter conditions are returned. 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

You can call this operation to update data of a specified row. You can add attribute columns to or delete attribute columns from a row, delete a specified version of data from an attribute column, or update the existing data in an attribute column. If the specified row does not exist, a new row is added.
Note If the UpdateRow request contains only columns to delete, and the specified row does not exist, a new row is not added.
  • 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 configured number and types of primary key columns must be consistent with the actual number and types of primary key columns of the table.
    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, attribute column value type (optional), and 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 generated by Tablestore is calculated based on the number of milliseconds that have elapsed since 00:00:00 UTC on January 1, 1970.
      • When 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.
    • To delete a specified version of data from an attribute column, you need only to set the attribute column name and timestamp.

      The timestamp is a 64-bit integer that indicates a specified version of data. Unit: milliseconds.

    • To delete an attribute column, you need only to set the attribute column name.
      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 a row existence condition or columns-based conditions for the row. For more information, see Configure conditional update.
  • 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. If the specified row does not exist, no change is made to the table.

  • 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 configured number and types of primary key columns must be consistent with the actual number and types 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 from a table:

        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.