Tablestore:データの読み取り

クエリメソッド

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

前提条件

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

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

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

GetRow 操作を呼び出して、単一のデータ行を読み取ることができます。GetRow 操作を呼び出すと、次のいずれかの結果が返される場合があります。

• 行が存在する場合、行の主キー列と属性列が返されます。

• 行が存在しない場合、行は返されず、エラーも報告されません。

API 操作

/**
 * データ行を読み取ります。
 * @api
 * @param [] $request リクエストパラメータ。
 * @return [] レスポンス。
 * @throws OTSClientException パラメータエラーが発生した場合、または Tablestore サーバーが検証エラーを返した場合にスローされる例外。
 * @throws OTSServerException Tablestore サーバーがエラーを返した場合にスローされる例外。
 */
public function getRow(array $request);            

リクエストパラメータ

リクエスト構文

$result = $client->getRow([
    'table_name' => '<string>',                     // テーブルの名前を指定します。
    'primary_key' => [                              // 主キー情報を指定します。
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ],
    'max_versions' => <integer>,
    'time_range' => [
        'start_time' => <integer>,
        'end_time' => <integer>,
        'specific_time' => <integer>
    ],
    'start_column' => '<string>',
    'end_column' => '<string>',
    'token' => '<string>',
    'columns_to_get' => [
        '<string>',
        '<string>',
        //...
    ],
    'column_filter' =>  <ColumnCondition>
]);            

レスポンスパラメータ

レスポンス形式

[
    'consumed' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ]
    ],
    'primary_key' => [
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ],
    'attribute_columns' => [
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
    ],
    'next_token' => '<string>'
]            

サンプルコード

$request = [
    'table_name' => 'MyTable',
    'primary_key' => [ // 主キー情報を指定します。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'max_versions' => 1,                     // 最新バージョンのデータを読み取るには、このパラメータを 1 に設定します。
    'columns_to_get' => ['Col0']             // 読み取る列を指定します。
];
$response = $otsClient->getRow ($request);            

$request = [
    'table_name' => 'MyTable',
    'primary_key' => [ // 主キー情報を指定します。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'max_versions' => 1,                     // 最新バージョンのデータを読み取るには、このパラメータを 1 に設定します。
    'column_filter' => [                     // Col0 列の値が 0 である行を返すフィルタを設定します。
        'column_name' => 'Col0',
        'value' => 0,
        'comparator' => ComparatorTypeConst::CONST_EQUAL,
        'pass_if_missing' => false          // 行に Col0 列が含まれていない場合、行は返されません。
    ]
];
$response = $otsClient->getRow ($request);            

複数行のデータの同時読み取り

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

BatchGetRow 操作を呼び出すと、各 GetRow 操作は個別に実行され、Tablestore は各 GetRow 操作へのレスポンスを個別に返します。

使用上の注意

• BatchGetRow 操作を呼び出して一度に複数の行を読み取ると、一部の行の読み取りに失敗する可能性があります。この場合、Tablestore は例外を返さず、失敗した行に関する情報が含まれる BatchGetRowResponse を返します。したがって、BatchGetRow 操作を呼び出すときは、戻り値をチェックして、各行からデータが正常に読み取られたかどうかを確認する必要があります。

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

• BatchGetRow 操作を呼び出して、一度に最大 100 行を読み取ることができます。

API 操作

/**
 * 指定されたデータ行を読み取ります。
 * BatchGetRow 操作を呼び出して一度に複数の行を読み取ると、一部の行の読み取りに失敗する可能性があります。この場合、システムは例外を返さず、$response で失敗した行に関する情報を返します。詳細については、BatchGetRow 操作へのサンプルレスポンスを参照してください。
 * @api
 * @param [] $request リクエストパラメータ。
 * @return [] レスポンス。
 * @throws OTSClientException パラメータエラーが発生した場合、または Tablestore サーバーが検証エラーを返した場合に返される例外。
 * @throws OTSServerException Tablestore サーバーがエラーを返した場合に返される例外。
 */
public function batchGetRow(array $request);

            

リクエストパラメータ

リクエスト構文

$result = $client->batchGetRow([
    'tables' => [                                            // テーブルの階層を指定します。
        [
            'table_name' => '<string>',                      // テーブルの名前を指定します。
            'primary_keys' => [                              // 主キー情報を指定します。
                [
                    ['<string>', <PrimaryKeyValue>],
                    ['<string>', <PrimaryKeyValue>],
                    ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
                ],
                // その他のパラメータを指定します。
            ]
            'max_versions' => <integer>,
            'time_range' => [
                'start_time' => <integer>,
                'end_time' => <integer>,
                'specific_time' => <integer>
            ],
            'start_column' => '<string>',
            'end_column' => '<string>',
            'token' => '<string>',
            'columns_to_get' => [
                '<string>',
                '<string>',
                //...
            ],
            'column_filter' =>  <ColumnCondition>
        ],
        // その他のテーブルを指定します。
    ]
]);            

レスポンスパラメータ

レスポンス形式

[
    'tables' => [
        [
            'table_name' => '<string>',
            'rows' => [
                [
                    'is_ok' => true || false,
                    'error' => [
                        'code' => '<string>',
                        'message' => '<string>',
                    ]
                    'consumed' => [
                        'capacity_unit' => [
                            'read' => <integer>,
                            'write' => <integer>
                        ]
                    ],
                    'primary_key' => [
                        ['<string>', <PrimaryKeyValue>],
                        ['<string>', <PrimaryKeyValue>],
                        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
                    ],
                    'attribute_columns' => [
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                    ],
                    'next_token' => '<string>'
                ],
                // その他の行。
            ]
        ],
        // その他のテーブル。
    ]
]            

サンプルコード

次のサンプルコードは、3 つのテーブルから一度に 30 行のデータを読み取る方法の例を示しています。各テーブルから 10 行が読み取られます。

// 3 つのテーブルからデータを読み取ります。各テーブルから 10 行が読み取られます。
$tables = array();
for($i = 0; $i < 3; $i++) {
    $primary_keys = array();
    for($j = 0; $j < 10; $j++) {
        $primary_keys[] = [
            ['pk0', $i],
            ['pk1', $j]
        ];
    }
    $tables[] = [
        'table_name' => 'SampleTable' . $i,
        'max_versions' => 1,
        'primary_keys' => $primary_keys
    ];
}
$request = [
    'tables' => $tables
];
$response = $otsClient->batchGetRow ($request);

// 各テーブルから返されたデータを処理します。
foreach ($response['tables'] as $tableData) {
  print "テーブル {$tableData['table_name']} を処理しています...\n";

  // テーブル内のデータの各行を処理します。
  foreach ($tableData['rows'] as $rowData) {

    if ($rowData['is_ok']) {

      // 読み取られたデータを処理します。
        $row = json_encode($rowData['primary_key']);
        print "行を処理しています: {$row}\n";

    } else {

      // エラーを処理します。
      print "エラー: {$rowData['error']['code']} {$rowData['error']['message']}\n";
    }
  }
}            

次の表に、詳細なサンプルコードの例を示します。

主キー値が特定の範囲内にあるデータの読み取り

GetRange 操作を呼び出して、主キー値が指定された範囲内にあるデータを読み取ることができます。

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

使用上の注意

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

次のいずれかの条件が満たされると、GetRange 操作が停止してデータが返される場合があります。

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

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

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

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

API 操作

/**
 * 開始主キー情報と終了主キー情報で指定された範囲内にある主キー値を持つデータを読み取ります。
 * サーバーはこの範囲を切り捨てる場合があります。この場合、レスポンスで返される next_start_primary_key パラメータの値に基づいて、GetRange 操作を再度呼び出すかどうかを判断する必要があります。
 * 読み取る行の最大数を指定できます。
 * 開始主キー情報と終了主キー情報を指定する場合、INF_MIN を使用して最小値を指定し、INF_MAX を使用して最大値を指定できます。詳細については、次のサンプルコードを参照してください。
 * @api
 * @param [] $request リクエストパラメータ。
 * @return [] レスポンス。
 * @throws OTSClientException パラメータエラーが発生した場合、または Tablestore サーバーが検証エラーを返した場合に返される例外。
 * @throws OTSServerException Tablestore サーバーがエラーを返した場合に返される例外。
 */
public function getRange(array $request);            

パラメータ

リクエスト構文

$result = $client->getRange([
    'table_name' => '<string>',                                     // テーブル名を指定します。
    'inclusive_start_primary_key' => [                              // 開始プライマリキー情報を指定します。
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'exclusive_end_primary_key' => [                                // 終了プライマリキー情報を指定します。
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'direction' => <Direction>,                                     // レスポンス内の行をソートする順序を指定します。
    'limit' => <Direction>,
    'max_versions' => <integer>,
    'time_range' => [
        'start_time' => <integer>,
        'end_time' => <integer>,
        'specific_time' => <integer>
    ],
    'start_column' => '<string>',
    'end_column' => '<string>',
    'token' => '<string>',
    'columns_to_get' => [
        '<string>',
        '<string>',
        //...   
    ],
    'column_filter' =>  <ColumnCondition>
]);      

レスポンスパラメーター

レスポンス形式

[
    'consumed' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ]
    ],
    'next_start_primary_key' => [ 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'rows' => [
        [
            'primary_key' => [ 
                ['<string>', <PrimaryKeyValue>], 
                ['<string>', <PrimaryKeyValue>],
                ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
            ],  
            'attribute_columns' => [
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>],
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>],
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ]
        ],
        // 他の行。
    ]
]
            

サンプルコード

次のサンプルコードは、プライマリキー値が指定された範囲内にあるデータを読み取る方法の例を示しています。

// PK0 列の値が [1, 4) の範囲にある行をクエリします。
// 範囲を指定するには、完全な主キー列を指定する必要があります。クエリ範囲に列の値が含まれていない場合は、列の値を無限大 (INF_MAX) または無限小 (INF_MIN) に設定します。
$startPK = [
    ['PK0', 1], 
    ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MIN]  // INF_MIN は無限小の値を示します。
];
// 範囲を指定するには、完全な主キー列を指定する必要があります。クエリ範囲に列の値が含まれていない場合は、列の値を無限大 (INF_MAX) または無限小 (INF_MIN) に設定します。
$endPK = [
    ['PK0', 4], 
    ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MAX]  // INF_MAX は無限大の値を示します。
];
$request = [
    'table_name' => 'SampleTable',
    'max_versions' => 1,                          // このパラメータを 1 に設定すると、最新バージョンが読み取られます。
    'direction' => DirectionConst::CONST_FORWARD, // データを順方向にクエリします。
    'inclusive_start_primary_key' => $startPK,    // 開始主キー情報を指定します。
    'exclusive_end_primary_key' => $endPK,        // 終了主キー情報を指定します。
    'limit' => 10                                 // このパラメータを 10 に設定すると、最大 10 行のデータを返すことができます。
];
$response = $otsClient->getRange ($request);
print "Read CU Consumed: {$response['consumed']['capacity_unit']['read']}\n";

foreach ($response['rows'] as $rowData) {
  // 各データ行を処理します。
}           

次の表は、詳細なサンプルコードの例を示しています。