表格存儲的數據操作__開發指南_表格存儲-阿裏雲

消耗的讀服務能力單元為 1218 Byte 除以 4 KB 向上取整，該 GetRow 操作消耗 1 個單位的讀服務能力單元。

更多信息請參見 API Reference 的 GetRow。

多行操作

表格存儲提供了 BatchWriteRow 和 BatchGetRow 兩種多行操作。

BatchWriteRow 用於插入、修改、刪除一個表或者多個表中的多行記錄。BatchWriteRow 操作由多個 PutRow、UpdateRow、DeleteRow 子操作組成。BatchWriteRow 的各個子操作獨立執行，表格存儲會將各個子操作的執行結果分別返回給應用程序，可能存在部分請求成功、部分請求失敗的現象。即使整個請求沒有返回錯誤，應用程序也必須要檢查每個子操作返回的結果，從而拿到正確的狀態。BatchWriteRow 的各個子操作單獨計算寫服務能力單元。

BatchGetRow 用於讀取一個表或者多個表中的多行記錄。BatchGetRow 各個子操作獨立執行，表格存儲會將各個子操作的執行結果分別返回給應用程序，可能存在部分請求成功、部分請求失敗的現象。即使整個請求沒有返回錯誤，應用程序也必須要檢查每個子操作返回的結果，從而拿到正確的狀態。BatchGetRow 的各個子操作單獨計算讀服務能力單元。

更多信息請參見 API Reference 中的 BatchWriteRow 與 BatchGetRow章節。

範圍讀取操作

表格存儲提供了範圍讀取操作 GetRange，該操作將指定主鍵範圍內的數據返回給應用程序。

表格存儲表中的行按主鍵進行從小到大排序，GetRange 的讀取範圍是一個左閉右開的區間。操作會返回主鍵屬於該區間的行數據，區間的起始點是有效的主鍵或者是由 INF_MIN 和 INF_MAX 類型組成的虛擬點，虛擬點的列數必須與主鍵相同。其中，INF_MIN 表示無限小，任何類型的值都比它大；INF_MAX 表示無限大，任何類型的值都比它小。

GetRange 操作需要指定請求列名，請求列名中可以包含多個列名。如果某一行的主鍵屬於讀取的範圍，但是不包含指定返回的列，那麼請求返回結果中不包含該行數據。不指定請求列名，則返回完整的行。

GetRange 操作需要指定讀取方向，讀取方向可以為正序或逆序。假設同一表中有兩個主鍵 A 和 B，A<B。如正序讀取 [A, B)，則按從 A 至 B 的順序返回主鍵大於等於 A、小於 B 的行。逆序讀取 [B,A)，則按從 B 至 A 的順序返回大於 A、小於等於 B 的數據。

GetRange 操作可以指定最大返回行數。表格存儲按照正序或者逆序最多返回指定的行數之後即結束該操作的執行，即使該區間內仍有未返回的數據。

GetRange 操作可能在以下幾種情況下停止執行並返回數據給應用程序：

• 返回的行數據大小之和達到 1 MB。

• 返回的行數等於 5000。

• 返回的行數等於最大返回行數。

• 當前剩餘的預留讀吞吐量已被全部使用，餘量不足以讀取下一條數據。同時 GetRange 請求的返回結果中還包含下一條未讀數據的主鍵，應用程序可以使用該返回值作為下一次 GetRange 操作的起始點繼續讀取。如果下一條未讀數據的主鍵為空，表示讀取區間內的數據全部返回。

表格存儲計算讀取區間起始點到下一條未讀數據的起始點的所有行主鍵數據大小與實際讀取的屬性列數據大小之和。將數據大小之和除以 4 KB 向上取整計算消耗的讀服務能力單元。例如，若讀取範圍中包含 10 行，每行主鍵數據大小與實際讀取到的屬性列數據之和占用數據大小為 330 Byte，則消耗的讀服務能力單元為 1（數據總和 3.3 KB，除以 4 KB 向上取整為1）。

示例說明：

下麵舉例說明 GetRange 操作的行為。假設表的內容如下，PK1、PK2 是表的主鍵列，類型分別為 String 和 Integer；A、B 是表的屬性列。

示例 1，讀取某一範圍內的數據：

//請求
table_name: "table_name"
direction: FORWARD
inclusive_start_primary_key: ("PK1", STRING, "A"), ("PK2", INTEGER, 2)
exclusive_end_primary_key: ("PK1", STRING, "C"), ("PK2", INTEGER, 1)
//響應
cosumed_read_capacity_unit: 1
rows: {
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 2)
        attribute_columns:("Attr1", STRING, "Hell"), ("Attr2", STRING, "Bell")
      },
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 5)
        attribute_columns:("Attr1", STRING, "Hello")
      },
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 6)
        attribute_columns:("Attr2", STRING, "Blood")
      }，
      {
        primary_key_columns:("PK1", STRING, "B"), ("PK2", INTEGER, 10)
        attribute_columns:("Attr1", STRING, "Apple")
      }
    }

//請求
table_name: "table_name"
direction: FORWARD
inclusive_start_primary_key: ("PK1", INF_MIN)
exclusive_end_primary_key: ("PK1", INF_MAX)
//響應
cosumed_read_capacity_unit: 1
rows: {
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 2)
        attribute_columns:("Attr1", STRING, "Hell"), ("Attr2", STRING, "Bell")
      },
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 5)
        attribute_columns:("Attr1", STRING, "Hello")
      },
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 6)
        attribute_columns:("Attr2", STRING, "Blood")
      }，
      {
        primary_key_columns:("PK1", STRING, "B"), ("PK2", INTEGER, 10)
        attribute_columns:("Attr1", STRING, "Apple")
      }
      {
        primary_key_columns:("PK1", STRING, "C"), ("PK2", INTEGER, 1)
      }
      {
        primary_key_columns:("PK1", STRING, "C"), ("PK2", INTEGER, 9)
        attribute_columns:("Attr1", STRING, "Alpha")
      }
    }

//請求
table_name: "table_name"
direction: FORWARD
inclusive_start_primary_key: ("PK1", STRING, "A"), ("PK2", INF_MIN)
exclusive_end_primary_key: ("PK1", STRING, "A"), ("PK2", INF_MAX)
//響應
cosumed_read_capacity_unit: 1
rows: {
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 2)
        attribute_columns:("Attr1", STRING, "Hell"), ("Attr2", STRING, "Bell")
      },
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 5)
        attribute_columns:("Attr1", STRING, "Hello")
      },
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 6)
        attribute_columns:("Attr2", STRING, "Blood")
      }
    }

//請求
table_name: "table_name"
direction: BACKWARD
inclusive_start_primary_key: ("PK1", STRING, "C"), ("PK2", INTEGER, 1)
exclusive_end_primary_key: ("PK1", STRING, "A"), ("PK2", INTEGER, 5)
//響應
cosumed_read_capacity_unit: 1
rows: {
      {
        primary_key_columns:("PK1", STRING, "C"), ("PK2", INTEGER, 1)
      },
      {
        primary_key_columns:("PK1", STRING, "B"), ("PK2", INTEGER, 10)
        attribute_columns:("Attr1", STRING, "Apple")
      },
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 6)
        attribute_columns:("Attr2", STRING, "Blood")
      }
    }

//請求
table_name: "table_name"
direction: FORWARD
inclusive_start_primary_key: ("PK1", STRING, "C"), ("PK2", INF_MIN)
exclusive_end_primary_key: ("PK1", STRING, "C"), ("PK2", INF_MAX)
columns_to_get: "Attr1"
//響應
cosumed_read_capacity_unit: 1
rows: {
      {
        attribute_columns: {"Attr1", STRING, "Alpha"}
      }
    }

//請求
table_name: "table_name"
direction: FORWARD
inclusive_start_primary_key: ("PK1", STRING, "C"), ("PK2", INF_MIN)
exclusive_end_primary_key: ("PK1", STRING, "C"), ("PK2", INF_MAX)
columns_to_get: "Attr1", "PK1"
//響應
cosumed_read_capacity_unit: 1
rows: {
      {
        primary_key_columns:("PK1", STRING, "C")
      }
      {
        primary_key_columns:("PK1", STRING, "C")
        attribute_columns:("Attr1", STRING, "Alpha")
      }
    }

//請求 1
table_name: "table_name"
direction: FORWARD
inclusive_start_primary_key: ("PK1", STRING, "A"), ("PK2", INF_MIN)
exclusive_end_primary_key: ("PK1", STRING, "A"), ("PK2", INF_MAX)
limit: 2
//響應 1
cosumed_read_capacity_unit: 1
rows: {
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 2)
        attribute_columns:("Attr1", STRING, "Hell"), ("Attr2", STRING, "Bell")
      },
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 5)
        attribute_columns:("Attr1", STRING, "Hello")
      }
    }
next_start_primary_key:("PK1", STRING, "A"), ("PK2", INTEGER, 6)
//請求 2
table_name: "table_name"
direction: FORWARD
inclusive_start_primary_key: ("PK1", STRING, "A"), ("PK2", INTEGER, 6)
exclusive_end_primary_key: ("PK1", STRING, "A"), ("PK2", INF_MAX)
limit: 2
//響應 2
cosumed_read_capacity_unit: 1
rows: {
      {
        primary_key_columns:("PK1", STRING, "A"), ("PK2", INTEGER, 6)
        attribute_columns:("Attr2", STRING, "Blood")
      }
    }

//請求
table_name: "table2_name"
direction: FORWARD
inclusive_start_primary_key: ("PK1", INTEGER, 1)
exclusive_end_primary_key: ("PK1", INTEGER, 4)
columns_to_get: "PK1", "Attr1"
//響應
cosumed_read_capacity_unit: 1
rows: {
      {
        primary_key_columns:("PK1", INTEGER, 1)
      },
      {
        primary_key_columns:("PK1", INTEGER, 2),
        attribute_columns:("Attr1", INTEGER, 8)
      },
      {
        primary_key_columns:("PK1", INTEGER, 3),
        attribute_columns:("Attr1", STRING, String(1000Byte))
      },
    }