单行数据操作 - 表格存储 Tablestore

如需了解表格存储各场景的应用案例，请参见适用场景。

前提条件

已初始化Client，详情请参见初始化。
已创建数据表并写入数据。

插入一行数据（PutRow）

PutRow接口用于新写入一行数据。如果该行已存在，则先删除原行数据（原行的所有列以及所有版本的数据），再写入新行数据。

接口

    // @param PutRowRequest    执行PutRow操作所需参数的封装。
    // @return PutRowResponse
    PutRow(request *PutRowRequest) (*PutRowResponse, error)

参数


参数	说明
TableName	数据表名称。
PrimaryKey	行的主键。说明设置的主键个数和类型必须和数据表的主键个数和类型一致。当主键为自增列时，只需将相应主键指定为自增主键，详情请参见主键列自增。
Columns	行的属性列。每一项的顺序是属性名、属性值ColumnValue、属性类型ColumnType（可选）、时间戳（可选）。 ColumnType可以是INTEGER、STRING（UTF-8编码字符串）、BINARY、BOOLEAN、DOUBLE五种，分别用ColumnType.INTEGER、ColumnType.STRING、ColumnType.BINARY、ColumnType.BOOLEAN、ColumnType.DOUBLE表示，其中BINARY不可省略，其他类型都可以省略。时间戳即数据的版本号，详情请参见数据版本和生命周期。数据的版本号可以由系统自动生成或者自定义，如果不设置此参数，则默认由系统自动生成。当由系统自动生成数据的版本号时，系统默认将当前时间的毫秒单位时间戳（从1970-01-01 00:00:00 UTC计算起的毫秒数）作为数据的版本号。当自定义数据的版本号时，版本号需要为64位的毫秒单位时间戳且在有效版本范围内。
Condition	使用条件更新，可以设置原行的存在性条件或者原行中某列的列值条件，详情请参见条件更新。

示例

插入一行数据。

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

详细代码请参见PutRow@GitHub。

读取一行数据（GetRow）

GetRow接口用于读取一行数据。

读取的结果可能有如下两种：

如果该行存在，则返回该行的各主键列以及属性列。
如果该行不存在，则返回中不包含行，并且不会报错。

接口

    //返回表中的一行数据。
    //
    // @param GetRowRequest             执行GetRow操作所需参数的封装。
    // @return  GetRowResponse          GetRow操作的响应内容。
    GetRow(request *GetRowRequest) (*GetRowResponse, error)

参数


参数	说明
TableName	数据表名称。
PrimaryKey	行的主键。说明设置的主键个数和类型必须和数据表的主键个数和类型一致。
ColumnsToGet	读取的列集合，列名可以是主键列或属性列。如果不设置返回的列名，则返回整行数据。说明查询一行数据时，默认返回此行所有列的数据。如果需要只返回特定列，可以通过设置ColumnsToGet参数限制。如果将col0和col1加入到ColumnsToGet中，则只返回col0和col1列的值。当ColumnsToGet和Filter同时使用时，执行顺序是先获取ColumnsToGet指定的列，再在返回的列中进行条件过滤。
MaxVersion	最多读取的版本数。说明 MaxVersion与TimeRange必须至少设置一个。如果仅设置MaxVersion，则返回所有版本中从新到旧最多指定数量版本的数据。如果仅设置TimeRange，则返回该范围内所有数据或指定版本数据。如果同时设置MaxVersion和TimeRange，则返回版本号范围内从新到旧最多指定数量版本的数据。
TimeRange	读取版本号范围或特定版本号的数据。详情请参见TimeRange。说明 MaxVersion与TimeRange必须至少设置一个。如果仅设置MaxVersion，则返回所有版本中从新到旧最多指定数量版本的数据。如果仅设置TimeRange，则返回该范围内所有数据或指定版本数据。如果同时设置MaxVersion和TimeRange，则返回版本号范围内从新到旧最多指定数量版本的数据。如果查询一个范围的数据，则需要设置Start和End。Start和End分别表示起始时间戳和结束时间戳，范围为前闭后开区间，即[Start, End)。如果查询特定版本号的数据，则需要设置Specific。Specific表示特定的时间戳。 Specific和[Start, End)中只需要设置一个。时间戳的单位为毫秒，最小值为0，最大值为INT64.MAX。
Filter	使用过滤器，在服务端对读取结果再进行一次过滤，只返回符合过滤器中条件的数据行，详情请参见过滤器。说明当ColumnsToGet和Filter同时使用时，执行顺序是先获取ColumnsToGet指定的列，再在返回的列中进行条件过滤。

示例

读取一行数据。

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

详细代码请参见GetRow@GitHub。

更新一行数据（UpdateRow）

UpdateRow接口用于更新一行数据，可以增加和删除一行中的属性列，删除属性列指定版本的数据，或者更新已存在的属性列的值。如果更新的行不存在，则新增一行数据。

说明当UpdateRow请求中只包含删除指定的列且该行不存在时，则该请求不会新增一行数据。

接口

    // 更新表中的一行数据。
    // @param UpdateRowRequest      执行UpdateRow操作所需参数的封装。
    // @return UpdateRowResponse    UpdateRow操作的响应内容。
    UpdateRow(request *UpdateRowRequest) (*UpdateRowResponse, error)

参数


参数	说明
TableName	数据表名称。
PrimaryKey	行的主键。说明设置的主键个数和类型必须和数据表的主键个数和类型一致。
Columns	行的属性列。增加或更新数据时，需要设置属性名、属性值、属性类型（可选）、时间戳（可选）。时间戳即数据的版本号，可以由系统自动生成或者自定义，如果不设置此参数，则默认由系统自动生成。详情请参见数据版本和生命周期。当由系统自动生成数据的版本号时，系统默认将当前时间的毫秒单位时间戳（从1970-01-01 00:00:00 UTC计算起的毫秒数）作为数据的版本号。当自定义数据的版本号时，版本号需要为64位的毫秒单位时间戳且在有效版本范围内。删除属性列特定版本的数据时，只需要设置属性名和时间戳。时间戳是64位整数，单位为毫秒，表示某个特定版本的数据。删除属性列时，只需要设置属性名。说明删除一行的全部属性列不等同于删除该行，如果需要删除该行，请使用DeleteRow操作。
Condition	使用条件更新，可以设置原行的存在性条件或者原行中某列的列值条件，详情请参见条件更新。

示例

更新一行数据。

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

详细代码请参见UpdateRow@GitHub

删除一行数据（DeleteRow）

DeleteRow接口用于删除一行数据。如果删除的行不存在，则不会发生任何变化。

接口

    // 删除表中的一行。
    // @param DeleteRowRequest           执行DeleteRow操作所需参数的封装。
    // @return DeleteRowResponse         DeleteRow操作的响应内容。
    DeleteRow(request *DeleteRowRequest) (*DeleteRowResponse, error)

参数


参数	说明
TableName	数据表名称。
PrimaryKey	行的主键。说明设置的主键个数和类型必须和数据表的主键个数和类型一致。
Condition	支持使用条件更新，可以设置原行的存在性条件或者原行中某列的列值条件，详情请参见条件更新。

示例

删除一行数据。

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

详细代码请参见DeleteRow@GitHub。