多行数据操作_.NET SDK_SDK 参考

表格存储的 SDK 提供了 BatchGetRow、BatchWriteRow、GetRange 和 GetRangeIterator 等多行操作的接口。

批量读（BatchGetRow）

批量读取一个或多个表中的若干行数据。

BatchGetRow 操作可视为多个 GetRow 操作的集合，各个操作独立执行，独立返回结果，独立计算服务能力单元。

与执行大量的 GetRow 操作相比，使用 BatchGetRow 操作可以有效减少请求的响应时间，提高数据的读取速率。

接口

        /// <summary>
        /// <para>批量读取一个或多个表中的若干行数据。</para>
        /// <para>BatchGetRow操作可视为多个GetRow操作的集合，各个操作独立执行，独立返回结果，独立计算服务能力单元。</para>
        /// 与执行大量的GetRow操作相比，使用BatchGetRow操作可以有效减少请求的响应时间，提高数据的读取速率。
        /// </summary>
        /// <param name="request">请求实例</param>
        /// <returns>响应实例</returns>
        public BatchGetRowResponse BatchGetRow(BatchGetRowRequest request);

        /// <summary>
        /// BatchGetRow的异步形式。
        /// </summary>
        public Task<BatchGetRowResponse> BatchGetRowAsync(BatchGetRowRequest request);

示例

批量一次读 10 行。

        // 构造批量读取请求的对象，设置10行的pk值
        List<PrimaryKey> primaryKeys = new List<PrimaryKey>();
        for (int i = 0; i < 10; i++)
        {
            PrimaryKey primaryKey = new PrimaryKey();
            primaryKey.Add("pk0", new ColumnValue(i));
            primaryKey.Add("pk1", new ColumnValue("abc"));
            primaryKeys.Add(primaryKey);
        }

        try
        {
            BatchGetRowRequest request = new BatchGetRowRequest();
            request.Add(TableName, primaryKeys);

            // 调用BatchGetRow，查询十行数据
            var response = otsClient.BatchGetRow(request);
            var tableRows = response.RowDataGroupByTable;
            var rows = tableRows[TableName];

            // 输入rows里的数据，这里省略，详见下面GitHub链接

            // 批量操作可能部分成功部分失败，需要为每行检查状态，详见下面GitHub链接
        }
        catch (Exception ex)
        {
            // 如果抛出异常，则说明执行失败，打印出错误信息
            Console.WriteLine("Batch get row failed, exception:{0}", ex.Message);
        }

说明批量读也支持通过条件语句过滤。

详细代码请参见BatchGetRow@GitHub。

批量写（BatchWriteRow）

批量插入、修改或删除一个或多个表中的若干行数据。

BatchWriteRow 操作可视为多个 PutRow、UpdateRow 和 DeleteRow 操作的集合，各个操作独立执行，独立返回结果，独立计算服务能力单元。

接口

        /// <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行数据的pk
        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。

范围读（GetRange）

读取指定主键范围内的数据。

接口

        /// <summary>
        /// 根据范围条件获取多行数据。
        /// </summary>
        /// <param name="request">请求实例</param>
        /// <returns>响应实例</returns>
        public GetRangeResponse GetRange(GetRangeRequest request);

        /// <summary>
        /// GetRange的异步版本。
        /// </summary>
        /// <param name="request"></param>
        /// <returns></returns>
        public Task<GetRangeResponse> GetRangeAsync(GetRangeRequest request);

示例

范围读取。

        // 读取 (0, INF_MIN)到(100, INF_MAX)这个范围内的所有行
        var inclusiveStartPrimaryKey = new PrimaryKey();
        inclusiveStartPrimaryKey.Add("pk0", new ColumnValue(0));
        inclusiveStartPrimaryKey.Add("pk1", ColumnValue.INF_MIN);

        var exclusiveEndPrimaryKey = new PrimaryKey();
        exclusiveEndPrimaryKey.Add("pk0", new ColumnValue(100));
        exclusiveEndPrimaryKey.Add("pk1", ColumnValue.INF_MAX);

        try
        {
            // 构造范围查询请求对象
            var request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
                            inclusiveStartPrimaryKey, exclusiveEndPrimaryKey);

            var response = otsClient.GetRange(request);

            // 如果一次没有返回所有数据，则需要继续查询
            var rows = response.RowDataList;
            var nextStartPrimaryKey = response.NextPrimaryKey;
            while (nextStartPrimaryKey != null)
            {
                request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
                                nextStartPrimaryKey, exclusiveEndPrimaryKey);
                response = otsClient.GetRange(request);
                nextStartPrimaryKey = response.NextPrimaryKey;
                foreach (RowDataFromGetRange row in response.RowDataList)
                {
                    rows.Add(row);
                }
            }

            // 输出Rows的数据，这里省略，详见下面GitHub链接

            // 如果没有抛出异常，则说明执行成功
            Console.WriteLine("Get range succeeded");
        }
        catch (Exception ex)
        {
            // 如果抛出异常，则说明执行失败，打印出错误信息
            Console.WriteLine("Get range failed, exception:{0}", ex.Message);
        }

说明按范围读也支持通过条件语句过滤。

详细代码请参见GetRange@GitHub。

迭代读（GetRangeIterator）

获取一个范围查询的迭代器。

接口

        /// <summary>
        /// 根据范围条件获取多行数据，返回用来迭代每一行数据的迭代器。
        /// </summary>
        /// <param name="request"><see cref="GetIteratorRequest"/></param>
        /// <returns>返回<see cref="RowDataFromGetRange"/>的迭代器。</returns>
        public IEnumerable<RowDataFromGetRange> GetRangeIterator(GetIteratorRequest request);

示例

迭代读取。

        // 读取 (0, "a")到(1000, "xyz")这个范围内的所有行
        PrimaryKey inclusiveStartPrimaryKey = new PrimaryKey();
        inclusiveStartPrimaryKey.Add("pk0", new ColumnValue(0));
        inclusiveStartPrimaryKey.Add("pk1", new ColumnValue("a"));

        PrimaryKey exclusiveEndPrimaryKey = new PrimaryKey();
        exclusiveEndPrimaryKey.Add("pk0", new ColumnValue(1000));
        exclusiveEndPrimaryKey.Add("pk1", new ColumnValue("xyz"));

        // 构造一个CapacityUnit，用于记录迭代过程中消耗的CU值
        var cu = new CapacityUnit(0, 0);

        try
        {
            // 构造一个GetIteratorRequest，这里也支持过滤条件
            var request = new GetIteratorRequest(TableName, GetRangeDirection.Forward, inclusiveStartPrimaryKey,
                                                exclusiveEndPrimaryKey, cu);

            var iterator = otsClient.GetRangeIterator(request);
            // 遍历迭代器，读取数据
            foreach (var row in iterator)
            {
                // 处理逻辑
            }

            Console.WriteLine("Iterate row succeeded");
        } 
        catch (Exception ex)
        {
            Console.WriteLine("Iterate row failed, exception:{0}", ex.Message);
        }

说明读数据迭代器也支持通过条件语句过滤

详细代码请参见GetRangeIterator@GitHub。