单行数据操作

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

前提条件

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

插入一行数据（PutRow）

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

接口

/// <summary>
/// 指定数据表名称、主键和属性，写入一行数据。返回本次操作消耗的CapacityUnit。
/// </summary>
/// <param name="request">插入数据的请求</param>
/// <returns>本次操作消耗的CapacityUnit</returns>
public PutRowResponse PutRow(PutRowRequest request);

/// <summary>
/// PutRow的异步形式。
/// </summary>
public Task<PutRowResponse> PutRowAsync(PutRowRequest request);                    

参数

示例

• 示例1

  插入一行数据。

  //定义行的主键，必须与创建表时的TableMeta中定义的一致。
  var primaryKey = new PrimaryKey();
  primaryKey.Add("pk0", new ColumnValue(0));
  primaryKey.Add("pk1", new ColumnValue("abc"));
  
  //定义要写入该行的属性列。
  var attribute = new AttributeColumns();
  attribute.Add("col0", new ColumnValue(0));
  attribute.Add("col1", new ColumnValue("a"));
  attribute.Add("col2", new ColumnValue(true));
  
  try
  {
      //构造插入数据的请求对象，RowExistenceExpectation.IGNORE表示无论此行是否存在均会插入新数据。
      var request = new PutRowRequest("SampleTable", new Condition(RowExistenceExpectation.IGNORE),
                              primaryKey, attribute);
  
      //调用PutRow接口插入数据。
      otsClient.PutRow(request);
  
      //如果没有抛出异常，则说明执行成功。
      Console.WriteLine("Put row succeeded.");
  }
  catch (Exception ex)
  {
      //如果抛出异常，则说明执行失败，处理异常。
      Console.WriteLine("Put row failed, exception:{0}", ex.Message);
  }                    

  详细代码请参见PutRow@GitHub。

• 示例2

  设置条件插入一行数据。如下示例的条件为当行存在且col0大于24时才执行插入操作。

  //定义行的主键，必须与创建表时的TableMeta中定义的一致。
  var primaryKey = new PrimaryKey();
  primaryKey.Add("pk0", new ColumnValue(0));
  primaryKey.Add("pk1", new ColumnValue("abc"));
  
  //定义要写入该行的属性列。
  AttributeColumns attribute = new AttributeColumns();
  attribute.Add("col0", new ColumnValue(0));
  attribute.Add("col1", new ColumnValue("a"));
  attribute.Add("col2", new ColumnValue(true));
  
  //当col0列的值大于24时，允许再次插入行，覆盖掉原值。
  try
  {
      var request = new PutRowRequest(tableName, new Condition(RowExistenceExpectation.EXPECT_EXIST),
                              primaryKey, attribute);
      request.Condition.ColumnCondition = new RelationalCondition("col0",
                                          RelationalCondition.CompareOperator.GREATER_THAN,
                                          new ColumnValue(24));
      otsClient.PutRow(request);
  
      Console.WriteLine("Put row succeeded.");
  }
  catch (Exception ex)
  {
      Console.WriteLine("Put row failed. error:{0}", ex.Message);
  }                   

  详细代码请参见ConditionPutRow@GitHub。

• 示例3

  异步插入一行数据。

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

  try
  {
      var putRowTaskList = new List<Task<PutRowResponse>>();
      for (int i = 0; i < 100; i++)
      {
          //定义行的主键，必须与创建表时的TableMeta中定义的一致。
          var primaryKey = new PrimaryKey();
          primaryKey.Add("pk0", new ColumnValue(i));
          primaryKey.Add("pk1", new ColumnValue("abc"));
  
          //定义要写入该行的属性列。
          var attribute = new AttributeColumns();
          attribute.Add("col0", new ColumnValue(i));
          attribute.Add("col1", new ColumnValue("a"));
          attribute.Add("col2", new ColumnValue(true));
  
          var request = new PutRowRequest(TableName, new Condition(RowExistenceExpectation.IGNORE),
                                          primaryKey, attribute);
  
          putRowTaskList.Add(TabeStoreClient.PutRowAsync(request));
      }
  
      //等待每个异步调用返回，并打印出消耗的CU值。
      foreach (var task in putRowTaskList)
      {
          task.Wait();
          Console.WriteLine("consumed read:{0}, write:{1}", task.Result.ConsumedCapacityUnit.Read,
                              task.Result.ConsumedCapacityUnit.Write);
      }
  
      //如果没有抛出异常，则说明执行成功。
      Console.WriteLine("Put row async succeeded.");
  }
  catch (Exception ex)
  {
      //如果抛出异常，则说明执行失败，处理异常。
      Console.WriteLine("Put row async failed. exception:{0}", ex.Message);
  }                   

  详细代码请参见PutRowAsync@GitHub。

读取一行数据（GetRow）

GetRow接口用于读取一行数据。

接口

/// <summary>
/// 根据给定的主键读取单行数据。
/// </summary>
/// <param name="request">查询数据的请求</param>
/// <returns>GetRow的响应</returns>
public GetRowResponse GetRow(GetRowRequest request);

/// <summary>
/// GetRow的异步形式。
/// </summary>
public Task<GetRowResponse> GetRowAsync(GetRowRequest request);
            

参数

示例

• 示例1

  读取一行数据。

      //定义行的主键，必须与创建表时的TableMeta中定义的一致。
      PrimaryKey primaryKey = new PrimaryKey();
      primaryKey.Add("pk0", new ColumnValue(0));
      primaryKey.Add("pk1", new ColumnValue("abc"));
  
      try
      {
          //构造查询请求对象，此处未指定读取的列，默认读取整行数据。
          var request = new GetRowRequest(TableName, primaryKey);
  
          //调用GetRow接口查询数据。
          var response = otsClient.GetRow(request);
  
          //输出此行的数据，此处省略，详见示例代码的GitHub链接。
  
          //如果没有抛出异常，则说明执行成功。
          Console.WriteLine("Get row succeeded.");
      }
      catch (Exception ex)
      {
          //如果抛出异常，则说明执行失败，处理异常。
          Console.WriteLine("Update table failed, exception:{0}", ex.Message);
      }
              

  详细代码请参见GetRow@GitHub。

• 示例2

  使用过滤器读取一行数据。

  如下示例为查询数据后，只返回col0和col1的数据，同时在col0列和col1列进行过滤，过滤条件是col0等于5或者col1不等于ff。

      //定义行的主键，必须与创建表时的TableMeta中定义的一致。
      PrimaryKey primaryKey = new PrimaryKey();
      primaryKey.Add("pk0", new ColumnValue(0));
      primaryKey.Add("pk1", new ColumnValue("abc"));
  
      var rowQueryCriteria = new SingleRowQueryCriteria("SampleTable");
      rowQueryCriteria.RowPrimaryKey = primaryKey;
  
      //条件1为col0列的值等于5。
      var filter1 = new RelationalCondition("col0",
                  RelationalCondition.CompareOperator.EQUAL,
                  new ColumnValue(5));
  
      //条件2为col1列的值不等于ff。
      var filter2 = new RelationalCondition("col1", RelationalCondition.CompareOperator.NOT_EQUAL, new ColumnValue("ff"));
  
      //构造组合条件，包括条件1和条件2，关系是OR。
      var filter = new CompositeCondition(CompositeCondition.LogicOperator.OR);
      filter.AddCondition(filter1);
      filter.AddCondition(filter2);
  
      rowQueryCriteria.Filter = filter;
  
      //设置要查询和返回的行，查询和过滤的顺序是先在行的[col0,col1]列上查询，然后再按条件过滤。
      rowQueryCriteria.AddColumnsToGet("col0");
      rowQueryCriteria.AddColumnsToGet("col1");
  
      //构造GetRowRequest。
      var request = new GetRowRequest(rowQueryCriteria);
  
      try
      {
          //查询。
          var response = otsClient.GetRow(request);
  
          //输出数据或者相关逻辑操作，此处省略。
  
          //如果没有抛出异常，则说明执行成功。
          Console.WriteLine("Get row with filter succeeded.");
      }
      catch (Exception ex)
      {
          //如果抛出异常，则说明执行失败，处理异常。
          Console.WriteLine("Get row with filter failed, exception:{0}", ex.Message);
      }
              

  详细代码请参见GetRowWithFilter@GitHub。

更新一行数据（UpdateRow）

UpdateRow接口用于更新一行数据，可以增加和删除一行中的属性列，删除属性列指定版本的数据，或者更新已存在的属性列的值。如果更新的行不存在，则新增一行数据。

接口

    /// <summary>
    /// 更新指定行的数据，如果该行不存在，则新增一行；若该行存在，则根据请求的内容在该行中新增、修改或者删除指定列的值。
    /// </summary>
    /// <param name="request">请求实例</param>
    public UpdateRowResponse UpdateRow(UpdateRowRequest request);

    /// <summary>
    /// UpdateRow的异步形式。
    /// </summary>
    /// <param name="request"></param>
    /// <returns></returns>
    public Task<UpdateRowResponse> UpdateRowAsync(UpdateRowRequest request);
            

参数

示例

更新一行数据。

    //定义行的主键，必须与创建表时的TableMeta中定义的一致。
    PrimaryKey primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(0));
    primaryKey.Add("pk1", new ColumnValue("abc"));

    //定义要写入该行的属性列。
    UpdateOfAttribute attribute = new UpdateOfAttribute();
    attribute.AddAttributeColumnToPut("col0", new ColumnValue(0));
    attribute.AddAttributeColumnToPut("col1", new ColumnValue("b")); // 将原先的值'a'改为'b'
    attribute.AddAttributeColumnToPut("col2", new ColumnValue(true));

    try
    {
        //构造更新行的请求对象，RowExistenceExpectation.IGNORE表示无论此行是否存在都执行更新。
        var request = new UpdateRowRequest(TableName, new Condition(RowExistenceExpectation.IGNORE),
                                    primaryKey, attribute);
        //调用UpdateRow接口更新数据。
        otsClient.UpdateRow(request);

        //如果没有抛出异常，则说明执行成功。
        Console.Writeline("Update row succeeded.");
    }
    catch (Exception ex)
    {
        //如果抛出异常，则说明执行失败，处理异常。
        Console.WriteLine("Update row failed, exception:{0}", ex.Message);
    }
            

详细代码请参见UpdateRow@GitHub。

删除一行数据（DeleteRow）

DeleteRow接口用于删除一行数据。如果删除的行不存在，则不会发生任何变化。

接口

    /// <summary>
    /// 指定数据表名称和行的主键，删除一行数据。
    /// </summary>
    /// <param name="request">请求实例</param>
    /// <returns>响应实例</returns>
    public DeleteRowResponse DeleteRow(DeleteRowRequest request);

    /// <summary>
    /// DeleteRow的异步形式。
    /// </summary>
    public Task<DeleteRowResponse> DeleteRowAsync(DeleteRowRequest request);
            

参数

示例

删除一行数据。

    //要删除的行的PK列分别为0和"abc"。
    var primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(0));
    primaryKey.Add("pk1", new ColumnValue("abc"));

    try
    {
        //构造请求，RowExistenceExpectation.EXPECT_EXIST表示只有此行存在时才执行删除。
        var deleteRowRequest = new DeleteRowRequest("SampleTable", new Condition(RowExistenceExpectation.EXPECT_EXIST), primaryKey);

        //调用DeleteRow接口删除数据。
        otsClient.DeleteRow(deleteRowRequest);

        //如果没有抛出异常，则说明执行成功。
        Console.Writeline("Delete table succeeded.");
    }
    catch (Exception ex)
    {
        //如果抛出异常，则说明执行失败，处理异常。
        Console.WriteLine("Delete table failed, exception:{0}", ex.Message);
    }
            

详细代码请参见DeleteRow@GitHub。