全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网
表格存储

单行数据操作

更新时间:2017-06-07 13:26:11

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

插入一行数据(PutRow)

插入数据到指定的行。

接口

  1. /// <summary>
  2. /// 指定表名、主键和属性,写入一行数据。返回本次操作消耗的CapacityUnit。
  3. /// </summary>
  4. /// <param name="request">插入数据的请求</param>
  5. /// <returns>本次操作消耗的CapacityUnit</returns>
  6. public PutRowResponse PutRow(PutRowRequest request);
  7. /// <summary>
  8. /// PutRow的异步形式。
  9. /// </summary>
  10. public Task<PutRowResponse> PutRowAsync(PutRowRequest request);

示例 1

插入一行数据。

  1. // 定义行的主键,必须与创建表时的TableMeta中定义的一致
  2. var primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. // 定义要写入该行的属性列
  6. var attribute = new AttributeColumns();
  7. attribute.Add("col0", new ColumnValue(0));
  8. attribute.Add("col1", new ColumnValue("a"));
  9. attribute.Add("col2", new ColumnValue(true));
  10. try
  11. {
  12. // 构造插入数据的请求对象,RowExistenceExpectation.IGNORE表示不管此行是否存在都执行
  13. var request = new PutRowRequest("SampleTable", new Condition(RowExistenceExpectation.IGNORE),
  14. primaryKey, attribute);
  15. // 调用PutRow接口插入数据
  16. otsClient.PutRow(request);
  17. // 如果没有抛出异常,则说明执行成功
  18. Console.WriteLine("Put row succeeded.");
  19. }
  20. catch (Exception ex)
  21. {
  22. // 如果抛出异常,则说明执行失败,打印出错误信息
  23. Console.WriteLine("Put row failed, exception:{0}", ex.Message);
  24. }

提示:

  • Condition.IGNORE、Condition.EXPECT_EXIST 和 Condition.EXPECT_NOT_EXIST 从 3.0.0 版本开始被废弃,请替换为 new Condition (RowExistenceExpectation.IGNORE)、new Condition (RowExistenceExpectation.EXPECT_EXIST) 和 new Condition (RowExistenceExpectation.EXPECT_NOT_EXIST)。

  • RowExistenceExpectation.IGNORE 表示不管此行是否已经存在,都会插入新数据,如果之前有会被覆盖。

  • RowExistenceExpectation.EXPECT_EXIST 表示只有此行存在时,才会插入新数据,此时,原有数据也会被覆盖。

  • RowExistenceExpectation.EXPECT_NOT_EXIST 表示只有此行不存在时,才会插入数据,否则不执行。

  • 从 2.2.0 版本开始,Condition 不仅支持行条件,也支持列条件。

  • 详细代码:PutRow@GitHub

示例 2

设置条件插入一行数据。

下列示例演示:当行存在,且 col1 大于 24 的时候才执行插入操作。

  1. // 定义行的主键,必须与创建表时的TableMeta中定义的一致
  2. var primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. // 定义要写入该行的属性列
  6. AttributeColumns attribute = new AttributeColumns();
  7. attribute.Add("col0", new ColumnValue(0));
  8. attribute.Add("col1", new ColumnValue("a"));
  9. attribute.Add("col2", new ColumnValue(true));
  10. var request = new PutRowRequest(tableName, new Condition(RowExistenceExpectation.EXPECT_EXIST),
  11. primaryKey, attribute);
  12. // 当col0列的值大于24的时候,允许再次put row,覆盖掉原值
  13. try
  14. {
  15. request.Condition.ColumnCondition = new RelationalCondition("col0",
  16. RelationalCondition.CompareOperator.GREATER_THAN,
  17. new ColumnValue(24));
  18. otsClient.PutRow(request);
  19. Console.WriteLine("Put row succeeded.");
  20. }
  21. catch (Exception ex)
  22. {
  23. Console.WriteLine("Put row failed. error:{0}", ex.Message);
  24. }

提示:

  • 条件不仅支持单个条件,也支持多个条件组合。例如,col1 大于 5 且 pk2 小于’xyz’时插入数据。

  • 属性列和主键列都支持条件。

  • 当条件中的列在某行不存在时,可以通过 RelationCondition 中的 PassIfMissing 控制,默认是 true。

  • 详细代码:ConditionPutRow@GitHub

示例 3

异步插入一行数据。

  1. try
  2. {
  3. var putRowTaskList = new List<Task<PutRowResponse>>();
  4. for (int i = 0; i < 100; i++)
  5. {
  6. // 定义行的主键,必须与创建表时的TableMeta中定义的一致
  7. var primaryKey = new PrimaryKey();
  8. primaryKey.Add("pk0", new ColumnValue(i));
  9. primaryKey.Add("pk1", new ColumnValue("abc"));
  10. // 定义要写入该行的属性列
  11. var attribute = new AttributeColumns();
  12. attribute.Add("col0", new ColumnValue(i));
  13. attribute.Add("col1", new ColumnValue("a"));
  14. attribute.Add("col2", new ColumnValue(true));
  15. var request = new PutRowRequest(TableName, new Condition(RowExistenceExpectation.IGNORE),
  16. primaryKey, attribute);
  17. putRowTaskList.Add(TabeStoreClient.PutRowAsync(request));
  18. }
  19. // 等待每个异步调用返回,并打印出消耗的CU值
  20. foreach (var task in putRowTaskList)
  21. {
  22. task.Wait();
  23. Console.WriteLine("consumed read:{0}, write:{1}", task.Result.ConsumedCapacityUnit.Read,
  24. task.Result.ConsumedCapacityUnit.Write);
  25. }
  26. // 如果没有抛出异常,则说明插入数据成功
  27. Console.WriteLine("Put row async succeeded.");
  28. }
  29. catch (Exception ex)
  30. {
  31. // 如果抛出异常,则打印出出错信息
  32. Console.WriteLine("Put row async failed. exception:{0}", ex.Message);
  33. }

提示:

  • 每一个异步调用都会启动一个线程,如果连续启动了很多异步调用,且每个都耗时比较大的时候,可能会出现超时。

  • 详细代码:PutRowAsync@GitHub

读取一行数据(GetRow)

根据给定的主键读取单行数据。

接口

  1. /// <summary>
  2. /// 根据给定的主键读取单行数据。
  3. /// </summary>
  4. /// <param name="request">查询数据的请求</param>
  5. /// <returns>GetRow的响应</returns>
  6. public GetRowResponse GetRow(GetRowRequest request);
  7. /// <summary>
  8. /// GetRow的异步形式。
  9. /// </summary>
  10. public Task<GetRowResponse> GetRowAsync(GetRowRequest request);

示例 1

读取一行数据。

  1. // 定义行的主键,必须与创建表时的TableMeta中定义的一致
  2. PrimaryKey primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. try
  6. {
  7. // 构造查询请求对象,这里未指定读哪列,默认读整行
  8. var request = new GetRowRequest(TableName, primaryKey);
  9. // 调用GetRow接口查询数据
  10. var response = otsClient.GetRow(request);
  11. // 输出此行的数据,这里省略,详见下面GitHub的链接
  12. // 如果没有抛出异常,则说明成功
  13. Console.WriteLine("Get row succeeded.");
  14. }
  15. catch (Exception ex)
  16. {
  17. // 如果抛出异常,说明执行失败,打印出错误信息
  18. Console.WriteLine("Update table failed, exception:{0}", ex.Message);
  19. }

提示:

  • 查询一行数据时,默认返回这一行所有列的数据。如果想只返回特定行,可以通过 columnsToGet 参数限制。如果将 col0 和 col1 加入到 columnsToGet 中,则只返回 col0 和 col1 的值。

  • 查询时也支持按条件过滤,比如当 col0 的值大于 24 时才返回结果。

  • 当 columnsToGet 和 condition 同时使用时,顺序是 columnsToGet 先生效,然后再去返回的列中进行过滤。

  • 当某列不存在时的行为,可以通过 PassIfMissing 控制。

  • 详细代码:GetRow@GitHub

示例 2

使用过滤读取一行数据。

下面演示查询数据,但只返回 col0 和 col1 的数据,同时在 col0 上面过滤,要求的条件是 col0=24。

  1. // 定义行的主键,必须与创建表时的TableMeta中定义的一致
  2. PrimaryKey primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. var rowQueryCriteria = new SingleRowQueryCriteria("SampleTable");
  6. rowQueryCriteria.RowPrimaryKey = primaryKey;
  7. // 条件1:col0的值等于5
  8. var filter1 = new RelationalCondition("col0",
  9. RelationalCondition.CompareOperator.EQUAL,
  10. new ColumnValue(5));
  11. // 条件2:col1不等于ff的行
  12. var filter2 = new RelationalCondition("col1", RelationalCondition.CompareOperator.NOT_EQUAL, new ColumnValue("ff"));
  13. // 构造组合条件,包括条件1和条件2,关系是OR
  14. var filter = new CompositeCondition(CompositeCondition.LogicOperator.OR);
  15. filter.AddCondition(filter1);
  16. filter.AddCondition(filter2);
  17. rowQueryCriteria.Filter = filter;
  18. // 设置要查询和返回的行,查询和过滤的顺序是:先在行[col0,col1]上查询,然后再按条件过滤
  19. rowQueryCriteria.AddColumnsToGet("col0");
  20. rowQueryCriteria.AddColumnsToGet("col1");
  21. // 构造GetRowRequest
  22. var request = new GetRowRequest(rowQueryCriteria);
  23. try
  24. {
  25. // 查询
  26. var response = otsClient.GetRow(request);
  27. // 输出数据或者相关逻辑操作,这里省略
  28. // 如果没有抛出异常,则说明执行成功
  29. Console.WriteLine("Get row with filter succeeded.");
  30. }
  31. catch (Exception ex)
  32. {
  33. // 如果抛出异常,则说明执行失败,打印出错误信息
  34. Console.WriteLine("Get row with filter failed, exception:{0}", ex.Message);
  35. }

提示:

详细代码:GetRowWithFilter@GitHub

更新一行数据(UpdateRow)

更新指定行的数据。如果该行不存在,则新增一行;若该行存在,则根据请求的内容在这一行中新增、修改或者删除指定列的值。

接口

  1. /// <summary>
  2. /// 更新指定行的数据,如果该行不存在,则新增一行;若该行存在,则根据请求的内容在这一行中新增、修改或者删除指定列的值。
  3. /// </summary>
  4. /// <param name="request">请求实例</param>
  5. public UpdateRowResponse UpdateRow(UpdateRowRequest request);
  6. /// <summary>
  7. /// UpdateRow的异步形式。
  8. /// </summary>
  9. /// <param name="request"></param>
  10. /// <returns></returns>
  11. public Task<UpdateRowResponse> UpdateRowAsync(UpdateRowRequest request);

示例

更新一行数据。

  1. // 定义行的主键,必须与创建表时的TableMeta中定义的一致
  2. PrimaryKey primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. // 定义要写入该行的属性列
  6. UpdateOfAttribute attribute = new UpdateOfAttribute();
  7. attribute.AddAttributeColumnToPut("col0", new ColumnValue(0));
  8. attribute.AddAttributeColumnToPut("col1", new ColumnValue("b")); // 将原先的值'a'改为'b'
  9. attribute.AddAttributeColumnToPut("col2", new ColumnValue(true));
  10. try
  11. {
  12. // 构造更新行的请求对象,RowExistenceExpectation.IGNORE表示不管此行是否存在都执行
  13. var request = new UpdateRowRequest(TableName, new Condition(RowExistenceExpectation.IGNORE),
  14. primaryKey, attribute);
  15. // 调用UpdateRow接口执行
  16. otsClient.UpdateRow(request);
  17. // 如果没有抛出异常,则说明执行成功
  18. Console.Writeline("Update row succeeded.");
  19. }
  20. catch (Exception ex)
  21. {
  22. // 如果抛出异常,说明执行失败,打印异常信息
  23. Console.WriteLine("Update row failed, exception:{0}", ex.Message);
  24. }

提示:

删除一行数据(DeleteRow)

接口

  1. /// <summary>
  2. /// 指定表名和主键,删除一行数据。
  3. /// </summary>
  4. /// <param name="request">请求实例</param>
  5. /// <returns>响应实例</returns>
  6. public DeleteRowResponse DeleteRow(DeleteRowRequest request);
  7. /// <summary>
  8. /// DeleteRow的异步形式。
  9. /// </summary>
  10. public Task<DeleteRowResponse> DeleteRowAsync(DeleteRowRequest request);

示例

删除一行数据。

  1. // 要删除的行的PK列分别为0和"abc"
  2. var primaryKey = new PrimaryKey();
  3. primaryKey.Add("pk0", new ColumnValue(0));
  4. primaryKey.Add("pk1", new ColumnValue("abc"));
  5. try
  6. {
  7. // 构造请求,Condition.EXPECT_EXIST表示只有此行存在时才执行
  8. var deleteRowRequest = new DeleteRowRequest("SampleTable", Condition.EXPECT_EXIST, primaryKey);
  9. // 调用DeleteRow接口执行删除
  10. otsClient.DeleteRow(deleteRowRequest);
  11. // 如果没有抛出异常,则表示成功
  12. Console.Writeline("Delete table succeeded.");
  13. }
  14. catch (Exception ex)
  15. {
  16. // 如果抛出异常,说明删除失败,打印粗错误信息
  17. Console.WriteLine("Delete table failed, exception:{0}", ex.Message);
  18. }

提示:

本文导读目录