Uso de filtros - Tablestore - Centro de documentación de Alibaba Cloud

El Tablestore SDK for Java filtra filas por valor de columna o devuelve una porción de las columnas de atributos en el servidor para reducir la cantidad de datos transferidos al cliente.

Requisitos previos

Instale Tablestore SDK for Java e inicialice el cliente.

Descripción

Un filtro se ejecuta en el servidor después de leer cada fila y devuelve solo las filas que coinciden con sus criterios. Dado que el filtrado ocurre después de la lectura, no reduce el número de filas escaneadas, pero sí disminuye el volumen de datos enviados a través de la red.

Establezca un filtro mediante la llamada a setFilter en SingleRowQueryCriteria, RangeRowQueryCriteria, MultiRowQueryCriteria o RangeIteratorParameter. A continuación se muestran los tipos de filtros disponibles:

SingleColumnValueFilter: compara el valor de una columna de propiedad con un valor objetivo mediante un operador relacional.
SingleColumnValueRegexFilter: extrae una subcadena de una columna de propiedad de tipo String mediante una expresión regular, la convierte a un tipo objetivo y la compara con un valor objetivo.
CompositeColumnValueFilter: combina varios filtros con operadores lógicos (AND, OR o NOT). Un filtro compuesto admite hasta 32 subcondiciones.
ColumnPaginationFilter: devuelve columnas de atributos según un desplazamiento y un límite, sin evaluar los valores de las columnas.

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

En el siguiente ejemplo se leen filas de la tabla filter_demo donde la columna col1 es igual a val1 mediante el uso de 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());

Parámetros

Filtro de valor de columna única

El constructor de SingleColumnValueFilter contiene los siguientes parámetros.

Nombre	Tipo	Descripción
columnName (obligatorio)	String	Nombre de la columna de propiedad que se va a evaluar.
operator (obligatorio)	CompareOperator	Operador relacional. Valores válidos: `EQUAL` (igual a) `NOT_EQUAL` (no igual a) `GREATER_THAN` (mayor que) `GREATER_EQUAL` (mayor o igual que) `LESS_THAN` (menor que) `LESS_EQUAL` (menor o igual que)
columnValue (obligatorio)	ColumnValue	Valor utilizado en la comparación.
passIfMissing (opcional)	boolean	Indica si se deben devolver las filas que no contienen la columna objetivo. Valor predeterminado: `true`; dichas filas se devuelven. Establézcalo en `false` para excluir las filas que no contienen la columna objetivo.
latestVersionsOnly (opcional)	boolean	Indica si se debe evaluar solo la versión más reciente de la columna. Valor predeterminado: `true`; solo se evalúa la versión más reciente. Establézcalo en `false` para devolver la fila si alguna versión coincide con la condición.

Filtro de expresión regular

El constructor de SingleColumnValueRegexFilter contiene los siguientes parámetros. Si especifica una regla de expresión regular, la columna de atributos objetivo debe ser del tipo String.

Nombre	Tipo	Descripción
columnName (obligatorio)	String	Nombre de la columna de atributos que se va a evaluar. Si se especifica `regexRule`, la columna debe ser del tipo `String`.
regexRule (opcional)	RegexRule	Regla de coincidencia de expresión regular. Si se especifica, el filtro extrae una subcadena del valor de la columna de cadena, la convierte y luego la evalúa. Si se omite, el filtro evalúa el valor original de la columna. La regla contiene los siguientes parámetros: `regex`: expresión regular que coincide con una subcadena. Longitud máxima: 256 bytes. Admite expresiones regulares de un solo byte compatibles con Perl; no coincide con caracteres chinos. Admite grupos de captura: cuando la expresión contiene grupos, la expresión regular devuelve la primera subcadena coincidente. Por ejemplo, si el valor de la columna es `1aaa51bbb5` y la expresión regular es `1([a-z]+)5`, la subcadena devuelta es `aaa`. `castType`: tipo al que se convertirá la subcadena coincidente. Valores válidos: `VT_INTEGER` (entero), `VT_DOUBLE` (punto flotante de doble precisión) y `VT_STRING` (cadena).
operator (obligatorio)	CompareOperator	Operador de evaluación. Valores válidos: `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_EQUAL`, `LESS_THAN`, `LESS_EQUAL`, `EXIST` y `NOT_EXIST`.
columnValue (opcional)	ColumnValue	Valor de comparación. Este parámetro es obligatorio para los seis operadores relacionales y debe omitirse para `EXIST` y `NOT_EXIST`. Si se especifica `regexRule`, el tipo de valor debe coincidir con `castType`.
latestVersionsOnly (opcional)	boolean	Especifica si se debe evaluar solo la versión más reciente de la columna de atributos. Valor predeterminado: `true`. Si se establece en `false`, la fila se devuelve cuando cualquier versión coincide.

Filtro compuesto

El constructor y la lista de subfiltros de CompositeColumnValueFilter contienen los siguientes parámetros. Agregue subfiltros mediante la llamada a addFilter(). Un filtro compuesto admite hasta 32 subcondiciones.

Nombre

Tipo

Descripción

type (obligatorio)

LogicOperator

Operador lógico. Valores válidos:

AND (AND lógico). Agregue como mínimo dos subfiltros.
OR (OR lógico). Agregue como mínimo dos subfiltros.
NOT (NOT lógico). Agregue exactamente un subfiltro.

filters (obligatorio)

List<ColumnValueFilter>

Subfiltros combinados por el operador lógico. Agregue cada subfiltro con addFilter(). Un subfiltro puede ser SingleColumnValueFilter, SingleColumnValueRegexFilter u otro CompositeColumnValueFilter (se admite el anidamiento).

Filtro de paginación de columnas de atributos

El constructor de ColumnPaginationFilter contiene los siguientes parámetros. Si se omite offset, el valor predeterminado es 0.

Nombre	Tipo	Descripción
limit (obligatorio)	int	Número de columnas de atributos que se van a devolver. El valor debe ser mayor que 0.
offset (opcional)	int	Desplazamiento basado en cero de la primera columna de atributos que se va a devolver. El valor debe ser mayor o igual que 0. Valor predeterminado: `0`.

Ejemplos

Comparar una subcadena extraída con una expresión regular

Utilice RegexRule para extraer una subcadena de un valor de columna y luego comparar la subcadena con un valor objetivo. En el siguiente ejemplo se aplica la expresión regular 1([a-z]+)5 a col2, se captura el primer grupo y se compara con la cadena 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 varios filtros con operadores lógicos

Utilice CompositeColumnValueFilter para combinar varios filtros con operadores lógicos. Los filtros compuestos pueden anidarse. En el siguiente ejemplo se construye la condición (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 la evaluación de columnas faltantes y versiones históricas

Utilice setPassIfMissing para controlar si se devuelven las filas que no contienen la columna objetivo, y setLatestVersionsOnly para controlar si también se evalúan las versiones históricas.

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

Devolver una página de columnas de atributos

Utilice ColumnPaginationFilter para devolver un número específico de columnas de atributos a partir de un desplazamiento. En el siguiente ejemplo se omite la primera columna de atributos y se devuelven las dos siguientes.

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