Tablestore提供了GetRow介面用於讀取單行資料以及BatchGetRow、GetRange等介面用於讀取多行資料。
前提條件
- 已初始化Client,詳情請參見初始化。
- 已建立資料表並寫入資料。
讀取單行資料
調用GetRow介面讀取一行資料。
- 如果該行存在,則返回該行的各主鍵列以及屬性列。
- 如果該行不存在,則返回中不包含行,並且不會報錯。
介面
/// <summary>
/// 根據給定的主鍵讀取單行資料。
/// </summary>
/// <param name="request">查詢資料的請求</param>
/// <returns>GetRow的響應</returns>
public GetRowResponse GetRow(GetRowRequest request);
/// <summary>
/// GetRow的非同步形式。
/// </summary>
public Task<GetRowResponse> GetRowAsync(GetRowRequest request);
參數
參數 | 說明 |
---|---|
tableName | 資料表名稱。 |
primaryKey | 行的主鍵。 说明 設定的主鍵個數和類型必須和資料表的主鍵個數和類型一致。 |
columnsToGet | 讀取的列集合,列名可以是主鍵列或屬性列。 如果不設定返回的列名,則返回整行資料。 说明
|
maxVersions | 最多讀取的版本數。 说明 maxVersions與timeRange必須至少設定一個。
|
timeRange | 讀取版本號碼範圍或特定版本號碼的資料。更多資訊,請參見TimeRange。 说明 maxVersions與timeRange必須至少設定一個。
SpecificTime和 時間戳記的單位為毫秒,最小值為0,最大值為Int64.MaxValue。 |
filter | 使用過濾器,在服務端對讀取結果再進行一次過濾,只返回符合過濾器中條件的資料行。更多資訊,請參見過濾器。 说明 當columnsToGet和filter同時使用時,執行順序是先擷取columnsToGet指定的列,再在返回的列中進行條件過濾。 |
樣本
- 樣本1
讀取一行資料。
//定義行的主鍵,必須與建立表時的TableMeta中定義的一致。 PrimaryKey primaryKey = new PrimaryKey(); primaryKey.Add("pk0", new ColumnValue(0)); primaryKey.Add("pk1", new ColumnValue("abc")); try { //構造查詢請求對象,此處未指定讀取的列,預設讀取整行資料。 var request = new GetRowRequest(TableName, primaryKey); //調用GetRow介面查詢資料。 var response = otsClient.GetRow(request); //輸出此行的資料,此處省略,詳見範例程式碼的GitHub連結。 //如果沒有拋出異常,則說明執行成功。 Console.WriteLine("Get row succeeded."); } catch (Exception ex) { //如果拋出異常,則說明執行失敗,處理異常。 Console.WriteLine("Update table failed, exception:{0}", ex.Message); }
詳細代碼請參見GetRow@GitHub。
- 樣本2
使用過濾器讀取一行資料。
如下樣本為查詢資料後,只返回col0和col1的資料,同時在col0列和col1列進行過濾,過濾條件是col0等於5或者col1不等於ff。
//定義行的主鍵,必須與建立表時的TableMeta中定義的一致。 PrimaryKey primaryKey = new PrimaryKey(); primaryKey.Add("pk0", new ColumnValue(0)); primaryKey.Add("pk1", new ColumnValue("abc")); var rowQueryCriteria = new SingleRowQueryCriteria("SampleTable"); rowQueryCriteria.RowPrimaryKey = primaryKey; //條件1為col0列的值等於5。 var filter1 = new RelationalCondition("col0", RelationalCondition.CompareOperator.EQUAL, new ColumnValue(5)); //條件2為col1列的值不等於ff。 var filter2 = new RelationalCondition("col1", RelationalCondition.CompareOperator.NOT_EQUAL, new ColumnValue("ff")); //構造組合條件,包括條件1和條件2,關係是OR。 var filter = new CompositeCondition(CompositeCondition.LogicOperator.OR); filter.AddCondition(filter1); filter.AddCondition(filter2); rowQueryCriteria.Filter = filter; //設定要查詢和返回的行,查詢和過濾的順序是先在行的[col0,col1]列上查詢,然後再按條件過濾。 rowQueryCriteria.AddColumnsToGet("col0"); rowQueryCriteria.AddColumnsToGet("col1"); //構造GetRowRequest。 var request = new GetRowRequest(rowQueryCriteria); try { //查詢。 var response = otsClient.GetRow(request); //輸出資料或者相關邏輯操作,此處省略。 //如果沒有拋出異常,則說明執行成功。 Console.WriteLine("Get row with filter succeeded."); } catch (Exception ex) { //如果拋出異常,則說明執行失敗,處理異常。 Console.WriteLine("Get row with filter failed, exception:{0}", ex.Message); }
詳細代碼請參見GetRowWithFilter@GitHub。
批量讀取資料
調用BatchGetRow介面一次請求讀取多行資料,也支援一次對多張表進行讀取。BatchGetRow由多個GetRow子操作組成。構造子操作的過程與使用GetRow介面時相同,也支援使用過濾器。
批量讀取的所有行採用相同的參數條件,例如ColumnsToGet=[colA]
,則要讀取的所有行都唯讀取colA列。
BatchGetRow的各個子操作獨立執行,Tablestore會分別返回各個子操作的執行結果。
注意事項
由於批量讀取可能存在部分行失敗的情況,失敗行的錯誤資訊在返回的BatchGetRowResponse中,但並不拋出異常。因此調用BatchGetRow介面時,需要檢查傳回值,判斷每行的狀態是否成功。
介面
/// <summary>
/// <para>批量讀取一個或多個表中的若干行資料。</para>
/// <para>BatchGetRow操作可視為多個GetRow操作的集合,各個操作獨立執行,獨立返回結果,獨立計算服務能力單元。</para>
/// 與執行大量的GetRow操作相比,使用BatchGetRow操作可以有效減少請求的回應時間,提高資料的讀取速率。
/// </summary>
/// <param name="request">請求執行個體</param>
/// <returns>響應執行個體</returns>
public BatchGetRowResponse BatchGetRow(BatchGetRowRequest request);
/// <summary>
/// BatchGetRow的非同步形式。
/// </summary>
public Task<BatchGetRowResponse> BatchGetRowAsync(BatchGetRowRequest request);
樣本
批量一次讀取10行。
//構造批量讀的請求對象,設定10行資料的主鍵。
List<PrimaryKey> primaryKeys = new List<PrimaryKey>();
for (int i = 0; i < 10; i++)
{
PrimaryKey primaryKey = new PrimaryKey();
primaryKey.Add("pk0", new ColumnValue(i));
primaryKey.Add("pk1", new ColumnValue("abc"));
primaryKeys.Add(primaryKey);
}
try
{
BatchGetRowRequest request = new BatchGetRowRequest();
request.Add(TableName, primaryKeys);
//調用BatchGetRow介面查詢10行資料。
var response = otsClient.BatchGetRow(request);
var tableRows = response.RowDataGroupByTable;
var rows = tableRows[TableName];
//輸出rows中的資料,此處省略,詳見範例程式碼的GitHub連結。
//大量操作可能部分成功部分失敗,需要檢查每行的狀態是否成功,詳見範例程式碼的GitHub連結。
}
catch (Exception ex)
{
//如果拋出異常,則說明執行失敗,處理異常。
Console.WriteLine("Batch get row failed, exception:{0}", ex.Message);
}
詳細代碼請參見BatchGetRow@GitHub。
範圍讀取資料
調用GetRange介面讀取一個範圍內的資料。
GetRange操作支援按照確定範圍進行正序讀取和逆序讀取,可以設定要讀取的行數。如果範圍較大,已掃描的行數或者資料量超過一定限制,會停止掃描,並返回已擷取的行和下一個主鍵資訊。您可以根據返回的下一個主鍵資訊,繼續發起請求,擷取範圍內剩餘的行。
注意事項
GetRange操作遵循最左匹配原則,讀取資料時,依次比較第一主鍵列到第四主鍵列。例如資料表的主鍵包括PK1、PK2、PK3三個主鍵列,讀取資料時,優先比較PK1是否在開始主鍵與結束主鍵的範圍內,如果PK1在設定的主鍵範圍內,則不會再比較其他的主鍵,返回在PK1主鍵範圍內的資料;如果PK1不在設定的主鍵範圍內,則繼續比較PK2是否在開始主鍵與結束主鍵的範圍內,以此類推。
- 掃描的行資料大小之和達到4 MB。
- 掃描的行數等於5000。
- 返回的行數等於最大返回行數。
- 當前剩餘的預留讀輸送量已全部使用,餘量不足以讀取下一條資料。
當使用GetRange掃描的資料量較大時,Tablestore每次請求僅會掃描一次(行數大於5000或者大小大於4 MB停止掃描),超過限制的資料不會繼續返回,需要通過翻頁繼續擷取後面的資料。
介面
/// <summary>
/// 根據範圍條件擷取多行資料。
/// </summary>
/// <param name="request">請求執行個體</param>
/// <returns>響應執行個體</returns>
public GetRangeResponse GetRange(GetRangeRequest request);
/// <summary>
/// GetRange的非同步版本。
/// </summary>
/// <param name="request"></param>
/// <returns></returns>
public Task<GetRangeResponse> GetRangeAsync(GetRangeRequest request);
參數
參數 | 說明 |
---|---|
tableName | 資料表名稱。 |
direction | 讀取方向。
例如同一表中有兩個主鍵A和B,A<B。如正序讀取[A, B),則按從A至B的順序返回主鍵大於等於A、小於B的行;逆序讀取[B, A),則按從B至A的順序返回大於A、小於等於B的資料。 |
inclusiveStartPrimaryKey | 本次範圍讀的起始主鍵和結束主鍵,起始主鍵和結束主鍵需要是有效主鍵或者是由INF_MIN和INF_MAX類型組成的虛擬點,虛擬點的列數必須與主鍵相同。 其中INF_MIN表示無限小,任何類型的值都比它大;INF_MAX表示無限大,任何類型的值都比它小。
資料表中的行按主鍵從小到大排序,讀取範圍是一個左閉右開的區間,正序讀取時,返回的是大於等於起始主鍵且小於結束主鍵的所有的行。 |
exclusiveEndPrimaryKey | |
limit | 資料的最大返回行數,此值必須大於 0。 Tablestore按照正序或者逆序返回指定的最大返回行數後即結束該操作的執行,即使該區間內仍有未返回的資料。此時可以通過返回的斷點記錄本次讀取到的位置,用於下一次讀取。 |
columnsToGet | 讀取的列集合,列名可以是主鍵列或屬性列。 如果不設定返回的列名,則返回整行資料。 说明
|
maxVersions | 最多讀取的版本數。 说明 maxVersions與timeRange必須至少設定一個。
|
timeRange | 讀取版本號碼範圍或特定版本號碼的資料。更多資訊,請參見TimeRange。 说明 maxVersions與timeRange必須至少設定一個。
SpecificTime和[StartTime, EndTime)中只需要設定一個。 時間戳記的單位為毫秒,最小值為0,最大值為Int64.MaxValue。 |
filter | 使用過濾器,在服務端對讀取結果再進行一次過濾,只返回符合過濾器中條件的資料行。更多資訊,請參見過濾器。 说明 當columnsToGet和filter同時使用時,執行順序是先擷取columnsToGet指定的列,再在返回的列中進行條件過濾。 |
nextStartPrimaryKey | 根據返回結果中的nextStartPrimaryKey判斷資料是否全部讀取。
|
樣本
按照範圍讀取資料。
//讀取(0, INF_MIN)到(100, INF_MAX)範圍內的所有行。
var inclusiveStartPrimaryKey = new PrimaryKey();
inclusiveStartPrimaryKey.Add("pk0", new ColumnValue(0));
inclusiveStartPrimaryKey.Add("pk1", ColumnValue.INF_MIN);
var exclusiveEndPrimaryKey = new PrimaryKey();
exclusiveEndPrimaryKey.Add("pk0", new ColumnValue(100));
exclusiveEndPrimaryKey.Add("pk1", ColumnValue.INF_MAX);
try
{
//構造範圍讀的請求對象。
var request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
inclusiveStartPrimaryKey, exclusiveEndPrimaryKey);
var response = otsClient.GetRange(request);
//如果一次沒有返回所有資料,則需要繼續查詢。
var rows = response.RowDataList;
var nextStartPrimaryKey = response.NextPrimaryKey;
while (nextStartPrimaryKey != null)
{
request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
nextStartPrimaryKey, exclusiveEndPrimaryKey);
response = otsClient.GetRange(request);
nextStartPrimaryKey = response.NextPrimaryKey;
foreach (RowDataFromGetRange row in response.RowDataList)
{
rows.Add(row);
}
}
//輸出rows中的資料,此處省略,詳見範例程式碼的GitHub連結。
//如果沒有拋出異常,則說明執行成功。
Console.WriteLine("Get range succeeded");
}
catch (Exception ex)
{
//如果拋出異常,則說明執行失敗,處理異常。
Console.WriteLine("Get range failed, exception:{0}", ex.Message);
}
詳細代碼請參見GetRange@GitHub。
迭代讀取資料
調用GetRangeIterator介面迭代讀取資料。
介面
/// <summary>
/// 根據範圍條件擷取多行資料,返回用來迭代每一行資料的迭代器。
/// </summary>
/// <param name="request"><see cref="GetIteratorRequest"/></param>
/// <returns>返回<see cref="RowDataFromGetRange"/>的迭代器。</returns>
public IEnumerable<RowDataFromGetRange> GetRangeIterator(GetIteratorRequest request);
樣本
迭代讀取(0, "a")到(1000, "xyz")範圍內的所有行。
//讀取(0, "a")到(1000, "xyz")範圍內的所有行。
PrimaryKey inclusiveStartPrimaryKey = new PrimaryKey();
inclusiveStartPrimaryKey.Add("pk0", new ColumnValue(0));
inclusiveStartPrimaryKey.Add("pk1", new ColumnValue("a"));
PrimaryKey exclusiveEndPrimaryKey = new PrimaryKey();
exclusiveEndPrimaryKey.Add("pk0", new ColumnValue(1000));
exclusiveEndPrimaryKey.Add("pk1", new ColumnValue("xyz"));
//構造一個CapacityUnit,用於記錄迭代過程中消耗的CU值。
var cu = new CapacityUnit(0, 0);
try
{
//構造一個GetIteratorRequest,也支援使用過濾條件。
var request = new GetIteratorRequest(TableName, GetRangeDirection.Forward, inclusiveStartPrimaryKey,
exclusiveEndPrimaryKey, cu);
var iterator = otsClient.GetRangeIterator(request);
//遍曆迭代器,讀取資料。
foreach (var row in iterator)
{
//處理邏輯。
}
Console.WriteLine("Iterate row succeeded");
}
catch (Exception ex)
{
Console.WriteLine("Iterate row failed, exception:{0}", ex.Message);
}
詳細代碼請參見GetRangeIterator@GitHub。