Expressions¶

from gault.expressions import Add, Multiply, Cond, ToUpper

@dataclass(frozen=True)
class Var(AsRef, AsAlias, ExpressionsInterface, FieldSortInterface, SubfieldInterface, ...)

from gault import Var

root = Var("ROOT")          # compiles to "$$ROOT"
this = Var("this")          # compiles to "$$this"
custom = Var("myVar")       # compiles to "$$myVar"

Var("this").expr.gt(10)     # {"$gt": ["$$this", 10]}

class Add(ExpressionOperator)

Add("$price", "$tax")
# Compiles to: {"$add": ["$price", "$tax"]}

Add("$a", "$b", "$c")
# Compiles to: {"$add": ["$a", "$b", "$c"]}

@dataclass
class Subtract(ExpressionOperator)

Subtract("$total", "$discount")
# {"$subtract": ["$total", "$discount"]}

class Multiply(ExpressionOperator)

Multiply("$price", "$quantity")
# {"$multiply": ["$price", "$quantity"]}

@dataclass
class Divide(ExpressionOperator)

Divide("$total", "$count")
# {"$divide": ["$total", "$count"]}

@dataclass
class Mod(ExpressionOperator)

Mod("$hours", 24)
# {"$mod": ["$hours", 24]}

@dataclass
class Abs(ExpressionOperator)

Abs("$delta")
# {"$abs": "$delta"}

@dataclass
class Ceil(ExpressionOperator)

Ceil("$price")
# {"$ceil": "$price"}

@dataclass
class Floor(ExpressionOperator)

Floor("$price")
# {"$floor": "$price"}

@dataclass
class Round(ExpressionOperator)

Round("$score", 2)
# {"$round": ["$score", 2]}

@dataclass
class Trunc(ExpressionOperator)

@dataclass
class Pow(ExpressionOperator)

Pow("$base", 2)
# {"$pow": ["$base", 2]}

@dataclass
class Sqrt(ExpressionOperator)

@dataclass
class Exp(ExpressionOperator)

@dataclass
class Ln(ExpressionOperator)   # Natural logarithm
class Log(ExpressionOperator)  # Log with specified base
class Log10(ExpressionOperator) # Base-10 logarithm

@dataclass
class Eq(ExpressionOperator)

Eq("$status", "active")
# {"$eq": ["$status", "active"]}

@dataclass
class Ne(ExpressionOperator)

Ne("$status", "deleted")
# {"$ne": ["$status", "deleted"]}

@dataclass
class Gt(ExpressionOperator)   # Greater than
class Gte(ExpressionOperator)  # Greater than or equal
class Lt(ExpressionOperator)   # Less than
class Lte(ExpressionOperator)  # Less than or equal

Gt("$age", 18)
# {"$gt": ["$age", 18]}

Lte("$score", 100)
# {"$lte": ["$score", 100]}

@dataclass
class Cmp(ExpressionOperator)

Cmp("$a", "$b")
# {"$cmp": ["$a", "$b"]}

@dataclass
class In(ExpressionOperator)

In("$status", ["active", "pending"])
# {"$in": ["$status", ["active", "pending"]]}

class Concat(ExpressionOperator)

Concat("$firstName", " ", "$lastName")
# {"$concat": ["$firstName", " ", "$lastName"]}

@dataclass
class SubStrBytes(ExpressionOperator)  # By UTF-8 bytes
class SubStrCP(ExpressionOperator)     # By code points

SubStrBytes("$name", 0, 5)
# {"$substrBytes": ["$name", 0, 5]}

@dataclass
class ToLower(ExpressionOperator)

ToLower("$name")
# {"$toLower": "$name"}

@dataclass
class ToUpper(ExpressionOperator)

ToUpper("$name")
# {"$toUpper": "$name"}

@dataclass
class Trim(ExpressionOperator)   # Both ends
class Ltrim(ExpressionOperator)  # Beginning
class Rtrim(ExpressionOperator)  # End

Trim("$name", chars=" ")
# {"$trim": {"input": "$name", "chars": " "}}

@dataclass
class Split(ExpressionOperator)

@dataclass
class StrLenBytes(ExpressionOperator)  # UTF-8 byte length
class StrLenCP(ExpressionOperator)     # Code point length

@dataclass
class StrCaseCmp(ExpressionOperator)

@dataclass
class IndexOfBytes(ExpressionOperator)
class IndexOfCP(ExpressionOperator)

@dataclass
class ReplaceOne(ExpressionOperator)  # First occurrence
class ReplaceAll(ExpressionOperator)  # All occurrences

@dataclass
class RegexFind(ExpressionOperator)
class RegexFindAll(ExpressionOperator)
class RegexMatch(ExpressionOperator)

@dataclass
class ArrayElemAt(ExpressionOperator)

ArrayElemAt("$tags", index=0)
# {"$arrayElemAt": ["$tags", 0]}

class ConcatArrays(ExpressionOperator)

ConcatArrays("$arr1", "$arr2")
# {"$concatArrays": ["$arr1", "$arr2"]}

@dataclass
class Filter(ExpressionOperator)

Filter("$scores", cond=Gt(Var("this"), 50))
# {"$filter": {"input": "$scores", "cond": {"$gt": ["$$this", 50]}}}

# With callable
Filter("$scores", cond=lambda this, ctx: this.gt(50))

@dataclass
class Map(ExpressionOperator)

Map("$items", into=Multiply(Var("this"), 2))
# {"$map": {"input": "$items", "in": {"$multiply": ["$$this", 2]}}}

@dataclass
class Reduce(ExpressionOperator)

Reduce("$numbers", initial_value=0, into=Add(Var("value"), Var("this")))

@dataclass
class Size(ExpressionOperator)

Size("$tags")
# {"$size": "$tags"}

@dataclass
class Slice(ExpressionOperator)

@dataclass
class IndexOfArray(ExpressionOperator)

@dataclass
class ReverseArray(ExpressionOperator)

@dataclass
class SortArray(ExpressionOperator)

@dataclass
class Zip(ExpressionOperator)

@dataclass
class ArrayToObject(ExpressionOperator)  # Array -> document
class ObjectToArray(ExpressionOperator)  # Document -> array

class SetDifference(ExpressionOperator)     # Elements in first but not second
class SetEquals(ExpressionOperator)         # Same distinct elements (2+ arrays)
class SetIntersection(ExpressionOperator)   # Common elements (2+ arrays)
class SetIsSubset(ExpressionOperator)       # First is subset of second
class SetUnion(ExpressionOperator)          # Unique elements from all (2+ arrays)
class AllElementsTrue(ExpressionOperator)   # All elements are true
class AnyElementsTrue(ExpressionOperator)   # Any element is true

@dataclass
class DateAdd(ExpressionOperator)
class DateSubtract(ExpressionOperator)

DateAdd("$createdAt", unit="day", amount=30)
# {"$dateAdd": {"startDate": "$createdAt", "unit": "day", "amount": 30}}

@dataclass
class DateDiff(ExpressionOperator)

@dataclass
class DateFromParts(ExpressionOperator)

@dataclass
class DateFromString(ExpressionOperator)

@dataclass
class DateToParts(ExpressionOperator)    # Date -> parts document
class DateToString(ExpressionOperator)   # Date -> formatted string
class DateTrunc(ExpressionOperator)      # Truncate date to unit

@dataclass
class Type(ExpressionOperator)

Type("$value")
# {"$type": "$value"}

ToInt("$stringAge")
# {"$toInt": "$stringAge"}

@dataclass
class IsArray(ExpressionOperator)
class IsNumber(ExpressionOperator)

@dataclass
class BinarySize(ExpressionOperator)  # Size of string/binary in bytes
class BsonSize(ExpressionOperator)    # BSON size of document in bytes

@dataclass
class Cond(ExpressionOperator)

Cond(when=Gte("$score", 70), then="pass", otherwise="fail")
# {"$cond": {"if": {"$gte": ["$score", 70]}, "then": "pass", "else": "fail"}}

class IfNull(ExpressionOperator)

IfNull("$nickname", "$name", "Anonymous")
# {"$ifNull": ["$nickname", "$name", "Anonymous"]}

@dataclass
class Switch(ExpressionOperator)

Switch(
    branches=[
        (Gte("$score", 90), "A"),
        (Gte("$score", 80), "B"),
        (Gte("$score", 70), "C"),
    ],
    default="F",
)
# {"$switch": {"branches": [{"case": {"$gte": ["$score", 90]}, "then": "A"}, ...], "default": "F"}}

class And(ExpressionOperator)   # All true
class Or(ExpressionOperator)    # Any true
class Not(ExpressionOperator)   # Boolean negation

expr1 = Gt("$age", 18)
expr2 = Lt("$age", 65)
combined = expr1 & expr2    # And(expr1, expr2)
negated = ~expr1            # Not(expr1)
either = expr1 | expr2      # Or(expr1, expr2)

from gault import Field, Var

# Arithmetic
Field("price").expr.add("$tax")            # Add("$price", "$tax")
Field("price").expr.multiply("$qty")       # Multiply("$price", "$qty")
Field("price").expr.subtract("$discount")  # Subtract("$price", "$discount")
Field("score").expr.abs()                  # Abs("$score")
Field("score").expr.ceil()                 # Ceil("$score")
Field("score").expr.floor()                # Floor("$score")
Field("score").expr.round(2)               # Round("$score", 2)

# Comparison
Field("age").expr.gt(18)                   # Gt("$age", 18)
Field("age").expr.eq(21)                   # Eq("$age", 21)

# String
Field("name").expr.to_lower()              # ToLower("$name")
Field("name").expr.to_upper()              # ToUpper("$name")
Field("name").expr.concat(" ", "$suffix")  # Concat("$name", " ", "$suffix")
Field("name").expr.trim(" ")               # Trim("$name", chars=" ")

# Array
Field("tags").expr.size()                  # Size("$tags")
Field("items").expr.filter(cond=...)       # Filter("$items", cond=...)
Field("items").expr.map(into=...)          # Map("$items", into=...)

# Date
Field("created").expr.year()               # Year("$created")
Field("created").expr.month()              # Month("$created")
Field("created").expr.day_of_week()        # DayOfWeek("$created")

# Type
Field("value").expr.type()                 # Type("$value")
Field("str_num").expr.to_int()             # ToInt("$str_num")