表格存储的数据操作（一）

表格存储的表由行组成，每一行包含主键和属性。本节将介绍表格存储数据的操作方法。

表格存储行简介


组成表格存储表的基本单位是行，行由主键和属性组成。其中，主键是必须的，且每一行的主键列的名称和类型相同；属性不是必须的，并且每一行的属性可以不同。更多信息请参见表格存储的 数据模型概念。
表格存储的数据操作有以下三种类型：

• 
  单行操作
  GetRow：读取单行数据。
• 
  PutRow：新插入一行。如果该行内容已经存在，则先删除旧行，再写入新行。
• 
  UpdateRow：更新一行。应用可以增加、删除一行中的属性列，或者更新已经存在的属性列的值。如果该行不存在，则新增一行。
• 
  DeleteRow：删除一行。

批量操作

• 
  BatchGetRow：批量读取多行数据。
• 
  BatchWriteRow：批量插入、更新或者删除多行数据。

范围读取

• GetRange：读取表中一个范围内的数据。

表格存储单行操作



单行写入操作


表格存储的单行写操作有三种：PutRow、UpdateRow 和 DeleteRow。下面分别介绍每种操作的行为语义和注意事项:

• 
  PutRow：新写入一行。如果这一行已经存在，则这一行旧的数据会先被删除，再新写入一行。
• 
  UpdateRow：更新一行的数据。表格存储会根据请求的内容在这一行中新增列，修改或者删除指定列的值。如果这一行不存在，则会插入新的一行。但是有一种特殊的场景，若 UpdateRow 请求只包含删除指定的列，且该行不存在，则该请求不会插入新行。
• 
  DeleteRow：删除一行。如果删除的行不存在，则不会发生任何变化。

应用程序通过设置请求中的 condition 字段来指定写入操作执行时，是否需要对行的存在性进行检查。condition 有三种类型:

• 
  IGNORE：不做任何存在性检查。
• 
  EXPECT_EXIST：期望行存在。如果该行存在，则操作成功；如果该行不存在，则操作失败。
• 
  EXPECT_NOT_EXIST：期望行不存在。如果行不存在，则操作成功；如果该行存在，则操作失败。

condition 为 EXPECT_NOT_EXIST 的 DeleteRow、UpdateRow 操作是没有意义的，删除一个不存在的行是无意义的，如果需要更新不存在的行可以使用 PutRow 操作。
如果操作发生错误，如参数检查失败、单行数据量过多、行存在性检查失败等等，会返回错误码给应用程序。如果操作成功，表格存储会将操作消耗的服务能力单元返回给应用程序。
各操作消耗的写服务能力单元的计算规则如下：

• 
  PutRow：本次消耗的写 CU 为修改的行主键数据大小与属性列数据大小之和除以 4 KB 向上取整。若指定条件检查不为 IGNORE，还需消耗该行主键数据大小除以 4 KB 向上取整的读 CU。如果操作不满足应用程序指定的行存在性检查条件，则操作失败并消耗 1 单位写服务能力单元和 1 单位读服务能力单元。请参见 PutRow 详解。
• 
  UpdateRow：本次消耗的写 CU 为修改的行主键数据大小与属性列数据大小之和除以 4 KB 向上取整。UpdateRow 中包含的需要删除的属性列，只有其列名计入该属性列数据大小。若指定条件检查不为 IGNORE，还需消耗该行主键数据大小除以 4 KB 向上取整的读 CU。如果操作不满足应用程序指定的行存在性检查条件，则操作失败并消耗 1 单位写服务能力单元和 1 单位读服务能力单元。请参见 UpdateRow 详解。
• 
  DeleteRow：被删除的行主键数据大小除以 4 KB 向上取整。若指定条件检查不为 IGNORE，还需消耗该行主键数据大小除以 4 KB 向上取整的读 CU。如果操作不满足应用程序指定的行存在性检查条件，则操作失败并消耗 1 单位写服务能力单元。请参见 DeleteRow 详解。

写操作会根据指定的 condition 情况消耗一定的读服务能力单元。

示例


下面举例说明单行写操作的写服务能力单元和读服务能力单元的计算。
[backcolor=transparent]示例 1，使用 PutRow 进行如下行写入操作： //PutRow 操作
//row_size=len('pk')+len('value1')+len('value2')+8Byte+1300Byte+3000Byte=4322Byte
{
    primary_keys:{'pk':1},
    attributes:{'value1':String(1300Byte), 'value2':String(3000Byte)}
}
//原来的行
//row_size=len('pk')+len('value2')+8Byte+900Byte=916Byte
//row_primarykey_size=len('pk')+8Byte=10Byte
{
    primary_keys:{'pk':1},
    attributes:{'value2':String(900Byte)}
}

读/写服务能力单元的消耗情况如下：

• 
  将 condition 设置为 EXPECT_EXIST 时：消耗的写服务能力单元为 4322 Byte 除以 4 KB 向上取整，消耗的读服务能力单元为该行主键数据大小 10 Byte 除以 4 KB 向上取整。该 PutRow 操作消耗 2 个单位的写服务能力单元和 1 个单位的读服务能力单元。
• 
  将 condition 设置为 IGNORE 时：消耗的写服务能力单元为 4322 Byte 除以 4 KB 向上取整，消耗 0 个读服务能力单元。该 PutRow 操作消耗 2 个单位的写服务能力单元和 0 个单位的读服务能力单元。
• 
  将 condition 设置为 EXPECT_NOT_EXIST 时：指定的行存在性检查条件检查失败，该 PutRow 操作消耗 1 个单位的写服务能力单元和 1 个单位的读服务能力单元。

[backcolor=transparent]示例 2，使用 UpdateRow 新写入一行： //UpdateRow 操作
//删除的属性列列名长度计入 row_size
//row_size=len('pk')+len('value1')+len('value2')+8Byte+900Byte=922Byte
{
    primary_keys:{'pk':1},
    attributes:{'value1':String(900Byte), 'value2':Delete}
}
//原来的行不存在
//row_size=0

读/写服务能力单元的消耗情况如下：

• 
  将 condition 设置为 IGNORE 时：消耗的写服务能力单元为 922 Byte 除以 4 KB 向上取整，消耗 0 个读服务能力单元。该 UpdateRow 操作消耗 1个单位的写服务能力单元和 0 个读服务能力单元。
• 
  将 condition 设置为 EXPECT_EXIST 时：指定的行存在性检查条件检查失败，该 PutRow 操作消耗 1 个单位的写服务能力单元和 1 个单位的读服务能力单元。

[backcolor=transparent]示例 3，使用 UpdateRow 对存在的行进行更新操作： //UpdateRow 操作
//row_size=len('pk')+len('value1')+len('value2')+8Byte+1300Byte+3000Byte=4322Byte
{
    primary_keys:{'pk':1},
    attributes:{'value1':String(1300Byte), 'value2':String(3000Byte)}
}
//原来的行
//row_size=len('pk')+len('value1')+8Byte+900Byte=916Byte
//row_primarykey_size=len('pk')+8Byte=10Byte
{
    primary_keys:{'pk':1},
    attributes:{'value1':String(900Byte)}
}

读/写服务能力单元的消耗情况如下：

• 
  将 condition 设置为 EXPECT_EXIST 时：消耗的写服务能力单元为 4322 Byte 除以 4 KB 向上取整，消耗的读服务能力单元为该行主键数据大小 10 Byte 除以 4 KB 向上取整。该 UpdateRow 操作消耗 2 个单位的写服务能力单元和 1 个单位的读服务能力单元。
• 
  将 condition 设置为 IGNORE 时：消耗的写服务能力单元为 4322 Byte 除以 4 KB 向上取整，消耗 0 个读服务能力单元，该 UpdateRow 操作消耗 2 个单位的写服务能力单元和 0 个单位的读服务能力单元。

[backcolor=transparent]示例 4，使用 DeleteRow 删除不存在的行： //原来的行不存在
//row_size=0
//DeleteRow 操作
//row_size=0
//row_primarykey_size=len('pk')+8Byte=10Byte
{
    primary_keys:{'pk':1},
}

修改前后的数据大小均为 0，无论读写操作成功还是失败至少消耗 1 个单位服务能力单元。因此，该 DeleteRow 操作消耗 1 个单位的写服务能力单元。
读/写服务能力单元的消耗情况如下：

• 
  将 condition 设置为 EXPECT_EXIST 时：消耗的写服务能力单元为该行主键数据大小 10 Byte 除以 4 KB 向上取整，消耗的读服务能力单元为该主键数据大小 10 Byte 除以 4 KB 向上取整。该 DeleteRow 操作消耗 1 个单位的写服务能力单元和 1 个单位的读服务能力单元。
• 
  将 condition 设置为 IGNORE 时：消耗的写服务能力单元为该行主键数据大小 10 Byte 除以 4 KB 向上取整，消耗 0 个读服务能力单元。该 DeleteRow 操作消耗 1 个单位的写服务能力单元和 0 个单位的读服务能力单元。

更多信息请参见 API Reference 中的 PutRow、 UpdateRow 和 DeleteRow 章节。

单行读取操作


表格存储的单行读操作只有一种：GetRow。
应用程序提供完整的主键和需要返回的列名。列名可以是主键列或属性列，也可以不指定要返回的列名，此时请求返回整行数据。
表格存储根据被读取的行主键的数据大小与实际读取的属性列数据大小之和计算读服务能力单元。将行数据大小除以 4 KB 向上取整作为本次读取操作消耗的读服务能力单元。如果操作指定的行不存在，则消耗 1 单位读服务能力单元，单行读取操作不会消耗写服务能力单元。

示例


使用 GetRow 读取一行消耗的写服务能力单元的计算： //被读取的行
//row_size=len('pk')+len('value1')+len('value2')+8Byte+1200Byte+3100Byte=4322Byte
{
    primary_keys:{'pk':1},
    attributes:{'value1':String(1200Byte), 'value2':String(3100Byte)}
}
//GetRow 操作
//获取的数据 size=len('pk')+len('value1')+8Byte+1200Byte=1216Byte
{
    primary_keys:{'pk':1},
    columns_to_get:{'value1'}
}

消耗的读服务能力单元为 1216 Byte 除以 4 KB 向上取整，该 GetRow 操作消耗 1 个单位的读服务能力单元。
更多信息请参见 API Reference 的 GetRow 章节。