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

插入一行数据(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);
        }
说明
  • 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 的时候才执行插入操作。

        // 定义行的主键,必须与创建表时的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));

        var request = new PutRowRequest(tableName, new Condition(RowExistenceExpectation.EXPECT_EXIST),
                                    primaryKey, attribute);

        // 当col0列的值大于24的时候,允许再次put row,覆盖掉原值
        try
        {
            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);
        }
说明
  • 条件不仅支持单个条件,也支持多个条件组合。例如,col1 大于 5 且 pk2 小于'xyz'时插入数据。

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

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

详细代码请参见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)

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

接口

        /// <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);
        }
说明
  • 查询一行数据时,默认返回这一行所有列的数据。如果想只返回特定行,可以通过 columnsToGet 参数限制。如果将 col0 和 col1 加入到 columnsToGet 中,则只返回 col0 和 col1 的值。

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

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

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

详细代码请参见GetRow@GitHub

示例 2

使用过滤读取一行数据。

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

        // 定义行的主键,必须与创建表时的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)

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

接口

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

接口

        /// <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
        {
            // 构造请求,Condition.EXPECT_EXIST表示只有此行存在时才执行
            var deleteRowRequest = new DeleteRowRequest("SampleTable", Condition.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