Filter Operators

Filter operators are used in .filter(), condition=, and condition_or=. The syntax follows the pattern attribute__operator=value.

Available Operators

Operator	DynamoDB function	Example
eq	= :val	status__eq="PENDING"
neq	<> :val	status__neq="CANCELLED"
gt	> :val	total__gt=100
gte	>= :val	total__gte=100
lt	< :val	total__lt=500
lte	<= :val	total__lte=500
between	BETWEEN :a AND :b	total__between=[100, 500]
begins_with	begins_with(attr, :val)	name__begins_with="John"
contains	contains(attr, :val)	tags__contains="urgent"
not_contains	NOT contains(attr, :val)	tags__not_contains="old"
exists	attribute_exists(attr)	email__exists=True
not_exists	attribute_not_exists(attr)	email__not_exists=True
in	attr IN (:a, :b, ...)	status__in=["PENDING", "DRAFT"]
not_begins_with	NOT begins_with(attr, :val)	name__not_begins_with="test_"
type	attribute_type(attr, :val)	data__type="M"
size	size(attr) <op> :val	items__size__gt=0

The size Operator

The size operator is special. It applies the DynamoDB size() function to the attribute and then uses another operator for comparison.

# Check if a list is not empty
orders.query(user_id="usr_123").filter(items__size__gt=0)

# Check if a map has between 1 and 10 elements
orders.query(user_id="usr_123").filter(metadata__size__between=[1, 10])

Nested Attributes

You can use dot notation to filter by nested attributes in Maps or specific indexes in Lists.

# Nested Map attribute
results = orders.query(user_id="usr_123").filter(address.city__eq="Lima")

# Specific List index
results = orders.query(user_id="usr_123").filter(items[0].qty__gt=5)

Multiple Filters

Multiple filters in a single .filter() call are automatically combined using AND logic.

results = orders.query(user_id="usr_123").filter(
    status__eq="PENDING",
    total__gte=100,
    created_at__begins_with="2025"
)
# Generates: #status = :v0 AND #total >= :v1 AND #created_at begins_with(:v2)