Tüm Ürünler
Search

Bu Ürün

    Tablestore:GetRange

    Belge Merkezi

    Tablestore:GetRange

    Son Güncelleme:Oct 02, 2026

    Birincil anahtar değerleri belirtilen aralıkta bulunan verileri okur.

    İstek sözdizimi

    message GetRangeRequest {
    required string table_name = 1;
    required Direction direction = 2;
    repeated string columns_to_get = 3; // If you do not specify this parameter, all columns are read. 
    optional TimeRange time_range = 4;
    optional int32 max_versions = 5;
    optional int32 limit = 6;
    required bytes inclusive_start_primary_key = 7; // The start primary key information is encoded as binary data in the PlainBuffer format. 
    required bytes exclusive_end_primary_key = 8; // The end primary key information is encoded as binary data in the PlainBuffer format. 
    optional bytes filter = 10;
    optional string start_column = 11;
    optional string end_column = 12;
}

    Parametre

    Tür

    Zorunlu

    Açıklama

    table_name

    string

    Evet

    Tablonun adı.

    direction

    Direction

    Evet

    Yanıttaki satırların sıralanma düzeni.

    • Bu parametreyi FORWARD olarak ayarlarsanız inclusive_start_primary_key parametresinin değeri exclusive_end_primary_key parametresinin değerinden küçük olmalıdır ve yanıtta döndürülen satırlar birincil anahtar değerlerine göre artan düzende sıralanır.

    • Bu parametreyi BACKWARD olarak ayarlarsanız inclusive_start_primary_key parametresinin değeri exclusive_end_primary_key parametresinin değerinden büyük olmalıdır ve yanıtta döndürülen satırlar birincil anahtar değerlerine göre azalan düzende sıralanır.

    columns_to_get

    repeated string

    Hayır

    Döndürmek istediğiniz sütunların adları. Bu parametrenin değeri en fazla 128 dize içerebilir.

    • Bu parametreyi belirtmezseniz sorgu koşullarını karşılayan satırların tüm sütunları döndürülür.

    • Bir satırın tüm sütunları sorgu koşullarını karşılamıyorsa satır döndürülmez ve dönüş değeri null olur. Bir satır sorgu koşullarını karşılayan sütunların yalnızca bazısını içeriyorsa satır döndürülür ancak yanıtta yalnızca koşulları karşılayan sütunlar yer alır.

      Yinelenen sütun adları varsa yanıtta sütun yalnızca bir kez yer alır.

    time_range

    TimeRange

    Hayır. max_versions ve time_range parametrelerinden yalnızca biri zorunludur.

    Okumak istediğiniz verilerin zaman damgası aralığı. Geçerli değerler: 0 ile INT64.MAX. Birim: milisaniye.

    • Belirli bir zaman damgası aralığındaki verileri sorgulamak için start_time ve end_time değerlerini belirtin. time_range değeri sol kapalı, sağ açık bir aralıktır. Örnek: [start_time, end_time).

      Bu parametreyi [100, 200) olarak ayarlarsanız döndürülen sütunlardaki verilerin zaman damgası [100, 200) aralığında olmalıdır.

    • Belirli bir zaman damgasındaki verileri sorgulamak için specific_time değerini belirtin.

    max_versions

    int32

    Hayır. max_versions ve time_range parametrelerinden yalnızca biri zorunludur.

    Döndürmek istediğiniz veri sürümünün maksimum sayısı.

    Örneğin max_versions değeri 2 ise her sütun için en fazla iki veri sürümü döndürülür.

    limit

    int32

    Hayır

    Döndürmek istediğiniz satır sayısının üst sınırı. Bu parametrenin değeri 0'dan büyük olmalıdır.

    Sorgu koşullarını karşılayan satır sayısı bu parametrenin değerini aşarsa yanıt, okuma işleminin bittiği konumu kaydeden bir kesme noktası içerir. Sonraki okuma işlemi bu konumdan başlar.

    Tablestore bu parametreyi belirtip belirtmediğinize bakmaksızın en fazla 5.000 satır veri döndürür. Döndürülen satırların toplam boyutu 4 MB'yi geçemez.

    inclusive_start_primary_key

    bytes

    Evet

    Okuma işleminin başladığı birincil anahtar bilgisi. Başlangıç birincil anahtar bilgisi PlainBuffer biçiminde kodlanır. Daha fazla bilgi için bkz. PlainBuffer.

    Bir satır başlangıç birincil anahtar sütununu içeriyorsa satır yanıta dahil edilir.

    exclusive_end_primary_key

    bytes

    Evet

    Okuma işleminin sona erdiği birincil anahtar bilgisi. Bitiş birincil anahtar bilgisi PlainBuffer biçiminde kodlanır. Daha fazla bilgi için bkz. PlainBuffer.

    Bir satır bitiş birincil anahtar sütununu içeriyorsa satır yanıttan hariç tutulur.

    GetRange işlemi için inclusive_start_primary_key ve exclusive_end_primary_key değerlerindeki birincil anahtar sütunları yalnızca bu işleme özel olan INF_MIN ve INF_MAX türlerinden biri olabilir. INF_MIN sonsuz küçük bir değeri ifade eder. Bir birincil anahtar sütununun türü INF_MIN ise sütunun değerleri diğer sütunların değerlerinden küçüktür. INF_MAX sonsuz büyük bir değeri ifade eder. Bir birincil anahtar sütununun türü INF_MAX ise sütunun değerleri diğer sütunların değerlerinden büyüktür.

    filter

    bytes

    Hayır

    Filtre koşulu ifadeleri. Filtre koşulu ifadeleri Protobuf kullanılarak ikili veri olarak serileştirilir. Daha fazla bilgi için bkz. Filter.

    start_column

    string

    Hayır

    Bir satırda okuma işleminin başladığı sütun. Bu parametre geniş sütun okuma için kullanılır. Yanıt belirtilen başlangıç sütununu içerir. Sütunlar adlarına göre alfabetik olarak sıralanır.

    Bir tabloda a, b ve c Sütunları varsa ve start_column değeri b ise okuma işlemi b Sütunundan başlar ve b ile c Sütunları döndürülür.

    end_column

    string

    Hayır

    Bir satırda okuma işleminin sona erdiği sütun. Bu parametre geniş sütun okuma için kullanılır. Yanıt belirtilen bitiş sütununu içermez. Sütunlar adlarına göre alfabetik olarak sıralanır.

    Bir tabloda a, b ve c Sütunları varsa ve end_column değeri b ise okuma işlemi b Sütununda sona erer ve yalnızca a Sütunu döndürülür.

    Yanıt sözdizimi

    message GetRangeResponse {
    required ConsumedCapacity consumed = 1;
    required bytes rows = 2; 
    optional bytes next_start_primary_key = 3; 
}

    Parametre

    Tür

    Açıklama

    consumed

    ConsumedCapacity

    İşlem tarafından tüketilen kapasite birimi (CU) sayısı. Daha fazla bilgi için bkz. CU tüketimi.

    rows

    bytes

    İşlem tarafından döndürülen satırlar. Satırlar PlainBuffer biçiminde kodlanır. Daha fazla bilgi için bkz. PlainBuffer.

    • İstekteki direction değeri FORWARD olarak ayarlanırsa yanıtta döndürülen satırlar birincil anahtar değerlerine göre artan düzende sıralanır.

    • İstekteki direction değeri BACKWARD olarak ayarlanırsa yanıtta döndürülen satırlar birincil anahtar değerlerine göre azalan düzende sıralanır.

    Yanıttaki her satırın birincil anahtar ve nitelik sütunları yalnızca istekte columns_to_get için belirttiğiniz sütunları içerir. Yanıttaki sütunların sırası istekte columns_to_get için belirttiğiniz sütunların sırasından farklı olabilir. Yanıttaki birincil anahtar sütunlarının sırası tablo oluşturulurken belirtilen birincil anahtar sütunlarının sırasından farklı olabilir.

    İstekteki columns_to_get değeri bir birincil anahtar sütunu içermiyorsa satırların birincil anahtar değerleri sorgu aralığında olsa bile columns_to_get içinde belirtilen nitelik sütunlarını içermeyen satırlar yanıttan hariç tutulur.

    next_start_primary_key

    bytes

    Okuma işleminin sona erdiği konumu kaydeden kesme noktası. Kesme noktası PlainBuffer biçiminde kodlanır. Daha fazla bilgi için bkz. PlainBuffer.

    • Dönüş değeri boşsa GetRange işlemi sorgu koşullarını karşılayan tüm verileri döndürür.

    • Dönüş değeri boş değilse GetRange işlemi yalnızca [inclusive_start_primary_key, next_start_primary_key) aralığındaki verileri döndürür.

      Kalan verileri almak için inclusive_start_primary_key değerini next_start_primary_key değerine ayarlayın ve orijinal istekteki exclusive_end_primary_key değerini koruyarak GetRange işlemini yeniden çağırın.

    Not

    GetRange işlemi her istekte en fazla 5.000 satır döndürebilir. Satırlardaki verilerin toplam boyutu 4 MB'yi aşamaz.

    İstekte limit belirtmeseniz bile bir GetRange isteğine verilen yanıt next_start_primary_key değeri içerebilir. GetRange işlemini çağırırken yanıtın next_start_primary_key içerip içermediğini kontrol etmeniz gerekir.

    Tablestore SDK'larını kullanma

    Birincil anahtar değerleri belirtilen aralıkta bulunan verileri okumak için aşağıdaki Tablestore SDK'larını kullanabilirsiniz:

    CU tüketimi

    • GetRange işlemi için tüketilen okuma CU sayısı aşağıdaki formülün hesaplama sonucundan yukarı yuvarlanarak bulunur: Tüketilen okuma CU sayısı = (Sorgu koşullarını karşılayan satırların tüm birincil anahtar sütunlarında yer alan verilerin boyutu + Okunan nitelik sütunlarında yer alan verilerin boyutu) / 4 KB. Veri boyutunun nasıl hesaplanacağı hakkında daha fazla bilgi için bkz. Veri depolama.

    • İstek zaman aşımına uğrar ve sonuçlar belirsiz olursa CU'lar tüketilebilir veya tüketilmeyebilir.

    • Dahili hata oluştuğunu belirten bir HTTP durum kodu 5xx döndürülürse işlem CU tüketmez. Diğer hatalar döndürülürse bir okuma CU'su tüketilir.