Filters - Tablestore SDK for Java - Tablestore: Central de Documentação do Alibaba Cloud

Varreduras completas de tabelas e leituras por intervalo retornam muitas linhas que a aplicação descarta posteriormente, desperdiçando largura de banda. Os filtros avaliam os valores das colunas de atributo no servidor e retornam apenas as linhas correspondentes aos critérios definidos, o que reduz o tráfego de rede. O Tablestore SDK for Java oferece suporte a comparações de coluna única, comparações em substrings extraídas por expressões regulares e combinações lógicas de múltiplas condições.

Pré-requisitos

Instale o Tablestore SDK for Java e inicialize o cliente.

Funcionamento dos filtros

O filtro executa no servidor após a leitura de cada linha e retorna somente aquelas que atendem aos critérios definidos. Como a filtragem ocorre depois da leitura, ela não reduz o número de linhas percorridas na varredura, mas diminui o volume de dados transmitidos pela rede.

Anexe um filtro a uma solicitação de consulta chamando o método setFilter. Classes de solicitação suportadas: SingleRowQueryCriteria, RangeRowQueryCriteria, MultiRowQueryCriteria e RangeIteratorParameter. O Tablestore SDK for Java fornece três tipos de filtro:

SingleColumnValueFilter: compara o valor de uma coluna de atributo com um valor-alvo usando um operador relacional.
SingleColumnValueRegexFilter: extrai uma substring de uma coluna de atributo do tipo String por meio de uma expressão regular, converte-a para um tipo específico e a compara com um valor-alvo.
CompositeColumnValueFilter: combina vários filtros com operadores lógicos (AND, OR ou NOT). Um filtro composto aceita até 32 subcondições.

Os três filtros possuem as seguintes assinaturas de classe:

public class SingleColumnValueFilter extends ColumnValueFilter

public class SingleColumnValueRegexFilter extends ColumnValueFilter

public class CompositeColumnValueFilter extends ColumnValueFilter

O exemplo a seguir lê linhas da tabela filter_demo nas quais a coluna col1 é igual a val1. Ele utiliza o SingleColumnValueFilter, o mais comum entre os três.

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());

Parâmetros

SingleColumnValueFilter

Assinatura: new SingleColumnValueFilter(columnName, operator, columnValue).

Name	Type	Description
columnName (required)	String	Nome da coluna de atributo a avaliar.
operator (required)	CompareOperator	Operador relacional. Valores válidos: `EQUAL` (igual a) `NOT_EQUAL` (diferente de) `GREATER_THAN` (maior que) `GREATER_EQUAL` (maior ou igual a) `LESS_THAN` (menor que) `LESS_EQUAL` (menor ou igual a)
columnValue (required)	ColumnValue	Valor usado na comparação.
passIfMissing (optional)	boolean	Define se as linhas sem a coluna-alvo devem ser retornadas. Padrão `true`: essas linhas são incluídas no resultado. Defina como `false` para excluir linhas que não contêm a coluna-alvo.
latestVersionsOnly (optional)	boolean	Indica se apenas a versão mais recente da coluna deve ser avaliada. Padrão `true`: somente a última versão passa pela avaliação. Defina como `false` para retornar a linha caso qualquer versão atenda à condição.

SingleColumnValueRegexFilter

Assinatura: new SingleColumnValueRegexFilter(columnName, regexRule, operator, columnValue). **Apenas colunas de atributo do tipo String aceitam filtragem por expressão regular.**

Name	Type	Description
columnName (required)	String	Nome da coluna de atributo a avaliar. A coluna deve ser do tipo `String`.
regexRule (required)	RegexRule	Regra de correspondência por expressão regular. Contém dois parâmetros: `regex` e `castType`. `regex`: expressão regular usada para extrair uma substring. Tamanho máximo de 256 bytes. Aceita expressões regulares de byte único compatíveis com Perl; não corresponde a caracteres chineses. Permite grupos de captura — quando a expressão contém grupos, o filtro retorna a primeira substring correspondente. Por exemplo, se o valor da coluna for `1aaa51bbb5` e a expressão for `1([a-z]+)5`, a substring retornada será `aaa`. `castType`: tipo para o qual a substring extraída será convertida. Opções disponíveis: `VT_INTEGER` (inteiro), `VT_DOUBLE` (ponto flutuante de precisão dupla) e `VT_STRING` (string).
operator (required)	CompareOperator	Operador relacional. Os valores válidos são os mesmos do `SingleColumnValueFilter`: `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_EQUAL`, `LESS_THAN` e `LESS_EQUAL`.
columnValue (required)	ColumnValue	Valor usado na comparação. O tipo deve corresponder ao `castType` definido.

CompositeColumnValueFilter

Assinatura: new CompositeColumnValueFilter(logicOperator). Adicione subfiltros chamando addFilter(). Um filtro composto aceita até 32 subcondições.

Name

Type

Description

type (required)

LogicOperator

Operador lógico. Valores válidos:

AND (E lógico)
OR (OU lógico)
NOT (NEGAÇÃO lógica)

filters (required)

List<ColumnValueFilter>

Subfiltros combinados pelo operador lógico. Inclua cada subfiltro com addFilter(). Um subfiltro pode ser SingleColumnValueFilter, SingleColumnValueRegexFilter ou outro CompositeColumnValueFilter (aninhamento permitido).

Exemplos

Comparar uma substring extraída por expressão regular

Use RegexRule para extrair uma substring do valor de uma coluna e compará-la com um valor-alvo. No exemplo abaixo, a expressão regular 1([a-z]+)5 é aplicada à coluna col2, capturando o primeiro grupo e comparando-o com a string 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());

Combinar múltiplos filtros com operadores lógicos

Use CompositeColumnValueFilter para combinar diversos filtros por meio de operadores lógicos. Filtros compostos permitem aninhamento. O exemplo a seguir constrói a condição (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());

Controlar a avaliação de colunas ausentes e versões históricas

Use setPassIfMissing para definir se linhas sem a coluna-alvo serão retornadas e setLatestVersionsOnly para determinar se as versões anteriores também devem ser avaliadas.

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