edit-icon download-icon

BatchGetRow

最終更新日: Apr 17, 2018

BatchGetRow

アクション:

1 つ以上のテーブルから複数のデータ行を一括して読み取ります。

BatchGetRow 操作は、複数の GetRow 操作を 1 セットとして表示できます。各操作は独立して実行され、それぞれが独自に結果を返して容量単位を使用します。

BatchGetRow 操作を使用すると、GetRow 操作を大量に実行する場合に比べて、リクエスト応答時間が効果的に減り、データ読み取り速度を向上させることができます。

リクエストの構造:

  1. message BatchGetRowRequest {
  2. repeated TableInBatchGetRowRequest tables = 1;
  3. }

tables

  • 型: repeated TableInBatchGetRowRequest

  • 必須パラメーター: はい

  • 読み取る行の情報を指定します。

  • tablesが以下のいずれかの条件を持っている場合、操作全体が失敗し、エラーを返します:

    • “tables” にはテーブルが存在しない。
    • “tables” のいずれかのテーブルの名前がテーブルの命名規則に準拠していない。
    • “tables” のいずれかの行に対してプライマリキーが指定されていない、プライマリキー名が規則に準拠していない、またはプライマリキーの型が正しくない。
    • “tables” のいずれかの列に対して、columns_to_get の中に含まれる列の名前は 列の命名規則に準拠していない。
    • “tables” に同じ名前のテーブルが含まれている。
    • “tables” のいずれかのテーブルに同一のプライマリキーを持つ行が含まれている。
    • “tables” の RowInBatchGetRowRequest の合計数が 100 を超えている。
    • “tables” のどのテーブルにも RowInBatchGetRowRequest が含まれていない。
    • “tables” のいずれかのテーブルの columns_to_get が 128 列を超えている。

応答メッセージの構造:

  1. message BatchGetRowResponse {
  2. repeated TableInBatchGetRowResponse tables = 1;
  3. }

tables

型: repeated TableInBatchGetRowResponse

  • 各テーブルで読み取るデータに相当します。

  • 応答メッセージ内の TableInBatchGetRowResponse オブジェクトの順序は、BatchGetRowRequest での TableInBatchGetRowRequest オブジェクトの順序と同じです。TableInBatchGetRowResponse における各 RowInBatchGetRowResponse の順序は、TableInBatchGetRowRequest における RowInBatchGetRowRequest の順序と同じです。

  • 行が存在しないか、行に指定した columns_to_get のデータがない場合でも、対応する RowInBatchGetRowResponse が TableInBatchGetRowResponse に表示されますが、行の primary_key_columns と attribute_columns は null になります。

  • 行の読み取りに失敗した場合、行の RowInBatchGetRowResponse の is_ok 値は false になり、行は null になります。

: BatchGetRow 操作は行レベルで部分的に失敗することがあります。このような場合でも、200 という HTTP ステータスコードが返されます。アプリケーションでは RowInBatchGetRowResponse のエラーをチェックして、各行の実行結果を確認してから、その結果に従って進める必要があります。

容量単位の使用:

  • 操作全体が失敗した場合は、容量単位が使用されることはありません。

  • リクエストタイムアウトが発生し、結果が定義されていない場合は、容量単位が使用される場合とされない場合、どちらもありえます。

  • その他の状況では、書き込み容量単位がカウントされると、RowInBatchGetRowRequest 操作ごとに 1 回の GetRow 操作として表示されます。

リクエストの例:

  1. BatchGetRowRequest {
  2. tables {
  3. table_name: "consume_history"
  4. rows {
  5. primary_key {
  6. name: "CardID"
  7. value {
  8. type: STRING
  9. v_string: "2007035023"
  10. }
  11. }
  12. primary_key {
  13. name: "SellerID"
  14. value {
  15. type: STRING
  16. v_string: "00022"
  17. }
  18. }
  19. primary_key {
  20. name: "DeviceID"
  21. value {
  22. type: STRING
  23. v_string: "061104"
  24. }
  25. }
  26. primary_key {
  27. name: "OrderNumber"
  28. value {
  29. type: INTEGER
  30. v_int: 142857
  31. }
  32. }
  33. }
  34. rows {
  35. primary_key {
  36. name: "CardID"
  37. value {
  38. type: STRING
  39. v_string: "2007035023"
  40. }
  41. }
  42. primary_key {
  43. name: "SellerID"
  44. value {
  45. type: STRING
  46. v_string: "00026"
  47. }
  48. }
  49. primary_key {
  50. name: "DeviceID"
  51. value {
  52. type: STRING
  53. v_string: "065499"
  54. }
  55. }
  56. primary_key {
  57. name: "OrderNumber"
  58. value {
  59. type: INTEGER
  60. v_int: 153846
  61. }
  62. }
  63. }
  64. columns_to_get: "CardID"
  65. columns_to_get: "SellerID"
  66. columns_to_get: "DeviceID"
  67. columns_to_get: "OrderNumber"
  68. columns_to_get: "Amount"
  69. columns_to_get: "Remarks"
  70. }
  71. }

応答の例:

  1. BatchGetRowResponse {
  2. tables {
  3. table_name: "consume_history"
  4. rows {
  5. is_ok: true
  6. consumed {
  7. capacity_unit {
  8. read: 1
  9. }
  10. }
  11. row {
  12. primary_key_columns {
  13. name: "CardID"
  14. value {
  15. type: STRING
  16. v_string: "2007035023"
  17. }
  18. }
  19. primary_key_columns {
  20. name: "SellerID"
  21. value {
  22. type: STRING
  23. v_string: "00022"
  24. }
  25. }
  26. primary_key_columns {
  27. name: "DeviceID"
  28. value {
  29. type: STRING
  30. v_string: "061104"
  31. }
  32. }
  33. primary_key_columns {
  34. name: "OrderNumber"
  35. value {
  36. type: INTEGER
  37. v_int: 142857
  38. }
  39. }
  40. attribute_columns {
  41. name: "Amount"
  42. value {
  43. type: DOUBLE
  44. v_double: 2.5
  45. }
  46. }
  47. attribute_columns {
  48. name: "Remarks"
  49. value {
  50. type: STRING
  51. v_string: "ice cream"
  52. }
  53. }
  54. }
  55. }
  56. rows {
  57. is_ok: true
  58. consumed {
  59. capacity_unit {
  60. read: 1
  61. }
  62. }
  63. row {
  64. primary_key_columns {
  65. name: "CardID"
  66. value {
  67. type: STRING
  68. v_string: "2007035023"
  69. }
  70. }
  71. primary_key_columns {
  72. name: "SellerID"
  73. value {
  74. type: STRING
  75. v_string: "00026"
  76. }
  77. }
  78. primary_key_columns {
  79. name: "DeviceID"
  80. value {
  81. type: STRING
  82. v_string: "065499"
  83. }
  84. }
  85. primary_key_columns {
  86. name: "OrderNumber"
  87. value {
  88. type: INTEGER
  89. v_int: 153846
  90. }
  91. }
  92. attribute_columns {
  93. name: "Amount"
  94. value {
  95. type: DOUBLE
  96. v_double: 0.5
  97. }
  98. }
  99. }
  100. }
  101. }
  102. }