写入数据

表格存储提供了单行插入、单行更新和批量写入的写入方式用于写入数据到数据表。当要写入数据到数据表时,您需要指定完整主键以及要增删改的属性列。在高并发应用中写入数据时,您可以配置行存在性条件或者列条件实现按照指定条件更新数据。

如果需要了解表格存储各场景的应用案例,请参见快速玩转Tablestore入门与实战

前提条件

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

插入单行数据

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

接口

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

参数

参数

说明

TableName

数据表名称。

PrimaryKey

行的主键。主键包括主键列名、主键类型和主键值。

重要
  • 设置的主键个数和类型必须和数据表的主键个数和类型一致。

  • 当主键为自增列时,只需将相应主键指定为自增主键。更多信息,请参见主键列自增

Columns

行的属性列。每一项的顺序是属性名、属性值ColumnValue、属性类型ColumnType(可选)、时间戳(可选)。

  • 属性名即属性列的名称,属性类型即属性列的数据类型。更多信息,请参见命名规则和数据类型

    属性类型可以是INTEGER、STRING(UTF-8编码字符串)、BINARY、BOOLEANDOUBLE五种,分别用ColumnType.INTEGERColumnType.STRINGColumnType.BINARYColumnType.BOOLEANColumnType.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

更新单行数据

调用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

批量写入数据

调用BatchWriteRow接口在一次请求中进行批量写入操作或者一次对多张表进行写入。

BatchWriteRow操作由多个PutRow、UpdateRow、DeleteRow子操作组成,构造子操作的过程与使用PutRow接口、UpdateRow接口和DeleteRow接口时相同。

BatchWriteRow的各个子操作独立执行,表格存储会分别返回各个子操作的执行结果。

注意事项

  • 由于批量写入可能存在部分行失败的情况,失败行的Index及错误信息在返回的BatchWriteRowResponse中,但并不抛出异常。因此调用BatchWriteRow接口时,需要检查返回值,判断每行的状态是否成功;如果不检查返回值,则可能会忽略掉部分操作的失败。

    当服务端检查到某些操作出现参数错误时,BatchWriteRow接口可能会抛出参数错误的异常,此时该请求中所有的操作都未执行。

  • BatchWriteRow操作单次支持写入的最大行数为200行,且所有行的数据量总和不能超过4 MB。

接口

// 对多个数据表中的多行数据进行增加、删除或者更新操作。
// @param BatchWriteRowRequest             执行BatchWriteRow操作所需参数的封装。
// @return  BatchWriteRowResponse          BatchWriteRow操作的响应内容。
BatchWriteRow(request *BatchWriteRowRequest) (*BatchWriteRowResponse,error)                  

示例

以下示例用于批量写入100行数据。

batchWriteReq := &tablestore.BatchWriteRowRequest{}
for i := 0; i < 100; i++ {
    putRowChange := new(tablestore.PutRowChange)
    putRowChange.TableName = tableName
    putPk := new(tablestore.PrimaryKey)
    putPk.AddPrimaryKeyColumn("pk1", "pk1value1")
    putPk.AddPrimaryKeyColumn("pk2", int64(i))
    putPk.AddPrimaryKeyColumn("pk3", []byte("pk3"))
    putRowChange.PrimaryKey = putPk
    putRowChange.AddColumn("col1", "fixvalue")
    putRowChange.SetCondition(tablestore.RowExistenceExpectation_IGNORE)
    batchWriteReq.AddRowChange(putRowChange)
}

response, err := client.BatchWriteRow(batchWriteReq)
if err != nil {
    fmt.Println("batch request failed with:", response)
} else {
    fmt.Println("batch write row finished")
}                   

详细代码请参见BatchWriteRow@GitHub

常见问题

相关文档

  • 当要在高并发应用中实现按照指定条件更新数据时,您可以通过条件更新实现。更多信息,请参见条件更新

  • 当要为在线应用提供实时统计功能时,例如统计帖子的PV(实时浏览量)等,您可以通过原子计数器实现。更多信息,请参见原子计数器

  • 当要进行单行写或多行写的原子操作,您可以通过局部事务实现。更多信息,请参见局部事务

  • 写入数据后,即可根据需要读取或者删除表中数据。更多信息,请参见读取数据删除数据