Tous les produits
Search

Ce produit

    Tablestore:GetRange

    Centre de documentation

    Tablestore:GetRange

    Dernière mise à jour :Aug 18, 2026

    Lit les données dont les valeurs de clé primaire se situent dans la plage spécifiée.

    Syntaxe de la requête

    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;
}

    Paramètre

    Type

    Obligatoire

    Description

    table_name

    string

    Oui

    Nom de la table.

    direction

    Direction

    Oui

    Ordre de tri des lignes dans la réponse.

    • Si vous définissez ce paramètre sur FORWARD, la valeur du paramètre inclusive_start_primary_key doit être inférieure à celle du paramètre exclusive_end_primary_key, et les lignes de la réponse sont triées par ordre croissant des valeurs de clé primaire.

    • Si vous définissez ce paramètre sur BACKWARD, la valeur du paramètre inclusive_start_primary_key doit être supérieure à celle du paramètre exclusive_end_primary_key, et les lignes de la réponse sont triées par ordre décroissant des valeurs de clé primaire.

    columns_to_get

    repeated string

    Non

    Noms des colonnes à renvoyer. Ce paramètre peut contenir jusqu'à 128 chaînes.

    • Si vous ne spécifiez pas ce paramètre, toutes les colonnes des lignes répondant aux conditions de la requête sont renvoyées.

    • Si aucune colonne d'une ligne ne satisfait aux conditions de la requête, la ligne n'est pas renvoyée et la valeur de retour est null. Si une ligne contient certaines des colonnes satisfaisant aux conditions de la requête, la ligne est renvoyée et seules ces colonnes figurent dans la réponse.

      En cas de noms de colonnes en double, la réponse n'inclut la colonne qu'une seule fois.

    time_range

    TimeRange

    Non. Seul l'un des paramètres max_versions ou time_range est obligatoire.

    Plage d'horodatage des données à lire. Valeurs valides : 0 à INT64.MAX. Unité : milliseconde.

    • Pour interroger les données comprises dans une plage d'horodatage, spécifiez start_time et end_time. La valeur de time_range correspond à un intervalle fermé à gauche et ouvert à droite. Exemple : [start_time, end_time).

      Si vous définissez ce paramètre sur [100, 200), l'horodatage des données dans les colonnes renvoyées doit se situer dans la plage [100, 200).

    • Pour interroger les données à un horodatage précis, spécifiez specific_time.

    max_versions

    int32

    Non. Seul l'un des paramètres max_versions ou time_range est obligatoire.

    Nombre maximal de versions de données à renvoyer.

    Par exemple, si la valeur de max_versions est 2, un maximum de deux versions de données est renvoyé pour chaque colonne.

    limit

    int32

    Non

    Nombre maximal de lignes à renvoyer. La valeur de ce paramètre doit être supérieure à 0.

    Si le nombre de lignes répondant aux conditions de la requête dépasse la valeur de ce paramètre, la réponse contient un point d'arrêt enregistrant la position à laquelle l'opération de lecture s'arrête. L'opération de lecture suivante commence à partir de cette position.

    Tablestore renvoie jusqu'à 5 000 lignes de données, que vous ayez ou non spécifié ce paramètre. La taille totale des lignes renvoyées ne peut pas dépasser 4 Mo.

    inclusive_start_primary_key

    bytes

    Oui

    Informations de clé primaire à partir desquelles l'opération de lecture commence. Les informations de clé primaire de début sont encodées au format PlainBuffer. Pour plus d'informations, consultez PlainBuffer.

    Si une ligne contient la colonne de clé primaire de début, la ligne est incluse dans la réponse.

    exclusive_end_primary_key

    bytes

    Oui

    Informations de clé primaire auxquelles l'opération de lecture s'arrête. Les informations de clé primaire de fin sont encodées au format PlainBuffer. Pour plus d'informations, consultez PlainBuffer.

    Si une ligne contient la colonne de clé primaire de fin, la ligne est exclue de la réponse.

    Pour l'opération GetRange, les colonnes de clé primaire dans les valeurs de inclusive_start_primary_key et exclusive_end_primary_key peuvent être de l'un des types suivants dédiés à cette opération : INF_MIN et INF_MAX. INF_MIN indique une valeur infiniment petite. Si le type d'une colonne de clé primaire est INF_MIN, les valeurs de la colonne sont inférieures aux valeurs des autres colonnes. INF_MAX indique une valeur infiniment grande. Si le type d'une colonne de clé primaire est INF_MAX, les valeurs de la colonne sont supérieures aux valeurs des autres colonnes.

    filter

    bytes

    Non

    Expressions des conditions de filtrage. Les expressions des conditions de filtrage sont sérialisées sous forme de données binaires à l'aide de Protobuf. Pour plus d'informations, consultez Filter.

    start_column

    string

    Non

    Colonne à partir de laquelle l'opération de lecture commence dans une ligne. Ce paramètre est utilisé pour la lecture de colonnes larges. La réponse inclut la colonne de début spécifiée. Les colonnes sont triées par ordre alphabétique de leurs noms.

    Si une table contient les colonnes a, b et c, et que la valeur de start_column est b, l'opération de lecture commence à partir de la colonne b, et les colonnes b et c sont renvoyées.

    end_column

    string

    Non

    Colonne à laquelle l'opération de lecture s'arrête dans une ligne. Ce paramètre est utilisé pour la lecture de colonnes larges. La réponse exclut la colonne de fin spécifiée. Les colonnes sont triées par ordre alphabétique de leurs noms.

    Si une table contient les colonnes a, b et c, et que la valeur de end_column est b, l'opération de lecture s'arrête à la colonne b, et seule la colonne a est renvoyée.

    Syntaxe de la réponse

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

    Paramètre

    Type

    Description

    consumed

    ConsumedCapacity

    Nombre d'unités de capacité (CU) consommées par l'opération. Pour plus d'informations, consultez Consommation de CU.

    rows

    bytes

    Lignes renvoyées par l'opération. Les lignes sont encodées au format PlainBuffer. Pour plus d'informations, consultez PlainBuffer.

    • Si direction dans la requête est défini sur FORWARD, les lignes de la réponse sont triées par ordre croissant des valeurs de clé primaire.

    • Si direction dans la requête est défini sur BACKWARD, les lignes de la réponse sont triées par ordre décroissant des valeurs de clé primaire.

    Les colonnes de clé primaire et les colonnes d'attribut pour chaque ligne de la réponse incluent uniquement les colonnes que vous avez spécifiées pour columns_to_get dans la requête. L'ordre des colonnes dans la réponse peut différer de l'ordre des colonnes que vous avez spécifié pour columns_to_get dans la requête. L'ordre des colonnes de clé primaire dans la réponse peut différer de l'ordre des colonnes de clé primaire spécifié lors de la création de la table.

    Si la valeur de columns_to_get dans la requête ne contient pas de colonne de clé primaire, les lignes qui ne contiennent pas de colonnes d'attribut spécifiées dans columns_to_get sont exclues de la réponse, même si les valeurs de clé primaire des lignes se situent dans la plage de la requête.

    next_start_primary_key

    bytes

    Point d'arrêt enregistrant la position à laquelle l'opération de lecture s'arrête. Le point d'arrêt est encodé au format PlainBuffer. Pour plus d'informations, consultez PlainBuffer.

    • Si la valeur de retour est vide, l'opération GetRange renvoie toutes les données répondant aux conditions de la requête.

    • Si la valeur de retour n'est pas vide, l'opération GetRange renvoie uniquement les données comprises dans la plage [inclusive_start_primary_key, next_start_primary_key).

      Pour obtenir les données restantes, définissez inclusive_start_primary_key sur la valeur de next_start_primary_key et conservez la valeur de exclusive_end_primary_key de la requête d'origine pour appeler à nouveau l'opération GetRange.

    Remarque

    L'opération GetRange peut renvoyer jusqu'à 5 000 lignes par requête. La taille totale des données dans les lignes ne peut pas dépasser 4 Mo.

    La réponse à une requête GetRange peut contenir une valeur next_start_primary_key même si vous ne spécifiez pas de limite dans la requête. Lorsque vous appelez l'opération GetRange, vous devez vérifier si la réponse contient next_start_primary_key.

    Utiliser les SDK Tablestore

    Utilisez les SDK Tablestore suivants pour lire les données dont les valeurs de clé primaire se situent dans la plage spécifiée :

    Consommation de CU

    • Le nombre de CU de lecture consommées pour l'opération GetRange est arrondi à l'entier supérieur à partir du résultat du calcul de la formule suivante : Nombre de CU de lecture consommées = (Taille des données dans toutes les colonnes de clé primaire des lignes répondant aux conditions de la requête + Taille des données dans les colonnes d'attribut lues) / 4 Ko. Pour plus d'informations sur le calcul de la taille des données, consultez Stockage des données.

    • Si la requête expire et que les résultats sont indéfinis, des CU peuvent ou non être consommées.

    • Si un code d'état HTTP 5xx est renvoyé, indiquant qu'une erreur interne s'est produite, l'opération ne consomme pas de CU. Si d'autres erreurs sont renvoyées, une CU de lecture est consommée.