Expression Building and Computation

def literal(value, type=None):
    """
    Create a literal expression.
    
    Parameters:
    - value: Python value (int, float, str, bool, None, etc.)
    - type: optional DataType to cast to
    
    Returns:
    Scalar expression
    """

def null(type=None):
    """
    Create a null literal.
    
    Parameters:
    - type: optional DataType for the null value
    
    Returns:
    Null scalar expression
    """

import ibis

# Basic literals
num = ibis.literal(42)
text = ibis.literal('hello')
flag = ibis.literal(True)
nothing = ibis.null()

# Typed null
typed_null = ibis.null('string')

def array(values, type=None):
    """
    Create an array literal.
    
    Parameters:
    - values: list of values or expressions
    - type: optional array DataType
    
    Returns:
    Array expression
    """

def map(keys, values):
    """
    Create a map literal.
    
    Parameters:
    - keys: list of key values/expressions
    - values: list of value values/expressions
    
    Returns:
    Map expression
    """

def struct(mapping):
    """
    Create a struct literal.
    
    Parameters:
    - mapping: dict of field_name -> value/expression
    
    Returns:
    Struct expression
    """

# Array of numbers
arr = ibis.array([1, 2, 3, 4])

# Map literal
mapping = ibis.map(['a', 'b'], [1, 2])

# Struct literal
person = ibis.struct({
    'name': 'Alice',
    'age': 30,
    'active': True
})

def param(type):
    """
    Create a parameter placeholder.
    
    Parameters:
    - type: DataType or type string
    
    Returns:
    Parameter scalar expression
    """

# Create parameterized query
age_param = ibis.param('int64')
result = table.filter(table.age > age_param)

# Execute with parameter value
executed = result.execute(params={age_param: 25})

def case():
    """
    DEPRECATED: Use ibis.cases() instead.
    Create a case expression builder.
    
    Returns:
    Case expression builder with when() and else_() methods
    """

def cases(branch, *branches, else_=None):
    """
    Create multi-branch if-else expression (SQL CASE statement).
    
    Parameters:
    - branch: tuple of (condition, result) - first required pair
    - *branches: additional (condition, result) tuples
    - else_: default value if no conditions match (defaults to NULL)
    
    Returns:
    Case expression
    """

def ifelse(condition, true_expr, false_expr):
    """
    Simple if-else expression.
    
    Parameters:
    - condition: boolean expression
    - true_expr: value when condition is true
    - false_expr: value when condition is false
    
    Returns:
    Conditional expression
    """

# Case expression
grade = (
    ibis.case()
    .when(table.score >= 90, 'A')
    .when(table.score >= 80, 'B') 
    .when(table.score >= 70, 'C')
    .else_('F')
)

# Cases from tuples
grade = ibis.cases(
    (table.score >= 90, 'A'),
    (table.score >= 80, 'B'),
    (table.score >= 70, 'C'),
    else_='F'
)

# Simple if-else
status = ibis.ifelse(table.age >= 18, 'adult', 'minor')

def coalesce(*exprs):
    """
    Return first non-null expression.
    
    Parameters:
    - *exprs: expressions to check
    
    Returns:
    First non-null expression
    """

def greatest(*exprs):
    """
    Return greatest value among expressions.
    
    Parameters:
    - *exprs: expressions to compare
    
    Returns:
    Greatest value expression
    """

def least(*exprs):
    """
    Return least value among expressions.
    
    Parameters:
    - *exprs: expressions to compare
    
    Returns:
    Least value expression
    """

# Coalesce null values
result = ibis.coalesce(table.phone, table.mobile, 'N/A')

# Min/max across columns
max_val = ibis.greatest(table.x, table.y, table.z)
min_val = ibis.least(table.x, table.y, table.z)

def and_(*predicates):
    """
    Logical AND of boolean expressions.
    
    Parameters:
    - *predicates: boolean value expressions
    
    Returns:
    Boolean expression representing AND of all predicates
    """

def or_(*predicates):
    """
    Logical OR of boolean expressions.
    
    Parameters:
    - *predicates: boolean value expressions
    
    Returns:
    Boolean expression representing OR of all predicates  
    """

# Complex conditions
condition = ibis.and_(
    table.age >= 18,
    table.status == 'active',
    table.balance > 0
)

alternative = ibis.or_(
    table.vip == True,
    table.years_member > 5
)

_ = Deferred()  # Deferred expression builder

deferred = _  # Alias for the deferred builder (same as _)

from ibis import _

# Use in aggregations
result = (
    table
    .group_by(_.department)
    .aggregate(avg_salary=_.salary.mean())
)

# Use in selections
result = table.select(
    _.name,
    age_next_year=_.age + 1,
    is_senior=_.age > 50
)

def random():
    """
    Generate random number between 0 and 1.
    
    Returns:
    Random float expression
    """

def uuid():
    """
    Generate UUID string.
    
    Returns:
    UUID string expression
    """

# Add random column
result = table.mutate(
    random_value=ibis.random(),
    id=ibis.uuid()
)

e: Scalar  # Mathematical constant e (2.718...)
pi: Scalar  # Mathematical constant π (3.14159...)

# Use constants in calculations
area = ibis.pi * table.radius ** 2
exponential = ibis.e ** table.x