Tablestore:データの読み取り

API 操作

"""
説明: この操作は単一のデータ行を読み取ります。
table_name: テーブルの名前。
primary_key: プライマリキー。タイプ: dict。
columns_to_get: オプション。返す列の名前。タイプ: list。このパラメーターを指定しない場合は、すべての列が返されます。
column_filter: オプション。列のフィルター条件。条件を満たす行のみが返されます。
max_version: オプション。返すことができるデータバージョンの最大数。
time_range: オプション。返すバージョンの範囲または特定のバージョン。 max_version パラメーターと time_range パラメーターの少なくとも 1 つを設定する必要があります。
レスポンス: 操作によって消費される容量ユニット (CU) の数、および返されるプライマリキー列と属性列。
consumed: 操作によって消費される CU の数。 consumed パラメーターは、tablestore.metadata.CapacityUnit クラスのインスタンスです。
return_row: 返される行データ。プライマリキーと属性列が含まれます。タイプ: list。例: [('PK0',value0), ('PK1',value1)]。
next_token: 次のワイドカラム読み取り操作が開始される列。タイプ: binary。
例:
    primary_key = [('gid',1), ('uid',101)]
    columns_to_get = ['name', 'address', 'age']
    consumed, return_row, next_token = client.get_row('myTable', primary_key, columns_to_get)
"""
def get_row(self, table_name, primary_key, columns_to_get=None,
            column_filter=None, max_version=1, time_range=None,
            start_column=None, end_column=None, token=None,
            transaction_id=None):

パラメーター

例

次のサンプルコードは、テーブルからデータ行を読み取る方法の例を示しています。

# 最初のプライマリキー列は gid で、値は整数 1 です。2 番目のプライマリキー列は uid で、値は整数 101 です。
primary_key = [('gid', 1), ('uid', 101)]

# 読み取る列を指定します。この例では、列は属性列 name、growth、および type に設定されています。 columns_to_get パラメーターを空のままにすると、すべての属性列が返されます。
columns_to_get = ['name', 'growth', 'type']

# 列のフィルターを指定します。この例では、growth 列の値が 0.9 ではなく、name 列の値が Hangzhou である行が返されます。
cond = CompositeColumnCondition(LogicalOperator.AND)
cond.add_sub_condition(SingleColumnCondition("growth", 0.9, ComparatorType.NOT_EQUAL))
cond.add_sub_condition(SingleColumnCondition("name", 'Hangzhou', ComparatorType.EQUAL))

try:
    # get_row 操作を呼び出してデータをクエリします。
    # テーブル名を指定します。最後の値 1 は、データの 1 つのバージョンのみが返されることを指定します。
    consumed, return_row, next_token = client.get_row('<table_name>', primary_key, columns_to_get, cond, 1)
    print('読み取り成功、消費 %s 読み取り cu.' % consumed.read)
    print('プライマリキーの値: %s' % return_row.primary_key)
    print('属性の値: %s' % return_row.attribute_columns)
    for att in return_row.attribute_columns:
        # 各列のキー、値、およびバージョンを表示します。
        print('name:%s\tvalue:%s\ttimestamp:%d' % (att[0], att[1], att[2]))
# ほとんどの場合、クライアント例外はパラメーターエラーまたはネットワーク例外が原因です。
except OTSClientError as e:
    print('行の取得に失敗しました、http_status:%d、error_message:%s' % (e.get_http_status(), e.get_error_message()))
# ほとんどの場合、サーバー例外はパラメーターエラーまたはスロットリングエラーが原因です。
except OTSServiceError as e:
    print('行の取得に失敗しました、http_status:%d、error_code:%s、error_message:%s、request_id:%s' % (e.get_http_status(), e.get_error_code(), e.get_error_message(), e.get_request_id()))

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

使用上の注意

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

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

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

API 操作

"""
説明: この操作は複数のデータ行を同時に読み取ります。
request = BatchGetRowRequest()
request.add(TableInBatchGetRowItem(myTable0, primary_keys, column_to_get=None, column_filter=None))
request.add(TableInBatchGetRowItem(myTable1, primary_keys, column_to_get=None, column_filter=None))
request.add(TableInBatchGetRowItem(myTable2, primary_keys, column_to_get=None, column_filter=None))
request.add(TableInBatchGetRowItem(myTable3, primary_keys, column_to_get=None, column_filter=None))
response = client.batch_get_row(request)
response: 返された結果。 response パラメーターは、tablestore.metadata.BatchGetRowResponse クラスのインスタンスです。
"""
def batch_get_row(self, request):                    
  

パラメーター

パラメーターの詳細については、「単一のデータ行の読み取り」セクションのパラメーターテーブルを参照してください。

例

次のサンプルコードは、複数のテーブルから 3 つのデータ行を同時に読み取る方法の例を示しています。

# 返す列を指定します。
columns_to_get = ['name', 'mobile', 'address', 'age']
# 3 つのデータ行を読み取ります。
rows_to_get = []
for i in range(0, 3):
    primary_key = [('gid', i), ('uid', i + 1)]
    rows_to_get.append(primary_key)

# 列のフィルターを指定します。この例では、name 列の値が John で、address 列の値が China の場合、フィルター条件が満たされます。
cond = CompositeColumnCondition(LogicalOperator.AND)
cond.add_sub_condition(SingleColumnCondition("name", "John", ComparatorType.EQUAL))
cond.add_sub_condition(SingleColumnCondition("address", 'China', ComparatorType.EQUAL))

# 複数のデータ行を読み取るリクエストを構築します。
request = BatchGetRowRequest()

# テーブルから読み取る行を指定します。最後の値 1 は、データの最新バージョンが読み取られることを指定します。
request.add(TableInBatchGetRowItem('<table_name1>', rows_to_get, columns_to_get, cond, 1))

# 別のテーブルから読み取る行を指定します。
request.add(TableInBatchGetRowItem('<table_name2>', rows_to_get, columns_to_get, cond, 1))

try:
    result = client.batch_get_row(request)
    print('結果ステータス: %s' % (result.is_all_succeed()))

    table_result_0 = result.get_result_by_table('<table_name1>')
    table_result_1 = result.get_result_by_table('<table_name2>')
    print('最初のテーブルの結果を確認します:')
    for item in table_result_0:
        if item.is_ok:
            print('読み取り成功、PrimaryKey: %s、Attributes: %s' % (item.row.primary_key, item.row.attribute_columns))
        else:
            print('読み取り失敗、エラーコード: %s、エラーメッセージ: %s' % (item.error_code, item.error_message))
    print('2 番目のテーブルの結果を確認します:')
    for item in table_result_1:
        if item.is_ok:
            print('読み取り成功、PrimaryKey: %s、Attributes: %s' % (item.row.primary_key, item.row.attribute_columns))
        else:
            print('読み取り失敗、エラーコード: %s、エラーメッセージ: %s' % (item.error_code, item.error_message))
# ほとんどの場合、クライアント例外はパラメーターエラーまたはネットワーク例外が原因です。
except OTSClientError as e:
    print('行の取得に失敗しました、http_status:%d、error_message:%s' % (e.get_http_status(), e.get_error_message()))
# ほとんどの場合、サーバー例外はパラメーターエラーまたはスロットリングエラーが原因です。
except OTSServiceError as e:
    print('行の取得に失敗しました、http_status:%d、error_code:%s、error_message:%s、request_id:%s' % (e.get_http_status(), e.get_error_code(), e.get_error_message(), e.get_request_id()))

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

使用上の注意

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

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

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

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

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

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

各 GetRange 呼び出しはデータを 1 回スキャンします。 GetRange 操作を呼び出してスキャンするデータのサイズが大きい場合、スキャンされた行数が 5,000 に達するか、スキャンされたデータのサイズが 4 MB に達すると、スキャンは停止します。 Tablestore は、クエリ条件を満たす残りのデータを返しません。ページングメソッドを使用して、クエリ条件を満たす残りのデータを取得できます。

API 操作

"""
説明: この操作は、プライマリキー値が特定の範囲内にある行を読み取ります。
table_name: データテーブルの名前。
direction: レスポンス内の行をソートする順序。タイプ: string。有効な値: FORWARD および BACKWARD。
inclusive_start_primary_key: 読み取り操作が開始されるプライマリキー。指定された行が存在する場合、その行はレスポンスに含まれます。
exclusive_end_primary_key: 読み取り操作が終了するプライマリキー。終了プライマリキーを含む行が存在するかどうかに関係なく、その行はレスポンスから除外されます。
columns_to_get: オプション。返す列の名前。タイプ: list。このパラメーターを指定しない場合は、すべての列が返されます。
limit: オプション。返すことができる行の最大数。このパラメーターを指定しない場合は、すべての行が返されます。
column_filter: オプション。列のフィルター条件。条件を満たす行のみが返されます。
max_version:オプション。返すことができるデータバージョンの最大数。 max_version パラメーターと time_range パラメーターの少なくとも 1 つを指定する必要があります。
time_range: オプション。返すバージョンの範囲または特定のバージョン。 max_version パラメーターと time_range パラメーターの少なくとも 1 つを指定する必要があります。
start_column: オプション。ワイドカラム読み取り操作が開始される列。
end_column: オプション。ワイドカラム読み取り操作が終了する列。
token: オプション。現在のワイドカラム読み取り操作の開始列。このパラメーターの値は、以前のワイドカラム読み取り操作によって返され、バイナリデータとしてエンコードされます。

レスポンス: 条件を満たす結果。
consumed: 操作によって消費される CU の数。 consumed パラメーターは、tablestore.metadata.CapacityUnit クラスのインスタンスです。
next_start_primary_key: 次の GetRange 操作を開始するプライマリキー。タイプ: dict。
row_list: 返されたデータ行。形式: [Row, ...]。  
"""
def get_range(self, table_name, direction,
             inclusive_start_primary_key,
             exclusive_end_primary_key,
             columns_to_get=None,
             limit=None,
             column_filter=None,
             max_version=None,
             time_range=None,
             start_column=None,
             end_column=None,
             token=None):

パラメーター

例

次の例では、最初のプライマリキー列の値が指定された範囲内にあるデータが、2 番目のプライマリキー値に基づいて INF_MIN 値から INF_MAX 値まで昇順で読み取られます。次に、システムはレスポンスで next_start_primary_key パラメーターが空かどうかを確認します。空でない場合、システムは next_start_primary_key パラメーターが空になるまで GetRange 操作を再度呼び出します。

# 開始プライマリキー情報を指定します。
inclusive_start_primary_key = [('gid', 1), ('uid', INF_MIN)]

# 終了プライマリキー情報を指定します。
exclusive_end_primary_key = [('gid', 5), ('uid', INF_MAX)]

# すべての列をクエリします。
columns_to_get = []

# limit パラメーターを 90 に設定して、最大 90 行のデータを返します。合計 100 行がクエリ条件を満たす場合、最初の読み取り操作で返される行数は 0 から 90 の範囲になります。 next_start_primary_key パラメーターの値は None ではありません。
limit = 90

# 列のフィルターを指定します。この例では、address 列の値が China で、age 列の値が 50 未満の行がフィルター条件を満たします。
cond = CompositeColumnCondition(LogicalOperator.AND)
# pass_if_missing パラメーターを指定して、行に特定の列が含まれていない場合に、行がフィルター条件を満たすかどうかを決定します。
# pass_if_missing パラメーターを指定しないか True に設定すると、行に特定の列が含まれていない場合、行はフィルター条件を満たします。
# pass_if_missing パラメーターを False に設定すると、行に特定の列が含まれていない場合、行はフィルター条件を満たしません。
cond.add_sub_condition(SingleColumnCondition("address", 'China', ComparatorType.EQUAL, pass_if_missing = False))
cond.add_sub_condition(SingleColumnCondition("age", 50, ComparatorType.LESS_THAN, pass_if_missing = False))

try:
    # GetRange 操作を呼び出します。
    consumed, next_start_primary_key, row_list, next_token = client.get_range(
        '<table_name>', Direction.FORWARD,
        inclusive_start_primary_key, exclusive_end_primary_key,
        columns_to_get,
        limit,
        column_filter=cond,
        max_version=1,
        time_range = (1557125059000, 1557129059000) # start_time パラメーターの値が 1557125059000 以上で、end_time パラメーターの値が 1557129059000 未満であることを指定します。
    )

    all_rows = []
    all_rows.extend(row_list)

    # next_start_primary_key パラメーターが空でない場合は、データの読み取りを続けます。
    while next_start_primary_key is not None:
        inclusive_start_primary_key = next_start_primary_key
        consumed, next_start_primary_key, row_list, next_token = client.get_range(
            '<table_name>', Direction.FORWARD,
            inclusive_start_primary_key, exclusive_end_primary_key,
            columns_to_get, limit,
            column_filter=cond,
            max_version=1
        )
        all_rows.extend(row_list)

    # プライマリキー列と属性列を表示します。
    for row in all_rows:
        print(row.primary_key, row.attribute_columns)
    print('合計行数: ', len(all_rows))
# ほとんどの場合、クライアント例外はパラメーターエラーまたはネットワーク例外が原因です。
except OTSClientError as e:
    print('行の取得に失敗しました、http_status:%d、error_message:%s' % (e.get_http_status(), e.get_error_message()))
# ほとんどの場合、サーバー例外はパラメーターエラーまたはスロットリングエラーが原因です。
except OTSServiceError as e:
    print('行の取得に失敗しました、http_status:%d、error_code:%s、error_message:%s、request_id:%s' % (e.get_http_status(), e.get_error_code(), e.get_error_message(), e.get_request_id()))

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