Lire des données à partir d'un index secondaire - SDK Tablestore pour Java - Tablestore

Prérequis

Installez le SDK Tablestore pour Java et initialisez un client.

Description de la fonctionnalité

Un index secondaire réorganise les colonnes de clé primaire et les colonnes prédéfinies d'une table de données afin de proposer un autre chemin de lecture. Une table d'index est en lecture seule. Elle contient la clé primaire de l'index, les colonnes de clé primaire que Tablestore ajoute automatiquement depuis la table de données, ainsi que les colonnes d'attribut spécifiées lors de la création de l'index. Pour récupérer une colonne d'attribut absente de la table d'index, utilisez la clé primaire de la table de données renvoyée pour interroger cette dernière. Pour plus d'informations, consultez Index secondaires.

Lors de la lecture d'une table d'index, les noms et l'ordre des colonnes de clé primaire doivent correspondre au schéma de clé primaire de cette table. Supposons par exemple qu'une table de données utilise user_id et order_id comme clé primaire, et que category soit ajoutée en tant que colonne d'index. Le tableau suivant compare l'ordre complet de la clé primaire pour les index secondaires globaux et locaux.

Type d'index

Clé primaire de l'index spécifiée lors de la création

Ordre complet de la clé primaire de la table d'index

Index secondaire global

category

category, user_id et order_id. Tablestore ajoute les colonnes de clé primaire de la table de données non spécifiées à la clé primaire de l'index.

Index secondaire local

user_id et category

user_id, category et order_id. La première colonne de la clé primaire de l'index doit être identique à la première colonne de la clé primaire de la table de données.

Important

Lorsqu'un index secondaire global est créé pour inclure des données existantes, la table d'index ne peut pas être lue tant que ces données n'ont pas été construites et synchronisées. Attendez la fin de la synchronisation avant de lire la table d'index.

Appelez getRow pour lire une ligne à l'aide de la clé primaire complète de la table d'index.

public GetRowResponse getRow(GetRowRequest getRowRequest)
        throws TableStoreException, ClientException

Appelez getRange pour lire des données situées dans une plage de clés primaires de la table d'index.

public GetRangeResponse getRange(GetRangeRequest getRangeRequest)
        throws TableStoreException, ClientException

L'exemple suivant lit une ligne de l'index secondaire global example_global_index en utilisant sa clé primaire complète et renvoie uniquement la colonne d'attribut status.

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.fromString("user-1"))
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.fromLong(101L))
        .build();

SingleRowQueryCriteria criteria =
        new SingleRowQueryCriteria("example_global_index", primaryKey);
criteria.addColumnsToGet("status");
criteria.setMaxVersions(1);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println(response.getRow());

Paramètres

Paramètres pour la lecture d'une seule ligne

GetRowRequest contient le paramètre suivant.

Nom

Type

Description

rowQueryCriteria (obligatoire)

SingleRowQueryCriteria

Les conditions de lecture d'une seule ligne.

Conditions de lecture d'une seule ligne

rowQueryCriteria est de type SingleRowQueryCriteria et contient les paramètres suivants.

Nom

Type

Description

tableName (obligatoire)

String

Le nom de la table d'index.

primaryKey (obligatoire)

PrimaryKey

La clé primaire complète de la ligne dans la table d'index. La clé primaire doit contenir les colonnes de clé primaire de l'index spécifiées lors de la création de l'index, ainsi que les colonnes de clé primaire de la table de données ajoutées automatiquement par Tablestore. Les noms et l'ordre des colonnes doivent correspondre au schéma de la table d'index.

columnsToGet (facultatif)

Set<String>

Les noms des colonnes d'attribut à renvoyer. Vous pouvez spécifier jusqu'à 128 colonnes. Si ce paramètre n'est pas spécifié, toutes les colonnes d'attribut de la ligne dans la table d'index sont renvoyées. Une colonne d'attribut absente de la table d'index n'est pas renvoyée et doit être récupérée depuis la table de données.

maxVersions (conditionnellement obligatoire)

int

Le nombre maximal de versions à renvoyer pour chaque colonne d'attribut. La valeur doit être supérieure à 0. Un index secondaire ne conserve que la dernière version. Dans la plupart des cas, définissez ce paramètre sur 1. Spécifiez soit maxVersions, soit timeRange, mais pas les deux.

timeRange (conditionnellement obligatoire)

TimeRange

La plage horaire des versions des colonnes d'attribut, en millisecondes. La plage est fermée à gauche et ouverte à droite. Spécifiez soit timeRange, soit maxVersions, mais pas les deux.

filter (facultatif)

Filter

Un filtre côté serveur. La ligne n'est pas renvoyée si elle ne respecte pas la condition de filtrage.

startColumn (facultatif)

String

Le nom de la première colonne d'attribut à renvoyer selon l'ordre lexicographique. La colonne spécifiée est incluse. Ce paramètre est destiné à la lecture de lignes larges.

endColumn (facultatif)

String

Le nom de la dernière colonne d'attribut selon l'ordre lexicographique. La colonne spécifiée est exclue. Ce paramètre est destiné à la lecture de lignes larges.

Paramètres pour la lecture d'une plage de lignes

GetRangeRequest contient le paramètre suivant.

Nom

Type

Description

rangeRowQueryCriteria (obligatoire)

RangeRowQueryCriteria

Les conditions de lecture d'une plage de lignes.

Conditions de lecture par plage

rangeRowQueryCriteria est de type RangeRowQueryCriteria et contient les paramètres suivants.

Nom

Type

Description

tableName (obligatoire)

String

Le nom de la table d'index.

inclusiveStartPrimaryKey (obligatoire)

PrimaryKey

La clé primaire de début de la plage. Cette clé primaire est incluse dans le résultat et doit contenir toutes les colonnes de clé primaire de la table d'index. Vous pouvez utiliser INF_MIN et INF_MAX pour représenter respectivement les valeurs minimale et maximale d'une colonne de clé primaire.

exclusiveEndPrimaryKey (obligatoire)

PrimaryKey

La clé primaire de fin de la plage. Cette clé primaire est exclue du résultat et doit contenir toutes les colonnes de clé primaire de la table d'index. Vous pouvez utiliser INF_MIN et INF_MAX pour représenter respectivement les valeurs minimale et maximale d'une colonne de clé primaire.

direction (facultatif)

Direction

La direction de lecture. Les valeurs valides sont FORWARD et BACKWARD. La valeur par défaut est FORWARD. Pour une lecture ascendante, la clé primaire de début doit être inférieure à la clé primaire de fin. Pour une lecture descendante, la clé primaire de début doit être supérieure à la clé primaire de fin.

limit (facultatif)

int

Le nombre maximal de lignes à renvoyer en une seule requête. La valeur doit être supérieure à 0. La valeur par défaut est -1, ce qui indique que le client ne limite pas le nombre de lignes renvoyées. Le serveur renvoie au maximum 5 000 lignes et 4 Mo de données dans une seule réponse.

columnsToGet (facultatif)

Set<String>

Les noms des colonnes d'attribut à renvoyer. Vous pouvez spécifier jusqu'à 128 colonnes. Si ce paramètre n'est pas spécifié, toutes les colonnes d'attribut de chaque ligne de la table d'index sont renvoyées. Si aucune des colonnes d'attribut spécifiées n'existe dans une ligne, celle-ci n'est pas renvoyée. Avant d'interroger la table de données, lisez les colonnes qui existent dans la table d'index ou laissez ce paramètre non spécifié.

maxVersions (conditionnellement obligatoire)

int

Le nombre maximal de versions à renvoyer pour chaque colonne d'attribut. La valeur doit être supérieure à 0. Un index secondaire ne conserve que la dernière version. Dans la plupart des cas, définissez ce paramètre sur 1. Spécifiez soit maxVersions, soit timeRange, mais pas les deux.

timeRange (conditionnellement obligatoire)

TimeRange

La plage horaire des versions des colonnes d'attribut, en millisecondes. La plage est fermée à gauche et ouverte à droite. Spécifiez soit timeRange, soit maxVersions, mais pas les deux.

filter (facultatif)

Filter

Un filtre côté serveur. Seules les lignes qui respectent la condition de filtrage sont renvoyées.

startColumn (facultatif)

String

Le nom de la première colonne d'attribut à renvoyer selon l'ordre lexicographique. La colonne spécifiée est incluse. Ce paramètre est destiné à la lecture de lignes larges.

endColumn (facultatif)

String

Le nom de la dernière colonne d'attribut selon l'ordre lexicographique. La colonne spécifiée est exclue. Ce paramètre est destiné à la lecture de lignes larges.

Valeurs de retour

Valeurs de retour pour la lecture d'une seule ligne

GetRowResponse contient les paramètres de réponse suivants.

Nom

Type

Description

row

Row

La ligne renvoyée. Si la ligne n'existe pas, null est renvoyé.

consumedCapacity

ConsumedCapacity

Les unités de capacité consommées par l'opération.

Valeurs de retour pour la lecture d'une plage de lignes

GetRangeResponse contient les paramètres de réponse suivants.

Nom

Type

Description

rows

List<Row>

Les lignes renvoyées par la requête.

nextStartPrimaryKey

PrimaryKey

La clé primaire de début pour la prochaine requête. Si ce paramètre n'est pas null, utilisez-le comme inclusiveStartPrimaryKey dans la requête suivante. Si ce paramètre est null, toutes les lignes de la plage spécifiée ont été lues. Ce paramètre peut être renvoyé lorsqu'une réponse atteint la limite du serveur, même si limit n'est pas spécifié.

consumedCapacity

ConsumedCapacity

Les unités de capacité consommées par l'opération.

Scénarios

Lire une plage de lignes à partir d'un index secondaire global

L'exemple suivant lit les lignes dont la valeur category est books à partir de l'index secondaire global example_global_index et gère le jeton de pagination nextStartPrimaryKey.

PrimaryKey startPrimaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.INF_MIN)
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.INF_MIN)
        .build();
PrimaryKey endPrimaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.INF_MAX)
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.INF_MAX)
        .build();

RangeRowQueryCriteria rangeCriteria =
        new RangeRowQueryCriteria("example_global_index");
rangeCriteria.setInclusiveStartPrimaryKey(startPrimaryKey);
rangeCriteria.setExclusiveEndPrimaryKey(endPrimaryKey);
rangeCriteria.setMaxVersions(1);
rangeCriteria.setLimit(100);

List<Row> rows = new ArrayList<>();
while (true) {
    GetRangeResponse response =
            client.getRange(new GetRangeRequest(rangeCriteria));
    rows.addAll(response.getRows());

    if (response.getNextStartPrimaryKey() == null) {
        break;
    }
    rangeCriteria.setInclusiveStartPrimaryKey(
            response.getNextStartPrimaryKey());
}
rows.forEach(System.out::println);

Interroger la table de données pour les colonnes d'attribut

L'exemple suivant utilise les rows renvoyées dans l'exemple précédent. Il extrait la clé primaire de la table de données à partir de chaque clé primaire de la table d'index et interroge la table de données example_table pour la colonne d'attribut detail, qui n'est pas incluse dans la table d'index.

for (Row indexRow : rows) {
    PrimaryKey indexPrimaryKey = indexRow.getPrimaryKey();
    PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
            .addPrimaryKeyColumn(
                    "user_id",
                    indexPrimaryKey.getPrimaryKeyColumn("user_id").getValue())
            .addPrimaryKeyColumn(
                    "order_id",
                    indexPrimaryKey.getPrimaryKeyColumn("order_id").getValue())
            .build();

    SingleRowQueryCriteria rowCriteria =
            new SingleRowQueryCriteria("example_table", primaryKey);
    rowCriteria.addColumnsToGet("detail");
    rowCriteria.setMaxVersions(1);

    GetRowResponse response =
            client.getRow(new GetRowRequest(rowCriteria));
    System.out.println(response.getRow());
}