すべてのプロダクト
Search

このプロダクト

    Tablestore:GetRow

    ドキュメントセンター

    Tablestore:GetRow

    最終更新日:Nov 04, 2025

    指定されたプライマリキーに基づいて、単一の行のデータを読み取ります。

    リクエスト構文

    message GetRowRequest {
    required string table_name = 1;
    required bytes primary_key = 2; // データは PlainBuffer フォーマットのバイナリデータとしてエンコードされます。
    repeated string columns_to_get = 3; // このパラメーターを指定しない場合、すべての列が読み取られます。
    optional TimeRange time_range = 4;
    optional int32 max_versions = 5;
    optional bytes filter = 7;
    optional string start_column = 8;
    optional string end_column = 9;
    optional bytes token = 10;
    optional string transaction_id = 11;
}

    パラメーター

    タイプ

    必須

    説明

    table_name

    string

    はい

    データを読み取るテーブルの名前。

    primary_key

    bytes

    はい

    行のすべてのプライマリキー列 (プライマリキー列の名前と値を含む)。プライマリキー列は PlainBuffer フォーマットでエンコードされます。詳細については、「PlainBuffer」をご参照ください。

    columns_to_get

    string

    いいえ

    返す列の名前。このパラメーターを指定しない場合、行のすべての列が返されます。このパラメーターの値には、最大 128 個の文字列を含めることができます。

    指定された列が存在しない場合、指定された列のデータは返されません。重複する列名を指定した場合、応答にはこの列が 1 回だけ含まれます。

    time_range

    TimeRange

    いいえ (time_range と max_versions のうち少なくとも 1 つを指定する必要があります。)

    データの複数バージョンを読み取るタイムスタンプ範囲。最小値は 0、最大値は INT64.MAX です。単位: ミリ秒。

    指定された時間範囲内のデータをクエリする場合は、start_time と end_time を指定します。指定されたタイムスタンプを含むデータをクエリする場合は、specific_time を指定します。

    たとえば、time_range の値が [100, 200) の場合、返される列のデータのタイムスタンプは [100, 200) の範囲内である必要があります。

    max_versions

    int32

    いいえ (time_range と max_versions のうち少なくとも 1 つを指定する必要があります。)

    返されるデータの最大バージョン数。

    max_versions の値が 2 の場合、各列に対して最大 2 つのバージョンのデータが返されます。

    filter

    bytes

    いいえ

    フィルター条件の式。フィルター条件の式は、Protobuf を使用してバイナリデータとしてシリアル化されます。詳細については、「Filter」をご参照ください。

    start_column

    string

    いいえ

    行内で読み取り操作を開始する列。このパラメーターは、ワイドカラムを読み取るために使用されます。列は、名前のアルファベット順にソートされます。応答には、指定された開始列が含まれます。

    テーブルに列 a、b、c が含まれ、start_column の値が b の場合、読み取り操作は列 b から開始され、列 b と c が返されます。

    end_column

    string

    いいえ

    読み取り操作を終了する列。応答には、指定された終了列は含まれません。列は、名前のアルファベット順にソートされます。

    例: テーブルに列 a、b、c が含まれ、end_column の値が b の場合、読み取り操作は列 b で終了し、列 a のみが返されます。

    token

    bytes

    いいえ

    ワイドカラムで次の読み取り操作を開始する位置。このパラメーターは使用できません。

    transaction_id

    string

    いいえ

    ローカルトランザクションの ID。ローカルトランザクション機能を使用してデータを読み取る場合、このパラメーターは必須です。

    応答構文

    message GetRowResponse {
    required ConsumedCapacity consumed = 1;
    required bytes row = 2; // データは PlainBuffer フォーマットのバイナリデータとしてエンコードされます。
    optional bytes next_token = 3;
}

    パラメーター

    タイプ

    説明

    consumed

    ConsumedCapacity

    操作によって消費される容量単位 (CU) の数。詳細については、「CU 消費量」をご参照ください。

    row

    bytes

    行から読み取られたデータ。リクエストされた行が存在しない場合、データは返されません。

    返されるデータは PlainBuffer フォーマットでエンコードされます。PlainBuffer の詳細については、「PlainBuffer」をご参照ください。

    next_token

    bytes

    リクエストで行のデータ列数が 128 を超えた場合に返されるトークン。

    Tablestore SDK の使用

    次の Tablestore SDK を使用して、1 行のデータを読み取ります。

    CU 消費量

    • リクエストされた行が存在しない場合、1 読み取り CU が消費されます。

    • リクエストされた行が存在する場合、消費される読み取り CU の数は、次の数式を使用して計算された値から切り上げられます: 消費される読み取り CU 数 = (行のすべてのプライマリキー列のデータサイズ + 読み取られる属性列のデータサイズ) / 4 KB。データサイズの計算方法の詳細については、「課金の概要」をご参照ください。

    • リクエストがタイムアウトし、結果が未定義の場合、CU は消費される場合とされない場合があります。

    • 内部エラーが発生したことを示す HTTP ステータスコード 5xx が返された場合、操作は CU を消費しません。他のエラーが返された場合、1 読み取り CU が消費されます。