Predicates¶

from gault import Field, Query
from gault.predicates import And, Or, Nor, Not, Eq, Gt, Gte, Lt, Lte, Ne, In, Nin

@dataclass(frozen=True)
class Field(AsRef, ConditionInterface, FieldSortInterface, SubfieldInterface,
            NotInterface, ExpressionInterface, InclusionInterface, Assignable)

Field(name: str)

Field("address").field("city")
# Represents "address.city"

Field("age").not_.gte(18)
# {"age": {"$not": {"$gte": 18}}}

Field("score").expr.gt(42)
# Used in: Pipeline().match(Field("score").expr.gt(42))
# Compiles to: {"$expr": {"$gt": ["$score", 42]}}

Field("name").keep()                    # Aliased("name", True)
Field("name").keep(alias="full_name")   # Aliased("full_name", Field("name"))
Field("internal").remove()              # Aliased("internal", "$$REMOVE")

Field("status").assign("active")
# Aliased(Field("status"), "active")
# Used in: Pipeline().set(Field("status").assign("active"))

Field.tmp()
# Creates a Field with a random name like "__64a1b2c3..."
# Useful for intermediate pipeline computations

from gault import Field, Pipeline

f = Field("age")

# Build predicates
predicate = f.gte(18) & f.lt(65)

# Use in pipeline
Pipeline().match(predicate)

# Sort
Pipeline().sort(f.desc())

# Project
Pipeline().project(f.keep(), Field("name").keep())

def Query() -> Predicate

from gault import Query, Field

q = Query()
q = q & Field("age").gte(18)
q = q & Field("status").eq("active")

class Predicate(QueryPredicate)

@dataclass
class Eq(Operator, AsExpression)

Field("status").eq("active")
# Compiles to: {"status": {"$eq": "active"}}

@dataclass
class Ne(Operator, AsExpression)

Field("status").ne("deleted")
# {"status": {"$ne": "deleted"}}

@dataclass
class Gt(Operator, AsExpression)

Field("age").gt(18)
# {"age": {"$gt": 18}}

@dataclass
class Gte(Operator, AsExpression)

Field("age").gte(18)
# {"age": {"$gte": 18}}

@dataclass
class Lt(Operator, AsExpression)

Field("age").lt(65)
# {"age": {"$lt": 65}}

@dataclass
class Lte(Operator, AsExpression)

Field("score").lte(100)
# {"score": {"$lte": 100}}

@dataclass
class In(Operator, AsExpression)

Field("status").in_("active", "pending")
# {"status": {"$in": ["active", "pending"]}}

Field("status").in_(["active", "pending"])
# {"status": {"$in": ["active", "pending"]}}

@dataclass
class Nin(Operator, AsExpression)

Field("status").nin("deleted", "archived")
# {"status": {"$nin": ["deleted", "archived"]}}

@dataclass
class And(Predicate, ExpressionOperator)

And(Field("age").gte(18), Field("status").eq("active"))
# {"$and": [{"age": {"$gte": 18}}, {"status": {"$eq": "active"}}]}

pred = Field("a").eq(1) & Field("b").eq(2) & Field("c").eq(3)
# And([a==1, b==2, c==3]) -- flat, not nested

@dataclass
class Or(Predicate, ExpressionOperator)

Or(Field("status").eq("active"), Field("status").eq("pending"))
# {"$or": [{"status": {"$eq": "active"}}, {"status": {"$eq": "pending"}}]}

pred = Field("a").eq(1) | Field("b").eq(2) | Field("c").eq(3)
# Or([a==1, b==2, c==3])

~Or(Field("a").eq(1), Field("b").eq(2))
# Nor([a==1, b==2])

@dataclass
class Nor(Predicate)

Nor(Field("status").eq("deleted"), Field("age").lt(18))
# {"$nor": [{"status": {"$eq": "deleted"}}, {"age": {"$lt": 18}}]}

~Nor(Field("a").eq(1), Field("b").eq(2))
# Or([a==1, b==2])

@dataclass
class Not(Operator)

# Via not_ property
Field("age").not_.gte(18)
# {"age": {"$not": {"$gte": 18}}}

# Direct instantiation
from gault.predicates import Not, Gte
Not(Gte(18))
# {"$not": {"$gte": 18}}

~Gte(18)   # Not(Gte(18))

@dataclass
class All(Operator)

Field("tags").all("python", "mongodb")
# {"tags": {"$all": ["python", "mongodb"]}}

@dataclass
class ElemMatch(Operator)

Field("scores").elem_match(Field("value").gte(80), Field("type").eq("exam"))
# {"scores": {"$elemMatch": {"value": {"$gte": 80}, "type": {"$eq": "exam"}}}}

Field("results").all(
    ElemMatch(Gte(80)),
    ElemMatch(Lt(90)),
)

@dataclass
class Size(Operator, AsExpression)

Field("tags").size(3)
# {"tags": {"$size": 3}}

@dataclass
class Regex(Operator, AsExpression)

Field("name").regex("^Alice", options="i")
# {"name": {"$regex": "^Alice", "$options": "i"}}

@dataclass
class Exists(Operator)

Field("email").exists(True)
# {"email": {"$exists": true}}

Field("deleted_at").exists(False)
# {"deleted_at": {"$exists": false}}

@dataclass
class Type(Operator)

Field("value").type("string", "int")
# {"value": {"$type": ["string", "int"]}}

@dataclass
class Expr(Operator, ExpressionOperator)

from gault.predicates import Expr
from gault.expressions import Gt

Expr(Gt("$spent", "$budget"))
# {"$expr": {"$gt": ["$spent", "$budget"]}}

@dataclass
class Raw(Predicate)

from gault.predicates import Raw

Raw({"$text": {"$search": "coffee shop"}})
# {"$text": {"$search": "coffee shop"}}

# AND
p = Field("age").gte(18) & Field("status").eq("active")

# OR
p = Field("role").eq("admin") | Field("role").eq("moderator")

# Complex
p = (Field("age").gte(18) & Field("status").eq("active")) | Field("role").eq("admin")

# Simple equality
Field("name").eq("Alice")
# {"name": {"$eq": "Alice"}}

# Range query
Field("age").gte(18) & Field("age").lt(65)
# {"$and": [{"age": {"$gte": 18}}, {"age": {"$lt": 65}}]}

# OR query
Field("status").in_("active", "pending")
# {"status": {"$in": ["active", "pending"]}}

# NOT with regex
Field("name").not_.regex("^test", options="i")
# {"name": {"$not": {"$regex": "^test", "$options": "i"}}}

# Nested field
Field("address").field("city").eq("Paris")
# {"address.city": {"$eq": "Paris"}}

# Array elem_match
Field("scores").elem_match(Gte(80), Lt(100))
# {"scores": {"$elemMatch": {"$gte": 80, "$lt": 100}}}