Os filtros permitem filtrar resultados de leitura no lado do servidor e retornam apenas as linhas correspondentes aos critérios definidos. Essa abordagem reduz a transferência de dados pela rede e diminui os tempos de resposta.
Casos de uso
-
Filtragem direta de resultados
Considere um medidor inteligente em um cenário de Internet das Coisas (IoT). O medidor grava dados como tensão, amperagem e consumo no Tablestore com frequência fixa, por exemplo, a cada 15 segundos. Para análises diárias, identifique se houve anomalias de tensão em um medidor e recupere outros dados de status desses momentos para decidir sobre a necessidade de inspeção na linha elétrica.
Sem filtro, use a operação
GetRangepara ler todos os 5.760 registros de monitoramento de um único medidor durante um dia. Em seguida, processe esses 5.760 registros no lado do cliente para encontrar os 10 registros que indicam instabilidade de tensão.Com filtro, o servidor retorna apenas os 10 registros necessários. Essa estratégia reduz significativamente a transferência de dados e elimina a filtragem no lado do cliente, o que economiza custos de desenvolvimento.
-
Filtragem com expressões regulares e conversão de tipos
Se uma coluna armazenar dados em formato personalizado, como string JSON, filtre um subcampo dentro dessa string. Use uma expressão regular para corresponder e extrair o valor do subcampo, converta-o para o tipo de dados desejado e aplique o filtro.
Por exemplo, suponha que uma coluna armazene dados no formato
{cluster_name:name1,lastupdatetime:12345}. Para consultar linhas ondelastupdatetime>12345, utilize a expressão regularlastupdatetime:([0-9]+)}para extrair o valor do subcampo. Depois, converta o valor extraído para tipo numérico e compare-o para encontrar as linhas desejadas.
Visão geral
Use filtros com as operações GetRow, BatchGetRow ou GetRange para retornar apenas as linhas que atendem às condições especificadas. O filtro não altera a semântica nativa nem os limites dessas operações. Para mais informações, consulte Ler dados.
Os filtros oferecem as seguintes opções de configuração:
Use o parâmetro PassIfMissing para definir o comportamento do filtro quando uma coluna referenciada não existir em uma linha.
Caso uma coluna referenciada tenha várias versões, configure o filtro para comparar apenas o valor da versão mais recente.
Utilize expressões regulares para corresponder a valores de subcampos.
Construa condições de filtro compostas com operadores relacionais e lógicos.
O Tablestore fornece SingleColumnValueFilter, SingleColumnValueRegexFilter e CompositeColumnValueFilter. Esses filtros determinam se uma linha deve ser retornada com base nos valores de uma ou mais colunas de referência.
Filtro | Descrição |
Filtra linhas com base no valor de uma única coluna de referência. | |
Permite usar expressão regular para corresponder a substrings dentro de coluna do tipo string. Converta a substring correspondente para string, inteiro ou double e filtre com base no valor convertido. A expressão regular deve atender às seguintes condições:
| |
Filtra linhas mediante combinação lógica de condições em várias colunas. |
Observações de uso
As condições de filtro aceitam operadores relacionais (=, !=, >, >=, <, <=) e operadores lógicos (NOT, AND, OR). Combine até 10 condições.
Inclua as colunas referenciadas por um filtro na solicitação de leitura. Caso contrário, o filtro não acessará seus valores.
-
Na operação
GetRange, uma única varredura não pode exceder 5.000 linhas ou 4 MB de dados.Se nenhuma linha dentro das 5.000 linhas ou 4 MB de dados verificados corresponder às condições do filtro, o campo
Rowsna resposta estará vazio, masNextStartPrimaryKeypode não estar vazio. Nesse caso, continue a leitura com oNextStartPrimaryKeyretornado até que ele esteja vazio.
Uso
Use filtros apenas por meio de SDKs.
Use filtros com o Tablestore SDK for Java, Tablestore SDK for Go, Tablestore SDK for Python, Tablestore SDK for Node.js, Tablestore SDK for .NET e Tablestore SDK for PHP. Os exemplos a seguir usam o Tablestore SDK for Java.
SingleColumnValueFilter
O código de exemplo a seguir mostra como ler dados da versão mais recente de uma linha em tabela de dados e usar filtro para selecionar dados com base no valor da coluna Col0.
private static void getRow(SyncClient client, String pkValue) {
// Construct the primary key.
PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
PrimaryKey primaryKey = primaryKeyBuilder.build();
// Specify the table name and primary key to read a row of data.
SingleRowQueryCriteria criteria = new SingleRowQueryCriteria("<TABLE_NAME>", primaryKey);
// Set the MaxVersions parameter to 1 to read the latest version of data.
criteria.setMaxVersions(1);
// Configure a filter to return a row in which the value of the Col0 column is 0.
SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0",
SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
// If the Col0 column does not exist, the row is not returned.
singleColumnValueFilter.setPassIfMissing(false);
criteria.setFilter(singleColumnValueFilter);
GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria));
Row row = getRowResponse.getRow();
System.out.println("Read complete. Result:");
System.out.println(row);
}
SingleColumnValueRegexFilter
O código de exemplo a seguir demonstra como ler dados cujos valores de chave primária estão no intervalo ["pk:2020-01-01.log", "pk:2021-01-01.log") da coluna Col1 e usar expressão regular para filtrar dados nessa coluna.
private static void getRange(SyncClient client) {
// Specify the name of the data table.
RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("<TABLE_NAME>");
// Specify ["pk:2020-01-01.log", "pk:2021-01-01.log") as the range of the primary key of the data that you want to read. The range is a left-closed, right-open interval.
PrimaryKey pk0 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("2020-01-01.log"))
.build();
PrimaryKey pk1 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("2021-01-01.log"))
.build();
criteria.setInclusiveStartPrimaryKey(pk0);
criteria.setExclusiveEndPrimaryKey(pk1);
// Set the MaxVersions parameter to 1 to read the latest version of data.
criteria.setMaxVersions(1);
// Configure a filter. A row is returned when cast<int>(regex(Col1)) is greater than 100.
RegexRule regexRule = new RegexRule("t1:([0-9]+),", RegexRule.CastType.VT_INTEGER);
SingleColumnValueRegexFilter filter = new SingleColumnValueRegexFilter("Col1",
regexRule,SingleColumnValueRegexFilter.CompareOperator.GREATER_THAN,ColumnValue.fromLong(100));
criteria.setFilter(filter);
while (true) {
GetRangeResponse resp = client.getRange(new GetRangeRequest(criteria));
for (Row row : resp.getRows()) {
// do something
System.out.println(row);
}
if (resp.getNextStartPrimaryKey() != null) {
criteria.setInclusiveStartPrimaryKey(resp.getNextStartPrimaryKey());
} else {
break;
}
}
}
CompositeColumnValueFilter
O exemplo a seguir mostra como retornar linhas cuja chave primária está no intervalo ["a","h") e que atendem à seguinte condição: (Col0 == 0 AND Col1 > 100) OR (Col2 <= 10).
private static void getRange(SyncClient client) {
// Specify the table name.
RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("<TABLE_NAME>");
// Set the primary key range to a left-closed, right-open interval.
PrimaryKey pk0 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("a"))
.build();
PrimaryKey pk1 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("h"))
.build();
criteria.setInclusiveStartPrimaryKey(pk0);
criteria.setExclusiveEndPrimaryKey(pk1);
// Set the query to read only the latest version.
criteria.setMaxVersions(1);
// The condition for composite1 is (Col0 == 0) AND (Col1 > 100).
CompositeColumnValueFilter composite1 = new CompositeColumnValueFilter(CompositeColumnValueFilter.LogicOperator.AND);
SingleColumnValueFilter single1 = new SingleColumnValueFilter("Col0",
SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
SingleColumnValueFilter single2 = new SingleColumnValueFilter("Col1",
SingleColumnValueFilter.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100));
composite1.addFilter(single1);
composite1.addFilter(single2);
// The condition for composite2 is ( (Col0 == 0) AND (Col1 > 100) ) OR (Col2 <= 10).
CompositeColumnValueFilter composite2 = new CompositeColumnValueFilter(CompositeColumnValueFilter.LogicOperator.OR);
SingleColumnValueFilter single3 = new SingleColumnValueFilter("Col2",
SingleColumnValueFilter.CompareOperator.LESS_EQUAL, ColumnValue.fromLong(10));
composite2.addFilter(composite1);
composite2.addFilter(single3);
criteria.setFilter(composite2);
while (true) {
GetRangeResponse resp = client.getRange(new GetRangeRequest(criteria));
for (Row row : resp.getRows()) {
// do something
System.out.println(row);
}
if (resp.getNextStartPrimaryKey() != null) {
criteria.setInclusiveStartPrimaryKey(resp.getNextStartPrimaryKey());
} else {
break;
}
}
}
Faturamento
Os filtros não alteram as regras de faturamento existentes.
Embora os filtros reduzam a quantidade de dados retornados, eles não diminuem as unidades de capacidade de leitura (CUs) consumidas. A filtragem ocorre no servidor após a leitura dos dados do disco, portanto o número de operações de E/S permanece inalterado. Por exemplo, se uma operação GetRange ler 100 linhas totalizando 200 KB e consumir 50 CUs de leitura, aplicar filtro que retorne apenas 10 linhas (20 KB) ainda consumirá 50 CUs de leitura.
Perguntas frequentes
Referências
Se sua aplicação precisar consultar dados com base em diferentes atributos, defina esses atributos como colunas de chave primária de índice secundário para permitir buscas rápidas. Para mais informações, consulte Índice secundário.
Para cenários de negócios que exigem consultas multidimensionais (como consultas em colunas fora da chave primária, consultas compostas ou buscas fuzzy) ou análise de dados (como busca de agregações, contagem de linhas ou agrupamento de dados), utilize índice de pesquisa. Defina os atributos necessários como campos do índice de pesquisa para consultar e analisar seus dados. Para mais informações, consulte Índice de pesquisa.