Temporal Operations

def date(year, month, day):
    """
    Create a date literal.
    
    Parameters:
    - year: int, year value
    - month: int, month value (1-12)
    - day: int, day value (1-31)
    
    Returns:
    Date expression
    """

def today():
    """
    Get current date.
    
    Returns:
    Current date expression
    """

import ibis

# Specific date
birthday = ibis.date(1990, 5, 15)

# Current date
current = ibis.today()

# Use in filters
recent = table.filter(table.created_date >= ibis.today() - ibis.interval(days=7))

def time(hour, minute, second=0, microsecond=0):
    """
    Create a time literal.
    
    Parameters:
    - hour: int, hour value (0-23)
    - minute: int, minute value (0-59)
    - second: int, second value (0-59)
    - microsecond: int, microsecond value
    
    Returns:
    Time expression
    """

# Specific time
meeting_time = ibis.time(14, 30, 0)  # 2:30 PM

# Time with seconds
precise_time = ibis.time(9, 15, 30)

def timestamp(year, month, day, hour=0, minute=0, second=0, microsecond=0, timezone=None):
    """
    Create a timestamp literal.
    
    Parameters:
    - year: int, year value
    - month: int, month value (1-12)
    - day: int, day value (1-31)
    - hour: int, hour value (0-23)
    - minute: int, minute value (0-59)
    - second: int, second value (0-59)
    - microsecond: int, microsecond value
    - timezone: str, timezone name (e.g., 'UTC', 'America/New_York')
    
    Returns:
    Timestamp expression
    """

def now():
    """
    Get current timestamp.
    
    Returns:
    Current timestamp expression
    """

# Specific timestamp
event_time = ibis.timestamp(2023, 12, 25, 10, 30, 0)

# With timezone
utc_time = ibis.timestamp(2023, 12, 25, 10, 30, 0, timezone='UTC')

# Current timestamp
current_time = ibis.now()

def interval(years=0, months=0, weeks=0, days=0, hours=0, minutes=0, seconds=0, microseconds=0):
    """
    Create an interval literal.
    
    Parameters:
    - years: int, number of years
    - months: int, number of months
    - weeks: int, number of weeks
    - days: int, number of days
    - hours: int, number of hours
    - minutes: int, number of minutes
    - seconds: int, number of seconds
    - microseconds: int, number of microseconds
    
    Returns:
    Interval expression
    """

# Various intervals
one_week = ibis.interval(weeks=1)
six_months = ibis.interval(months=6)
two_hours = ibis.interval(hours=2)

# Complex interval
duration = ibis.interval(days=30, hours=12, minutes=45)

# Use in arithmetic
future_date = table.start_date + ibis.interval(days=30)
past_time = ibis.now() - ibis.interval(hours=24)

# Date methods
date_expr.year(): int  # Extract year
date_expr.month(): int  # Extract month (1-12)
date_expr.day(): int  # Extract day of month
date_expr.day_of_year(): int  # Day of year (1-366)
date_expr.quarter(): int  # Quarter (1-4)
date_expr.week_of_year(): int  # Week of year

# Time methods  
time_expr.hour(): int  # Extract hour (0-23)
time_expr.minute(): int  # Extract minute (0-59)
time_expr.second(): int  # Extract second (0-59)
time_expr.microsecond(): int  # Extract microsecond

# Timestamp methods (combines date and time)
timestamp_expr.date(): date  # Extract date part
timestamp_expr.time(): time  # Extract time part

# Extract components
result = table.select(
    table.created_at,
    year=table.created_at.year(),
    month=table.created_at.month(),
    hour=table.created_at.hour()
)

# Filter by time components  
december_data = table.filter(table.date_col.month() == 12)
business_hours = table.filter(
    (table.timestamp_col.hour() >= 9) & 
    (table.timestamp_col.hour() < 17)
)

temporal_expr.strftime(format_string):
    """
    Format temporal value as string.
    
    Parameters:
    - format_string: str, format specification (e.g., '%Y-%m-%d')
    
    Returns:
    String expression with formatted temporal value
    """

# Format dates and times
result = table.select(
    formatted_date=table.date_col.strftime('%Y-%m-%d'),
    formatted_time=table.timestamp_col.strftime('%H:%M:%S'),
    readable=table.timestamp_col.strftime('%B %d, %Y at %I:%M %p')
)

# Addition and subtraction with intervals
temporal_expr + interval_expr: temporal
temporal_expr - interval_expr: temporal

# Difference between temporal values
temporal_expr - temporal_expr: interval

# Comparison operations
temporal_expr == temporal_expr: bool
temporal_expr < temporal_expr: bool
temporal_expr <= temporal_expr: bool
temporal_expr > temporal_expr: bool
temporal_expr >= temporal_expr: bool

# Add/subtract intervals
future_date = table.start_date + ibis.interval(months=3)
past_timestamp = table.event_time - ibis.interval(hours=2)

# Calculate durations
duration = table.end_time - table.start_time

# Time-based filtering
recent = table.filter(
    table.created_at > (ibis.now() - ibis.interval(days=30))
)

timestamp_expr.to_timezone(timezone):
    """
    Convert timestamp to different timezone.
    
    Parameters:
    - timezone: str, target timezone name
    
    Returns:
    Timestamp expression in target timezone
    """

# Convert timezones
utc_time = table.local_timestamp.to_timezone('UTC')
eastern_time = table.utc_timestamp.to_timezone('America/New_York')

temporal_expr.truncate(unit):
    """
    Truncate temporal value to specified unit.
    
    Parameters:
    - unit: str, truncation unit ('year', 'month', 'day', 'hour', 'minute', 'second')
    
    Returns:
    Truncated temporal expression
    """

# Truncate to different units
daily = table.timestamp_col.truncate('day')
hourly = table.timestamp_col.truncate('hour')
monthly = table.date_col.truncate('month')

# Group by truncated time periods
daily_stats = (
    table
    .group_by(day=table.timestamp_col.truncate('day'))
    .aggregate(count=table.count())
)

temporal_expr.delta(other, unit):
    """
    Calculate difference between temporal values.
    
    Parameters:
    - other: temporal expression to subtract
    - unit: str, unit for result ('days', 'hours', 'minutes', 'seconds')
    
    Returns:
    Numeric expression with difference in specified unit
    """

# Calculate age in years
age = table.birth_date.delta(ibis.today(), 'days') / 365.25

# Time differences
hours_elapsed = table.end_time.delta(table.start_time, 'hours')

def watermark(time_col, allowed_delay):
    """
    Create a watermark for streaming event time processing.
    
    Parameters:
    - time_col: str, timestamp column name for generating watermarks
    - allowed_delay: IntervalScalar, allowed lateness for events
    
    Returns:
    Watermark object for streaming processing
    """

# Define watermark for late events
wm = ibis.watermark('event_time', ibis.interval(minutes=5))

# Use in streaming table operations (backend-specific)