表格存储提供了PutRow、GetRow、UpdateRow和DeleteRow等单行操作的接口。
如果需要了解表格存储各场景的应用案例,请参见快速玩转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);
参数
参数 | 说明 |
---|---|
tableName | 数据表名称。 |
primaryKey | 行的主键。
说明
|
attribute | 行的属性列。
|
condition | 支持使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件。更多信息,请参见条件更新。
说明
|
示例
- 示例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);
参数
参数 | 说明 |
---|---|
tableName | 数据表名称。 |
primaryKey | 行的主键。
说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
|
columnsToGet | 读取的列集合,列名可以是主键列或属性列。
如果不设置返回的列名,则返回整行数据。 说明
|
maxVersions | 最多读取的版本数。
说明 maxVersions与timeRange必须至少设置一个。
|
timeRange | 读取版本号范围或特定版本号的数据。更多信息,请参见TimeRange。
说明 maxVersions与timeRange必须至少设置一个。
SpecificTime和 时间戳的单位为毫秒,最小值为0,最大值为Int64.MaxValue。 |
filter | 使用过滤器,在服务端对读取结果再进行一次过滤,只返回符合过滤器中条件的数据行。更多信息,请参见过滤器。
说明 当columnsToGet和filter同时使用时,执行顺序是先获取columnsToGet指定的列,再在返回的列中进行条件过滤。
|
示例
- 示例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);
参数
参数 | 说明 |
---|---|
tableName | 数据表名称。 |
primaryKey | 行的主键。
说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
|
condition | 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件。更多信息,请参见条件更新。 |
attribute | 更新的属性列。
|
示例
更新一行数据。
//定义行的主键,必须与创建表时的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);
参数
参数 | 说明 |
---|---|
tableName | 数据表名称。 |
primaryKey | 行的主键。
说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
|
condition | 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件。更多信息,请参见条件更新。 |
示例
删除一行数据。
//要删除的行的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。