Read rows with an iterator - Tablestore SDK for Java - Tablestore

Le SDK Tablestore pour Java permet de lire les lignes comprises dans une plage de clés primaires à l'aide d'un itérateur et récupère automatiquement les lots suivants.

Prérequis

Installez le SDK Tablestore pour Java et initialisez le client.

Description

Appelez la méthode createRangeIterator pour créer un itérateur de lignes sur une plage de clés primaires donnée. Lorsque le lot actuel est épuisé, l'itérateur envoie automatiquement la requête suivante. Vous n'avez pas besoin de suivre nextStartPrimaryKey ni de boucler sur getRange.

public Iterator<Row> createRangeIterator(RangeIteratorParameter rangeIteratorParameter) throws TableStoreException, ClientException

L'exemple suivant parcourt la table range_iter_demo vers l'avant, en commençant par la clé primaire row1 et en continuant jusqu'à la fin de la table, tout en affichant chaque ligne.

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

// End primary key (exclusive). INF_MAX reads to the end of the table.
PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
parameter.setExclusiveEndPrimaryKey(endPkBuilder.build());

parameter.setMaxVersions(1);

Iterator<Row> iterator = client.createRangeIterator(parameter);
int count = 0;
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
    count++;
}
System.out.println("Total rows iterated: " + count);

Paramètres

Utilisez RangeIteratorParameter pour transmettre les conditions de requête d'itération. Les paramètres sont décrits ci-dessous.

Nom	Type	Description
tableName (obligatoire)	String	Nom de la table à lire.
inclusiveStartPrimaryKey (obligatoire)	PrimaryKey	Clé primaire de début, incluant les noms et les valeurs des colonnes de clé primaire. Les données renvoyées incluent la clé primaire de début. Le nombre et les types de colonnes de clé primaire doivent correspondre au schéma de la table. Pour une itération vers l'avant, la clé primaire de début doit être inférieure à la clé primaire de fin. Pour une itération vers l'arrière, la clé primaire de début doit être supérieure à la clé primaire de fin. Utilisez `PrimaryKeyValue.INF_MIN` pour l'infini négatif et `PrimaryKeyValue.INF_MAX` pour l'infini positif.
exclusiveEndPrimaryKey (obligatoire)	PrimaryKey	Clé primaire de fin, incluant les noms et les valeurs des colonnes de clé primaire. Les données renvoyées n'incluent pas la clé primaire de fin. Le nombre et les types de colonnes de clé primaire doivent correspondre au schéma de la table. Utilisez `PrimaryKeyValue.INF_MIN` pour l'infini négatif et `PrimaryKeyValue.INF_MAX` pour l'infini positif.
direction (facultatif)	Direction	Sens de lecture. `FORWARD` : valeur par défaut. Itère vers l'avant. `BACKWARD` : itère vers l'arrière.
maxVersions (facultatif)	OptionalValue<Integer>	Nombre maximal de versions renvoyées par colonne d'attribut. Vous devez définir au moins l'un des paramètres `maxVersions` et `timeRange`. Si le nombre de versions correspondantes dépasse ce maximum, Tablestore renvoie les versions les plus récentes, de la plus récente à la plus ancienne, dans la limite du maximum défini.
timeRange (facultatif)	OptionalValue<TimeRange>	Plage de versions. Vous devez définir au moins l'un des paramètres `maxVersions` et `timeRange`. Chaque colonne d'attribut peut contenir plusieurs versions. La définition d'une plage de versions permet de renvoyer uniquement les données comprises dans cette plage.
maxCount (facultatif)	int	Nombre total maximal de lignes que l'itérateur renvoie. Doit être supérieur à 0.
bufferSize (facultatif)	int	Nombre de lignes récupérées par requête sous-jacente. Doit être supérieur à 0. Réduisez cette valeur pour diminuer l'utilisation maximale de la mémoire lors de balayages volumineux. Lorsque le lot actuel est épuisé, l'itérateur demande automatiquement le lot suivant à partir du point d'arrêt.
columnsToGet (facultatif)	Set<String>	Colonnes à lire. Il peut s'agir de colonnes de clé primaire ou de colonnes d'attribut. Si `columnsToGet` n'est pas défini, la ligne entière est renvoyée. Si `columnsToGet` est défini et qu'une ligne ne contient aucune des colonnes spécifiées, la valeur `null` est renvoyée.
filter (facultatif)	OptionalValue<Filter>	Condition de filtrage. Pour plus d'informations, consultez Utiliser des filtres. Si vous définissez à la fois `columnsToGet` et `filter`, `columnsToGet` sélectionne d'abord les colonnes, puis `filter` évalue les lignes.

Réponse

La méthode createRangeIterator renvoie un objet Iterator<Row>. Appelez hasNext() pour déterminer si d'autres données sont disponibles et next() pour obtenir l'objet Row suivant.

Exemples

Itération vers l'arrière

Utilisez setDirection(Direction.BACKWARD) pour effectuer une itération vers l'arrière. Pour une itération vers l'arrière, la clé primaire de début doit être supérieure à la clé primaire de fin.

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);
parameter.setDirection(Direction.BACKWARD);

// For backward iteration, the start primary key must be greater than the end primary key.
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
parameter.setInclusiveStartPrimaryKey(startPkBuilder.build());

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

parameter.setMaxVersions(1);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}

Limiter le nombre total de lignes

Utilisez setMaxCount pour limiter le nombre total de lignes renvoyées par l'itérateur. Cette approche est utile pour les lectures de type Top-N et évite les balayages inutiles.

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

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

parameter.setMaxVersions(1);
// Return at most 3 rows.
parameter.setMaxCount(3);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}

Optimiser la mémoire avec la taille du lot

Utilisez setBufferSize pour contrôler le nombre de lignes récupérées par requête sous-jacente. Réduisez cette valeur pour diminuer l'utilisation maximale de la mémoire lors de balayages volumineux.

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

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

parameter.setMaxVersions(1);
// Fetch 2 rows per underlying request.
parameter.setBufferSize(2);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}