Tablestore:データの読み取り

クエリメソッド

Tablestore では、データ読み取り用に GetRow、BatchGetRow、GetRange の 3 つの操作が提供されています。クエリシナリオに応じて適切な操作を選択してください。

前提条件

作業を開始する前に、以下の準備が完了していることを確認してください。

• OTSClient インスタンスが初期化されていること。詳細については、「OTSClient インスタンスの初期化」をご参照ください。

• データが書き込まれたデータテーブルが作成済みであること。詳細については、「データテーブルの作成」および「データの書き込み」をご参照ください。

単一行のデータを読み取る

プライマリキーを使用して単一行を読み取るには、GetRow 操作を呼び出します。

API オペレーション

/// <summary>
/// 指定されたプライマリキーに基づいて単一行を読み取ります。
/// </summary>
/// <param name="request">データクエリリクエスト</param>
/// <returns>GetRow の応答</returns>
public GetRowResponse GetRow(GetRowRequest request);

/// <summary>
/// GetRow の非同期バージョン。
/// </summary>
public Task<GetRowResponse> GetRowAsync(GetRowRequest request);

パラメーター

サンプルコード

    // プライマリキーを指定します。カラムと型はテーブルスキーマと一致している必要があります。
    PrimaryKey primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(0));
    primaryKey.Add("pk1", new ColumnValue("abc"));

    try
    {
        // リクエストを構築します。columnsToGet を省略すると、行全体が返されます。
        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);
    }

    // プライマリキーを指定します。カラムと型はテーブルスキーマと一致している必要があります。
    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"));

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

    var request = new GetRowRequest(rowQueryCriteria);

    try
    {
        var response = otsClient.GetRow(request);

        // 返された行データを処理します。
        // （ここでは省略—完全な実装については GitHub のサンプルをご参照ください。）

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

複数行のデータを一度に読み取る

1 回のリクエストで 1 つ以上のテーブルから複数行を読み取るには、BatchGetRow 操作を呼び出します。各行は独立した GetRow 呼び出しとして処理され、Tablestore は各行ごとに個別の結果を返します。

注意事項

• バッチリクエスト内の一部の行が個別に失敗する可能性があります。これらの行のエラーは、例外としてスローされるのではなく、BatchGetRowResponse 内に表示されます。各行が正常に読み取られたかどうかを確認するために、常に応答を確認してください。

• リクエスト内のすべての行に同じパラメーターが適用されます。たとえば、ColumnsToGet=[colA] を設定すると、すべての行から colA のみが読み取られます。

• 1 回の BatchGetRow リクエストで読み取れる行の最大数は 100 行です。

API オペレーション

/// <summary>
/// 1 回の呼び出しで 1 つ以上のテーブルから複数行を読み取ります。
/// 各行は個別に読み取られ、個別に課金されますが、複数の GetRow 呼び出しと比較して
/// 往復のオーバーヘッドが削減されます。
/// </summary>
/// <param name="request">リクエストインスタンス</param>
/// <returns>応答インスタンス</returns>
public BatchGetRowResponse BatchGetRow(BatchGetRowRequest request);

/// <summary>
/// BatchGetRow の非同期バージョン。
/// </summary>
public Task<BatchGetRowResponse> BatchGetRowAsync(BatchGetRowRequest request);

サンプルコード

次の例では、1 回の BatchGetRow 呼び出しで 10 行を読み取ります。

// 10 行分のプライマリキーを構築します。
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);

    var response = otsClient.BatchGetRow(request);
    var tableRows = response.RowDataGroupByTable;
    var rows = tableRows[TableName];

    // 各行の結果を個別に確認します—一部の行が失敗している可能性があります。
    // （ここでは省略—完全な実装については GitHub のサンプルをご参照ください。）
}
catch (Exception ex)
{
    Console.WriteLine("Batch get row failed, exception:{0}", ex.Message);
}

詳細なサンプルコードについては、「BatchGetRow@GitHub」をご覧ください。

指定された範囲内のプライマリキー値を持つデータを読み取る

指定された範囲内のプライマリキー値を持つ行をスキャンするには、GetRange 操作を呼び出します。スキャン方向は前方または後方に設定でき、返される行数に上限を設けることも可能です。スキャンが制限（データ量、行数、予約済みスループット）に達すると、早期に停止し、nextStartPrimaryKey 値を返します。この値を後続のリクエストの開始キーとして使用し、残りの行を読み取ってください。

注意事項

GetRange は最左一致原則を使用します。Tablestore はプライマリキー列の値を左から右へ順に比較します。最初のプライマリキー列（PK1）の値が指定された範囲内にある場合、その行は返され、以降の列は評価されません。PK1 が範囲外の場合、Tablestore は同様の方法で残りの列を評価し続けます。

GetRange 操作は、以下のいずれかの制限に達すると早期に停止します。

• スキャンされたデータが 4 MB に達した場合。

• スキャンされた行数が 5,000 行に達した場合。

• 返された行数が指定された limit に達した場合。

• 次の行を読み取る前に予約済み読み取りスループットが枯渇した場合。

API オペレーション

/// <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) の間にあるすべての行をスキャンし、ページネーションを自動的に処理します。

// キー範囲を定義：pk0 は 0（含む）から 100（含まない）。
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);

    // nextStartPrimaryKey が null になるまで、すべての行を収集します。
    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);
        }
    }

    // 収集したすべての行を処理します。
    // （ここでは省略—完全な実装については GitHub のサンプルをご参照ください。）

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

詳細なサンプルコードについては、「GetRange@GitHub」をご覧ください。

イテレーターを使用して指定された範囲内のプライマリキー値を持つデータを読み取る

イテレーターを使用してプライマリキー範囲をスキャンするには、GetRangeIterator 操作を呼び出します。GetRange とは異なり、イテレーターはページネーションを自動的に処理するため、nextStartPrimaryKey を確認して後続のリクエストを手動で発行する必要はありません。

API オペレーション

/// <summary>
/// 指定された範囲内のプライマリキー値を持つ行をスキャンします。
/// ページネーションを内部で処理し、1 行ずつ返すイテレーターを返します。
/// </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"));

// 反復処理中に消費された容量単位を追跡します。
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」をご覧ください。