Filters - Tablestore SDK for Java - Tablestore - Centre de documentation Alibaba Cloud

Prérequis

Installez le SDK Tablestore pour Java et initialisez le client.

Description

Un filtre s'exécute côté serveur après la lecture de chaque ligne et ne renvoie que celles correspondant à vos critères. Comme le filtrage intervient après la lecture, il ne réduit pas le nombre de lignes analysées, mais diminue le volume de données envoyées sur le réseau.

Pour définir un filtre, appelez setFilter sur SingleRowQueryCriteria, RangeRowQueryCriteria, MultiRowQueryCriteria ou RangeIteratorParameter. Les types de filtres disponibles sont les suivants :

SingleColumnValueFilter : compare la valeur d'une colonne de propriété à une valeur cible à l'aide d'un opérateur relationnel.
SingleColumnValueRegexFilter : extrait une sous-chaîne d'une colonne de propriété de type String via une expression régulière, la convertit dans un type cible et la compare à une valeur cible.
CompositeColumnValueFilter : combine plusieurs filtres à l'aide d'opérateurs logiques (AND, OR ou NOT). Un filtre composite prend en charge jusqu'à 32 sous-conditions.
ColumnPaginationFilter : renvoie des colonnes d'attributs selon un décalage et une limite, sans évaluer les valeurs des colonnes.

new SingleColumnValueFilter(columnName, operator, columnValue)
new SingleColumnValueRegexFilter(columnName, regexRule, operator, columnValue)
new CompositeColumnValueFilter(logicOperator)
new ColumnPaginationFilter(limit, offset)

L'exemple suivant lit les lignes de la table filter_demo où la colonne col1 est égale à val1 en utilisant SingleColumnValueFilter.

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("filter_demo");

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

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

criteria.setMaxVersions(1);

// Build the filter: col1 == "val1"
SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));
criteria.setFilter(filter);

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

Paramètres

Filtre de valeur de colonne unique

Le constructeur de SingleColumnValueFilter accepte les paramètres suivants.

Nom	Type	Description
columnName (obligatoire)	String	Nom de la colonne de propriété à évaluer.
operator (obligatoire)	CompareOperator	Opérateur relationnel. Valeurs valides : `EQUAL` (égal à) `NOT_EQUAL` (différent de) `GREATER_THAN` (supérieur à) `GREATER_EQUAL` (supérieur ou égal à) `LESS_THAN` (inférieur à) `LESS_EQUAL` (inférieur ou égal à)
columnValue (obligatoire)	ColumnValue	Valeur utilisée pour la comparaison.
passIfMissing (facultatif)	boolean	Indique si les lignes ne contenant pas la colonne cible doivent être renvoyées. Par défaut, `true` : ces lignes sont renvoyées. Définissez cette option sur `false` pour exclure les lignes qui ne contiennent pas la colonne cible.
latestVersionsOnly (facultatif)	boolean	Indique si seule la dernière version de la colonne doit être évaluée. Par défaut, `true` : seule la dernière version est évaluée. Définissez cette option sur `false` pour renvoyer la ligne si n'importe quelle version correspond à la condition.

Filtre d'expression régulière

Le constructeur de SingleColumnValueRegexFilter accepte les paramètres suivants. Si vous spécifiez une règle d'expression régulière, la colonne d'attribut cible doit être de type String.

Nom	Type	Description
columnName (obligatoire)	String	Nom de la colonne d'attribut à évaluer. Si `regexRule` est spécifié, la colonne doit être de type `String`.
regexRule (facultatif)	RegexRule	Règle de correspondance d'expression régulière. Si elle est spécifiée, le filtre extrait une sous-chaîne de la valeur de la colonne de type chaîne, convertit la sous-chaîne, puis l'évalue. Si elle est omise, le filtre évalue la valeur originale de la colonne. La règle contient les paramètres suivants : `regex` : expression régulière qui correspond à une sous-chaîne. Longueur maximale : 256 octets. Prend en charge les expressions régulières mono-octet compatibles Perl ; ne correspond pas aux caractères chinois. Prend en charge les groupes de capture — lorsque l'expression contient des groupes, l'expression régulière renvoie la première sous-chaîne correspondante. Par exemple, si la valeur de la colonne est `1aaa51bbb5` et que l'expression régulière est `1([a-z]+)5`, la sous-chaîne renvoyée est `aaa`. `castType` : type vers lequel convertir la sous-chaîne correspondante. Valeurs valides : `VT_INTEGER` (entier), `VT_DOUBLE` (nombre à virgule flottante double précision) et `VT_STRING` (chaîne).
operator (obligatoire)	CompareOperator	Opérateur d'évaluation. Valeurs valides : `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_EQUAL`, `LESS_THAN`, `LESS_EQUAL`, `EXIST` et `NOT_EXIST`.
columnValue (facultatif)	ColumnValue	Valeur de comparaison. Ce paramètre est requis pour les six opérateurs relationnels et doit être omis pour `EXIST` et `NOT_EXIST`. Si `regexRule` est spécifié, le type de valeur doit correspondre à `castType`.
latestVersionsOnly (facultatif)	boolean	Indique si seule la dernière version de la colonne d'attribut doit être évaluée. Valeur par défaut : `true`. Si défini sur `false`, la ligne est renvoyée lorsque n'importe quelle version correspond.

Filtre composite

Le constructeur et la liste des sous-filtres de CompositeColumnValueFilter acceptent les paramètres suivants. Ajoutez des sous-filtres en appelant addFilter(). Un filtre composite prend en charge jusqu'à 32 sous-conditions.

Nom

Type

Description

type (obligatoire)

LogicOperator

Opérateur logique. Valeurs valides :

AND (ET logique). Ajoutez au moins deux sous-filtres.
OR (OU logique). Ajoutez au moins deux sous-filtres.
NOT (NON logique). Ajoutez exactement un sous-filtre.

filters (obligatoire)

List<ColumnValueFilter>

Sous-filtres combinés par l'opérateur logique. Ajoutez chaque sous-filtre avec addFilter(). Un sous-filtre peut être un SingleColumnValueFilter, un SingleColumnValueRegexFilter ou un autre CompositeColumnValueFilter (l'imbrication est prise en charge).

Filtre de pagination des colonnes d'attributs

Le constructeur de ColumnPaginationFilter accepte les paramètres suivants. Si offset est omis, la valeur par défaut est 0.

Nom

Type

Description

limit (obligatoire)

int

Nombre de colonnes d'attributs à renvoyer. La valeur doit être supérieure à 0.

offset (facultatif)

int

Décalage basé sur zéro de la première colonne d'attribut à renvoyer. La valeur doit être supérieure ou égale à 0. Valeur par défaut : 0.

Exemples

Comparer une sous-chaîne extraite avec une expression régulière

Utilisez RegexRule pour extraire une sous-chaîne d'une valeur de colonne, puis comparez-la à une valeur cible. L'exemple suivant applique l'expression régulière 1([a-z]+)5 à col2, capture le premier groupe et le compare à la chaîne aaa.

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("filter_demo");

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

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

criteria.setMaxVersions(1);

// The regex "1([a-z]+)5" captures the first group; castType=VT_STRING compares the result as a string.
RegexRule regexRule = new RegexRule("1([a-z]+)5", RegexRule.CastType.VT_STRING);
SingleColumnValueRegexFilter filter = new SingleColumnValueRegexFilter(
        "col2",
        regexRule,
        SingleColumnValueRegexFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("aaa"));
criteria.setFilter(filter);

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

Combiner plusieurs filtres avec des opérateurs logiques

Utilisez CompositeColumnValueFilter pour combiner plusieurs filtres à l'aide d'opérateurs logiques. Les filtres composites peuvent être imbriqués. L'exemple suivant construit la condition (col1 == "val1" OR cast<String>(reg(col2)) >= "aaa") AND col3 == "val3".

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("filter_demo");

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

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

criteria.setMaxVersions(1);

// Leaf 1: col1 == "val1"
SingleColumnValueFilter leaf1 = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));

// Leaf 2: cast<String>(reg(col2)) >= "aaa"
RegexRule regexRule = new RegexRule("1([a-z]+)5", RegexRule.CastType.VT_STRING);
SingleColumnValueRegexFilter leaf2 = new SingleColumnValueRegexFilter(
        "col2",
        regexRule,
        SingleColumnValueRegexFilter.CompareOperator.GREATER_EQUAL,
        ColumnValue.fromString("aaa"));

// OR combination: leaf1 OR leaf2
CompositeColumnValueFilter orFilter = new CompositeColumnValueFilter(
        CompositeColumnValueFilter.LogicOperator.OR);
orFilter.addFilter(leaf1);
orFilter.addFilter(leaf2);

// Leaf 3: col3 == "val3"
SingleColumnValueFilter leaf3 = new SingleColumnValueFilter(
        "col3",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val3"));

// AND combination: (leaf1 OR leaf2) AND leaf3
CompositeColumnValueFilter andFilter = new CompositeColumnValueFilter(
        CompositeColumnValueFilter.LogicOperator.AND);
andFilter.addFilter(orFilter);
andFilter.addFilter(leaf3);

criteria.setFilter(andFilter);

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

Contrôler l'évaluation des colonnes manquantes et des versions historiques

Utilisez setPassIfMissing pour contrôler si les lignes ne contenant pas la colonne cible sont renvoyées, et setLatestVersionsOnly pour contrôler si les versions historiques sont également évaluées.

SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));

// Skip rows that do not contain col1 (default: include such rows).
filter.setPassIfMissing(false);
// Evaluate all versions; return the row if any version matches (default: evaluate only the latest version).
filter.setLatestVersionsOnly(false);

criteria.setFilter(filter);

Renvoyer une page de colonnes d'attributs

Utilisez ColumnPaginationFilter pour renvoyer un nombre spécifié de colonnes d'attributs à partir d'un décalage. L'exemple suivant ignore la première colonne d'attribut et renvoie les deux suivantes.

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"))
        .build();

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria("filter_demo", primaryKey);
criteria.setMaxVersions(1);
criteria.setFilter(new ColumnPaginationFilter(2, 1));

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
for (Column column : response.getRow().getColumns()) {
    System.out.println(column.getName());
}