Tablestore:データの読み取り

クエリメソッド

Tablestore は、データを読み取るための GetRow、BatchGetRow、および GetRange 操作を提供します。データを読み取る前に、実際のクエリシナリオに基づいて適切なクエリメソッドを選択してください。

前提条件

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

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

単一のデータ行の読み取り

GetRow 操作を呼び出して、単一のデータ行を読み取ることができます。 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);          

パラメータ

サンプルコード

    // 行の主キー情報を指定します。主キー情報は、テーブルの作成時に 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);
    }
            

    // 行のプライマリキー情報を指定します。プライマリキー情報は、テーブルの作成時に 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 を読み取る列として指定します。Tablestore は 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);
    }          

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

BatchGetRowオペレーションを呼び出して、一度に1つ以上のテーブルから複数の行のデータを読み取ることができます。BatchGetRowオペレーションは、複数のGetRowオペレーションで構成されています。BatchGetRowオペレーションを呼び出す場合、各GetRowオペレーションを構成するプロセスは、GetRowオペレーションを呼び出す場合のGetRowオペレーションを構成するプロセスと同じです。

BatchGetRowオペレーションを呼び出すと、各GetRowオペレーションは個別に実行され、Tablestoreは各GetRowオペレーションへの応答を個別に返します。

使用上の注意

• BatchGetRowオペレーションを呼び出して一度に複数の行を読み取ると、一部の行の読み取りに失敗する場合があります。このような場合、Tablestoreは例外を返さず、失敗した行の情報を含むBatchGetRowResponseを返します。そのため、BatchGetRowオペレーションを呼び出す場合は、戻り値を確認して、各行からデータが正常に読み取られたかどうかを確認する必要があります。

• BatchGetRowオペレーションでは、すべての行に同じパラメータ設定が使用されます。たとえば、ColumnsToGetパラメータが[colA]に設定されている場合、すべての行からcolA列の値のみが読み取られます。

• BatchGetRowオペレーションを呼び出して、一度に最大100行を読み取ることができます。

API操作

/// <summary>
/// <para>一度に1つ以上のテーブルから複数の行のデータを読み取ります。</para>
/// <para>BatchGetRow操作は、GetRow操作のセットです。各操作は独立して実行され、結果を返し、消費された容量ユニット（CU）を計算します。</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行のデータのプライマリキー情報を指定します。
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操作を呼び出して、10行のデータを読み取ります。
    var response = otsClient.BatchGetRow(request);
    var tableRows = response.RowDataGroupByTable;
    var rows = tableRows[TableName];

    // 行のデータを返します。この例では、行のデータを返すために使用されるサンプルコードは省略されています。詳細なサンプルコードを表示するには、このサンプルコードに提供されているGitHubリンクにアクセスしてください。

    // BatchGetRow操作を呼び出して一度に複数の行を読み取ると、一部の行の読み取りに失敗する場合があります。戻り値を確認して、各行からデータが正常に読み取られたかどうかを確認する必要があります。詳細なサンプルコードを表示するには、このサンプルコードに提供されているGitHubリンクにアクセスしてください。
}
catch (Exception ex)
{
    // 操作が失敗した場合、例外が返されます。例外を処理します。
    Console.WriteLine("Batch get row failed, exception:{0}", ex.Message);
}            

詳細なサンプルコードを表示するには、BatchGetRow@GitHubにアクセスしてください。

特定の範囲内のプライマリキー値を持つデータの読み取り

GetRangeオペレーションを呼び出して、プライマリキー値が指定された範囲内にあるデータを読み取ることができます。

GetRangeオペレーションを使用すると、プライマリキー値が指定された範囲内にあるデータを順方向または逆方向に読み取ることができます。読み取る行数を指定することもできます。範囲が広く、スキャンされた行数またはスキャンされたデータの量が上限を超えると、スキャンは停止し、読み取られた行と次の行のプライマリキーに関する情報が返されます。前回のオペレーションが中断したところから開始するリクエストを開始し、前回のオペレーションによって返された次の行のプライマリキー情報に基づいて残りの行を読み取ることができます。

使用上の注意

GetRangeオペレーションは左端一致の原則に従います。Tablestoreは、プライマリキー値が指定された範囲内にあるデータを読み取るために、最初のプライマリキー列から最後のプライマリキー列まで順番に値を比較します。たとえば、データテーブルのプライマリキーがPK1、PK2、PK3というプライマリキー列で構成されているとします。データの読み取り時に、Tablestoreはまず、行のPK1値が最初のプライマリキー列に指定された範囲内にあるかどうかを判断します。行のPK1値が範囲内にある場合、Tablestoreは、行の他のプライマリキー列の値が各プライマリキー列に指定された範囲内にあるかどうかの判断を停止し、行を返します。行のPK1値が範囲内にない場合、Tablestoreは、PK1と同じ方法で、行の他のプライマリキー列の値が各プライマリキー列に指定された範囲内にあるかどうかを判断し続けます。

次のいずれかの条件が満たされると、GetRangeオペレーションは停止してデータを返す場合があります。

• スキャンされたデータ量が4 MBに達する。

• スキャンされた行数が5,000に達する。

• 返された行数が上限に達する。

• 予約済みの読み取りスループットがすべて消費されているため、読み取りスループットが次のデータ行を読み取るのに不十分である。

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)の範囲内にあるすべての行を読み取ります。
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);
        }
    }

    // 行のデータを返します。この例では、行のデータを返すために使用されるサンプルコードは省略されています。詳細なサンプルコードを表示するには、このサンプルコードに提供されているGitHubリンクにアクセスしてください。

    // 操作が成功した場合、例外は返されません。
    Console.WriteLine("範囲の取得に成功しました");
}
catch (Exception ex)
{
    // 操作が失敗した場合、例外が返されます。例外を処理します。
    Console.WriteLine("範囲の取得に失敗しました。例外：{0}", ex.Message);
}            

詳細なサンプルコードを表示するには、GetRange@GitHubにアクセスしてください。

特定の範囲内のプライマリキー値を持つデータのイテレータを使用した読み取り

GetRangeIterator オペレーションを呼び出すことで、指定された範囲内のプライマリキー値を持つデータをイテレータを使用して読み取ることができます。

API オペレーション

/// <summary>
/// プライマリキー値が指定された範囲内にある複数の行からデータを取得します。各データ行を処理するために使用されるイテレータを返します。
/// </summary>
/// <param name="request"><see cref="GetIteratorRequest"/></param>
/// <returns><see cref="RowDataFromGetRange"/> イテレータを返します。</returns>
public IEnumerable<RowDataFromGetRange> GetRangeIterator(GetIteratorRequest request);           

サンプルコード

次のサンプルコードは、プライマリキー値が (0, "a") から (1000, "xyz") の範囲内にあるすべての行を読み取る方法の例を示しています。

// プライマリキー値が (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"));

// イテレーションによって消費される CU 数を記録するための CapacityUnit オブジェクトを構築します。
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("行の反復処理に成功しました");
} 
catch (Exception ex)
{
    Console.WriteLine("行の反復処理に失敗しました。例外: {0}", ex.Message);
}            

詳細なサンプルコードについては、GetRangeIterator@GitHub を参照してください。