Use filters - Tablestore SDK for Python - Tablestore - Centro de documentación de Alibaba Cloud

Utilice Tablestore SDK for Python para filtrar filas por valores de columnas de atributos en el servidor y reducir la cantidad de datos que se devuelven al cliente.

Requisitos previos

Instale Tablestore SDK for Python e inicialice un cliente.

Descripción de la función

Los filtros se aplican después de que el servidor lee los datos. Solo se devuelven al cliente las filas que cumplen con las condiciones. El filtrado no reduce el número de filas leídas por el servidor ni las CU de lectura consumidas. Utilice los filtros después de acotar el rango de clave primaria.

Se admiten las siguientes condiciones de filtro:

SingleColumnCondition compara el valor de una columna de atributo.
SingleColumnRegexCondition extrae una subcadena de una columna de atributo de tipo cadena y compara el valor extraído.
CompositeColumnCondition combina hasta 32 condiciones mediante AND, OR o NOT.

El siguiente ejemplo devuelve solo las filas cuyo valor más reciente en la columna de atributo status es online durante una lectura por rango.

column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
)
start_primary_key = [("partition", "device"), ("id", INF_MIN)]
end_primary_key = [("partition", "device"), ("id", INF_MAX)]

consumed, next_start_primary_key, rows, next_token = client.get_range(
    "example_table",
    Direction.FORWARD,
    start_primary_key,
    end_primary_key,
    column_filter=column_filter,
)

Parámetros

Condición de valor de columna única

Llame a SingleColumnCondition(column_name, column_value, comparator, pass_if_missing=True, latest_version_only=True) para crear una condición de valor de columna única.

Nombre	Tipo	Descripción
column_name (obligatorio)	`str`	Nombre de la columna de atributo que se va a evaluar.
column_value (obligatorio)	`str`, `int`, `bytes`, `float` o `bool`	Valor objetivo. Su tipo debe coincidir con el tipo de valor de la columna de atributo.
comparator (obligatorio)	`ComparatorType`	Operador de comparación. Los valores válidos son `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_EQUAL`, `LESS_THAN` y `LESS_EQUAL`.
pass_if_missing (opcional)	`bool`	Especifica si una fila pasa el filtro cuando falta la columna de atributo objetivo. Valor predeterminado: `True`. Si este parámetro es `False`, no se devuelven las filas sin dicha columna.
latest_version_only (opcional)	`bool`	Especifica si se evalúa únicamente la versión más reciente. Valor predeterminado: `True`. Si este parámetro es `False`, una fila pasa el filtro si cualquier versión cumple con la condición.

Condición de expresión regular

Llame a SingleColumnRegexCondition(column_name, comparator, column_value=None, regex_rule=None, latest_version_only=True) para crear una condición de expresión regular. Solo las columnas de atributo de tipo cadena admiten el filtrado mediante expresiones regulares.

Nombre	Tipo	Descripción
column_name (obligatorio)	`str`	Nombre de la columna de atributo de tipo cadena que se va a evaluar.
comparator (obligatorio)	`ComparatorType`	Operador de comparación. Los valores válidos son `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_EQUAL`, `LESS_THAN`, `LESS_EQUAL`, `EXIST` y `NOT_EXIST`.
column_value (opcional)	`str`, `int` o `float`	Valor objetivo. Omita este parámetro si `comparator` es `EXIST` o `NOT_EXIST`. En caso contrario, este parámetro es obligatorio. Su tipo debe coincidir con `regex_rule.cast_type`.
regex_rule (opcional)	`RegexRule`	Regla de extracción de subcadenas y conversión de tipos.
latest_version_only (opcional)	`bool`	Especifica si se evalúa únicamente la versión más reciente. Valor predeterminado: `True`. Si este parámetro es `False`, una fila pasa el filtro si cualquier versión cumple con la condición.

Si falta la columna de atributo objetivo, ninguna fila pasará el filtro de expresión regular. No es posible configurar pass_if_missing de forma independiente para esta condición.

Regla de expresión regular

El parámetro regex_rule es del tipo RegexRule y contiene los siguientes parámetros.

Nombre	Tipo	Descripción
regex_input (obligatorio)	`str`	Expresión regular, de hasta 256 bytes. Se admiten expresiones compatibles con Perl y caracteres de un solo byte. No se admiten caracteres chinos. Si la expresión contiene grupos de captura, se extrae el primer grupo; de lo contrario, se extrae toda la coincidencia.
cast_type (obligatorio)	`CastType`	Tipo al que se convierte el valor extraído. Los valores válidos son `VT_STRING`, `VT_INTEGER` y `VT_DOUBLE`. Las filas cuyos valores extraídos no puedan convertirse no pasarán el filtro.

Condición compuesta

Llame a CompositeColumnCondition(combinator) para crear una condición compuesta y, a continuación, llame a add_sub_condition para agregar condiciones.

Nombre	Tipo	Descripción
combinator (obligatorio)	`LogicalOperator`	Operador lógico. Los valores válidos son `AND`, `OR` y `NOT`.
sub_conditions (obligatorio)	`List[ColumnCondition]`	Condiciones que se van a combinar. Se admiten condiciones de valor de columna única, condiciones de expresión regular y condiciones compuestas anidadas, con un máximo de 32 condiciones.

Ejemplos

Filtrado con expresión regular

El siguiente ejemplo extrae el número de valores como user_004 en la columna de atributo account, convierte el número a un entero y devuelve solo las filas cuyo valor extraído sea mayor que 3.

regex_rule = RegexRule(r"user_(\d+)", CastType.VT_INTEGER)
column_filter = SingleColumnRegexCondition(
    "account",
    ComparatorType.GREATER_THAN,
    3,
    regex_rule,
)

consumed, next_start_primary_key, rows, next_token = client.get_range(
    "example_table",
    Direction.FORWARD,
    start_primary_key,
    end_primary_key,
    column_filter=column_filter,
)

Combinación de filtros

El siguiente ejemplo construye el filtro (category == "sensor" OR category == "gateway") AND score > 3.

category_filter = CompositeColumnCondition(LogicalOperator.OR)
category_filter.add_sub_condition(
    SingleColumnCondition("category", "sensor", ComparatorType.EQUAL)
)
category_filter.add_sub_condition(
    SingleColumnCondition("category", "gateway", ComparatorType.EQUAL)
)

column_filter = CompositeColumnCondition(LogicalOperator.AND)
column_filter.add_sub_condition(category_filter)
column_filter.add_sub_condition(
    SingleColumnCondition("score", 3, ComparatorType.GREATER_THAN)
)

Evaluación de versiones históricas

El siguiente ejemplo establece latest_version_only en False. Se devuelve una fila si cualquier versión de la columna de atributo status es online. No se devuelven las filas que carecen de la columna status.

column_filter = SingleColumnCondition(
    "status",
    "online",
    ComparatorType.EQUAL,
    pass_if_missing=False,
    latest_version_only=False,
)