写入数据

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

前提条件

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

插入单行数据

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

更新一行数据

接口

/// <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。

批量写入数据

调用BatchWriteRow接口在一次请求中进行批量的写入操作，也支持一次对多张表进行写入。BatchWriteRow操作由多个PutRow、UpdateRow、DeleteRow子操作组成，构造子操作的过程与使用PutRow接口、UpdateRow接口和DeleteRow接口时相同，也支持使用条件更新。

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

注意事项

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

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

接口

/// <summary>
/// <para>批量插入，修改或删除一个或多个表中的若干行数据。</para>
/// <para>BatchWriteRow操作可视为多个PutRow、UpdateRow、DeleteRow操作的集合，各个操作独立执行，独立返回结果，独立计算服务能力单元。</para>
/// <para>与执行大量的单行写操作相比，使用BatchWriteRow操作可以有效减少请求的响应时间，提高数据的写入速率。</para>
/// </summary>
/// <param name="request">请求实例</param>
/// <returns>响应实例</returns>
public BatchWriteRowResponse BatchWriteRow(BatchWriteRowRequest request);

/// <summary>
/// BatchWriteRow的异步形式。
/// </summary>
/// <param name="request"></param>
/// <returns></returns>
public Task<BatchWriteRowResponse> BatchWriteRowAsync(BatchWriteRowRequest request);            

示例

批量写入100行数据。

//构造批量写的请求对象，设置100行数据的主键。
var request = new BatchWriteRowRequest();
var rowChanges = new RowChanges();
for (int i = 0; i < 100; i++)
{
    PrimaryKey primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(i));
    primaryKey.Add("pk1", new ColumnValue("abc"));

    //定义要写入该行的属性列。
    UpdateOfAttribute attribute = new UpdateOfAttribute();
    attribute.AddAttributeColumnToPut("col0", new ColumnValue(0));
    attribute.AddAttributeColumnToPut("col1", new ColumnValue("a"));
    attribute.AddAttributeColumnToPut("col2", new ColumnValue(true));

    rowChanges.AddUpdate(new Condition(RowExistenceExpectation.IGNORE), primaryKey, attribute);
}

request.Add(TableName, rowChanges);

try
{
    //调用BatchWriteRow接口写入数据。
    var response = otsClient.BatchWriteRow(request);
    var tableRows = response.TableRespones;
    var rows = tableRows[TableName];

    //批量操作可能部分成功部分失败，需要检查每行的状态是否成功，详见示例代码的GitHub链接。
}
catch (Exception ex)
{
    //如果抛出异常，则说明执行失败，处理异常。
    Console.WriteLine("Batch put row failed, exception:{0}", ex.Message);
}           

详细代码请参见BatchWriteRow@GitHub。