表格存储提供了PutRow、GetRow、UpdateRow和DeleteRow等单行操作的接口。

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

前提条件

  • 已初始化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