Lire une plage de lignes - SDK Tablestore pour Java - Tablestore

Prérequis

Installez le SDK Tablestore pour Java et initialisez le client.

Description

Appelez la méthode getRange pour lire des lignes consécutives dans l'ordre croissant ou décroissant au sein d'une plage de clés primaires. Vous pouvez spécifier les colonnes à renvoyer, la plage de versions de données ainsi que les conditions de filtrage.

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

Remarque

Une seule lecture par plage renvoie au maximum 5 000 lignes ou 4 Mo de données. Lorsque l'une de ces limites est atteinte, utilisez la valeur nextStartPrimaryKey présente dans la réponse pour poursuivre la lecture.

L'exemple suivant effectue un balayage vers l'avant sur la table get_range_demo. Il lit toutes les lignes dont la clé primaire est supérieure ou égale à row1 et ne renvoie que la dernière version de chaque colonne.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

// Start primary key (inclusive)
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

// End primary key (exclusive); INF_MAX denotes positive infinity
PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
for (Row row : response.getRows()) {
    System.out.println(row);
}

Paramètres

L'objet GetRangeRequest contient les paramètres suivants.

Nom

Type

Description

rangeRowQueryCriteria (obligatoire)

RangeRowQueryCriteria

Les critères de lecture d'une plage de lignes.

transactionId (facultatif)

String

L'ID de transaction locale. Définissez ce paramètre uniquement lorsque vous lisez des données dans le cadre d'une transaction locale.

Pour savoir comment obtenir et utiliser cet ID, consultez la rubrique Utiliser des transactions locales.

Critères de requête par plage

Le paramètre rangeRowQueryCriteria est de type RangeRowQueryCriteria et comprend les éléments suivants.

Nom

Type

Description

tableName (obligatoire)

String

Le nom de la table.

inclusiveStartPrimaryKey (obligatoire)

PrimaryKey

La clé primaire de début inclusive. Pour une lecture vers l'avant, elle doit être inférieure à la clé primaire de fin. Pour une lecture vers l'arrière, elle doit être supérieure. Son schéma doit correspondre à celui de la table. Utilisez PrimaryKeyValue.INF_MIN et PrimaryKeyValue.INF_MAX pour représenter respectivement l'infini négatif et l'infini positif.

exclusiveEndPrimaryKey (obligatoire)

PrimaryKey

La clé primaire de fin exclusive. Son schéma doit correspondre à celui de la table. Utilisez PrimaryKeyValue.INF_MIN et PrimaryKeyValue.INF_MAX pour représenter respectivement l'infini négatif et l'infini positif.

direction (facultatif)

Direction

Le sens de lecture. La valeur par défaut est FORWARD. Définissez ce paramètre sur BACKWARD pour effectuer une lecture vers l'arrière.

maxVersions (facultatif)

Integer

Le nombre maximal de versions de données à renvoyer pour chaque colonne d'attribut. Si davantage de versions correspondent, Tablestore renvoie les versions de la plus récente à la plus ancienne. Définissez au moins l'un des paramètres maxVersions et timeRange.

timeRange (facultatif)

TimeRange

La plage de versions de données. Seules les versions comprises dans cette plage sont renvoyées. Définissez au moins l'un des paramètres maxVersions et timeRange.

limit (facultatif)

Integer

Le nombre maximal de lignes à renvoyer en un seul appel. La valeur doit être supérieure à 0. Lorsque la limite est atteinte, utilisez la valeur nextStartPrimaryKey présente dans la réponse pour poursuivre la lecture.

columnsToGet (facultatif)

Set<String>

Les colonnes à renvoyer. Si vous ne spécifiez pas ce paramètre, la ligne entière est renvoyée. Si vous le spécifiez, les lignes ne contenant aucune des colonnes indiquées ne sont pas renvoyées.

filter (facultatif)

Filter

La condition de filtrage. Si vous spécifiez à la fois columnsToGet et filter, Tablestore sélectionne d'abord les colonnes à renvoyer, puis applique le filtre.

Pour savoir comment configurer le filtre, consultez la rubrique Utiliser des filtres.

Réponse

L'objet GetRangeResponse contient les champs spécifiques à l'opération suivants.

Champ

Type

Description

rows

List<Row>

Les lignes renvoyées lors de l'appel actuel, obtenues en appelant la méthode getRows.

nextStartPrimaryKey

PrimaryKey

La clé primaire de début pour l'appel suivant, obtenue en appelant la méthode getNextStartPrimaryKey. Si la plage a été entièrement lue, la valeur null est renvoyée.

Exemples de scénarios

Itération paginée

La valeur nextStartPrimaryKey présente dans la réponse correspond à la clé primaire de début de la page suivante. Appelez la méthode getRange dans une boucle jusqu'à ce que la valeur nextStartPrimaryKey soit nulle afin de balayer toutes les lignes correspondantes.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MIN);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

int totalRows = 0;
while (true) {
    GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
    totalRows += response.getRows().size();

    // The current response did not return all rows; use nextStartPrimaryKey to fetch the next page.
    PrimaryKey nextStart = response.getNextStartPrimaryKey();
    if (nextStart == null) {
        break;
    }
    criteria.setInclusiveStartPrimaryKey(nextStart);
}
System.out.println("Total rows scanned: " + totalRows);

Balayage inverse

Utilisez la méthode setDirection(Direction.BACKWARD) pour effectuer un balayage dans l'ordre inverse. Dans ce cas, la clé primaire de début doit être supérieure à la clé primaire de fin.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);
criteria.setDirection(Direction.BACKWARD);

// For a reverse scan, the start primary key must be greater than the end primary key
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Rows (backward): " + response.getRows().size());

Filtrage conditionnel

Utilisez la méthode setFilter pour ne renvoyer que les lignes correspondant à une condition basée sur la valeur d'une colonne.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MIN);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

// Return only rows where col1 equals "val1"
SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));
filter.setPassIfMissing(false);
criteria.setFilter(filter);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Rows (filtered): " + response.getRows().size());