Expression Filters

Expression filter reference for langchain-mariadb, documenting the operator enum, filter builder classes, and MariaDBFilterExpressionConverter for metadata-based vector queries.

Version: langchain-mariadb v0.0.21

A flexible and composable filter expression system for building SQL-like queries.

This module provides a builder pattern implementation for creating complex filter expressions that can be converted to various query formats.

Example:

# Dict filter value
filter = {
   '$or': [{'status': {'$eq': 'active'}}, {'status': {'$eq': 'pending'}}],
   'age': {'$gte': 18}
   'country': {'$in': ['US', 'CA', 'UK']}
}

# Convert to SQL-like string (with a proper converter implementation)
converter = SQLFilterExpressionConverter()  # Some converter
sql_where = converter.convert_expression(filter)
print(sql_where)
# Output:
# (status = 'active' OR status = 'pending')
# AND age >= 18 AND country IN ['US','CA','UK']

Operator

Enumeration of supported filter operations

Attributes

• AND:

• OR:

• EQ:

• NE:

• GT:

• GTE:

• LT:

• LTE:

• LIKE:

• NLIKE:

• IN:

• NIN:

• NOT:

---

Key

Represents a key in a filter expression

Constructor

__init__(key: str)

Attributes

• key:

---

Value

Represents a value in a filter expression

Constructor

__init__(value: ValueType)

Attributes

• value:

---

Expression

Represents a boolean filter expression with a specific structure.

Constructor

__init__(type_: Operator, left: Operand, right: Optional[Operand] = None)

Attributes

• type:

• left:

• right:

---

Group

Represents a grouped collection of filter expressions.

Constructor

__init__(content: Expression)

Attributes

• content:

---

StringBuilder

Simple StringBuilder implementation for efficient string concatenation

Constructor

__init__() -> None

Methods

append

append(string: str) -> None

Attributes

• buffer (List[str]):

---

FilterExpressionConverter

Abstract base class defining the interface for converting filter expressions into various string-based query representations

Methods

convert_expression

convert_expression(filters: dict) -> str

Convert a complete expression into its string representation

convert_symbol_to_context

convert_symbol_to_context(exp: Expression, context: StringBuilder) -> None

Determine the appropriate operation symbol for a given expression

convert_operand_to_context

convert_operand_to_context(operand: Operand, context: StringBuilder) -> None

Convert an operand into a string representation within a given context

convert_expression_to_context

convert_expression_to_context(expression: Expression, context: StringBuilder) -> None

Convert an expression to its string representation in the given context

convert_key_to_context

convert_key_to_context(filter_key: Key, context: StringBuilder) -> None

Convert a key to its string representation in the given context

convert_value_to_context

convert_value_to_context(filter_value: Value, context: StringBuilder) -> None

Convert a value to its string representation in the given context

convert_single_value_to_context

convert_single_value_to_context(value: ValueType, context: StringBuilder) -> None

Convert a single value to its string representation in the given context

write_group_start

write_group_start(group: Group, context: StringBuilder) -> None

Write the start of a group in the given context

write_group_end

write_group_end(group: Group, context: StringBuilder) -> None

Write the end of a group in the given context

write_value_range_start

write_value_range_start(list_value: Value, context: StringBuilder) -> None

Write the start of a value range in the given context

write_value_range_end

write_value_range_end(list_value: Value, context: StringBuilder) -> None

Write the end of a value range in the given context

write_value_range_separator

write_value_range_separator(list_value: Value, context: StringBuilder) -> None

Write the separator between values in a range in the given context

---

BaseFilterExpressionConverter

Base implementation of the FilterExpressionConverter interface providing common functionality for converting filter expressions to string representations

Methods

convert_expression

convert_expression(filters: dict) -> str

convert_symbol_to_context

convert_symbol_to_context(exp: Expression, context: StringBuilder) -> None

convert_operand_to_context

convert_operand_to_context(operand: Operand, context: StringBuilder) -> None

convert_value_to_context

convert_value_to_context(filter_value: Value, context: StringBuilder) -> None

convert_single_value_to_context

convert_single_value_to_context(value: ValueType, context: StringBuilder) -> None

write_value_range_start

write_value_range_start(list_value: Value, context: StringBuilder) -> None

write_value_range_end

write_value_range_end(list_value: Value, context: StringBuilder) -> None

write_value_range_separator

write_value_range_separator(list_value: Value, context: StringBuilder) -> None

---

MariaDBFilterExpressionConverter

Converter for MariaDB filter expressions.

Constructor

__init__(metadata_field_name: str)

Methods

convert_expression_to_context

convert_expression_to_context(expression: Expression, context: StringBuilder) -> None

convert_key_to_context

convert_key_to_context(key: Key, context: StringBuilder) -> None

write_value_range_start

write_value_range_start(_list_value: Value, context: StringBuilder) -> None

write_value_range_end

write_value_range_end(_list_value: Value, context: StringBuilder) -> None

write_group_start

write_group_start(_group: Group, context: StringBuilder) -> None

write_group_end

write_group_end(_group: Group, context: StringBuilder) -> None

Attributes

• metadata_field_name:

---

eq

eq(key: str, value: ValueType) -> Expression

Check if a key equals a value.

Parameters:

• key (str): The metadata field name to filter on

• value (ValueType): The value to compare against

Returns:

Expression - Expression representing key == value

ne

ne(key: str, value: ValueType) -> Expression

Check if a key does not equal a value.

Parameters:

• key (str): The metadata field name to filter on

• value (ValueType): The value to compare against

Returns:

Expression - Expression representing key != value

gt

gt(key: str, value: Union[int, str, float]) -> Expression

Check if a key is greater than a value.

Parameters:

• key (str): The metadata field name to filter on

• value (Union[int, str, float]): The numeric or string value to compare against

Returns:

Expression - Expression representing key > value

gte

gte(key: str, value: Union[int, str, float]) -> Expression

Check if a key is greater than or equal to a value.

Parameters:

• key (str): The metadata field name to filter on

• value (Union[int, str, float]): The numeric or string value to compare against

Returns:

Expression - Expression representing key >= value

lt

lt(key: str, value: Union[int, str, float]) -> Expression

Check if a key is less than a value.

Parameters:

• key (str): The metadata field name to filter on

• value (Union[int, str, float]): The numeric or string value to compare against

Returns:

Expression - Expression representing key < value

lte

lte(key: str, value: Union[int, str, float]) -> Expression

Check if a key is less than or equal to a value.

Parameters:

• key (str): The metadata field name to filter on

• value (Union[int, str, float]): The numeric or string value to compare against

Returns:

Expression - Expression representing key <= value

like

like(key: str, value: Union[int, str, float]) -> Expression

Check if a key matches a pattern (SQL LIKE).

Parameters:

• key (str): The metadata field name to filter on

• value (Union[int, str, float]): The pattern to match (use % as wildcard)

Returns:

Expression - Expression representing key LIKE value

nlike

nlike(key: str, value: Union[int, str, float]) -> Expression

Check if a key does not match a pattern (SQL NOT LIKE).

Parameters:

• key (str): The metadata field name to filter on

• value (Union[int, str, float]): The pattern to not match (use % as wildcard)

Returns:

Expression - Expression representing key NOT LIKE value

includes

includes(key: str, values: Union[List[int], List[str], List[bool], List[float]]) -> Expression

Check if a key's value is in a list of values (SQL IN operator).

Parameters:

• key (str): The metadata field name to filter on

• values (Union[List[int], List[str], List[bool], List[float]]): List of values to check against

Returns:

Expression - Expression representing key IN values

excludes

excludes(key: str, values: Union[List[int], List[str], List[bool], List[float]]) -> Expression

Check if a key's value is not in a list of values (SQL NOT IN operator).

Parameters:

• key (str): The metadata field name to filter on

• values (Union[List[int], List[str], List[bool], List[float]]): List of values to exclude

Returns:

Expression - Expression representing key NOT IN values

both

both(left: Operand, right: Operand) -> Expression

Combine two expressions with logical AND.

Parameters:

• left (Operand): First expression

• right (Operand): Second expression

Returns:

Expression - Expression representing (left AND right)

either

either(left: Operand, right: Operand) -> Expression

Combine two expressions with logical OR.

Parameters:

• left (Operand): First expression

• right (Operand): Second expression

Returns:

Expression - Expression representing (left OR right)

negate

negate(content: Expression) -> Expression

Negate an expression with logical NOT.

Parameters:

• content (Expression): Expression to negate

Returns:

Expression - Expression representing NOT content

group

group(content: Expression) -> Group

Group an expression with parentheses for precedence control.

Parameters:

• content (Expression): Expression to group

Returns:

Group - Group wrapping the expression

_{This page is: Copyright © 2026 MariaDB. All rights reserved.}