表格存储提供了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。