0
# Temporal Operations
1

2
Extensive date, time, and timestamp functionality including construction, arithmetic, formatting, and timezone handling.
3

4
## Capabilities
5

6
### Date Construction
7

8
Create date literals and expressions.
9

10
```python { .api }
11
def date(year, month, day):
12
    """
13
    Create a date literal.
14
    
15
    Parameters:
16
    - year: int, year value
17
    - month: int, month value (1-12)
18
    - day: int, day value (1-31)
19
    
20
    Returns:
21
    Date expression
22
    """
23

24
def today():
25
    """
26
    Get current date.
27
    
28
    Returns:
29
    Current date expression
30
    """
31
```
32

33
**Usage Examples:**
34
```python
35
import ibis
36

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

40
# Current date
41
current = ibis.today()
42

43
# Use in filters
44
recent = table.filter(table.created_date >= ibis.today() - ibis.interval(days=7))
45
```
46

47
### Time Construction
48

49
Create time literals and expressions.
50

51
```python { .api }
52
def time(hour, minute, second=0, microsecond=0):
53
    """
54
    Create a time literal.
55
    
56
    Parameters:
57
    - hour: int, hour value (0-23)
58
    - minute: int, minute value (0-59)
59
    - second: int, second value (0-59)
60
    - microsecond: int, microsecond value
61
    
62
    Returns:
63
    Time expression
64
    """
65
```
66

67
**Usage Examples:**
68
```python
69
# Specific time
70
meeting_time = ibis.time(14, 30, 0)  # 2:30 PM
71

72
# Time with seconds
73
precise_time = ibis.time(9, 15, 30)
74
```
75

76
### Timestamp Construction
77

78
Create timestamp literals with timezone support.
79

80
```python { .api }
81
def timestamp(year, month, day, hour=0, minute=0, second=0, microsecond=0, timezone=None):
82
    """
83
    Create a timestamp literal.
84
    
85
    Parameters:
86
    - year: int, year value
87
    - month: int, month value (1-12)
88
    - day: int, day value (1-31)
89
    - hour: int, hour value (0-23)
90
    - minute: int, minute value (0-59)
91
    - second: int, second value (0-59)
92
    - microsecond: int, microsecond value
93
    - timezone: str, timezone name (e.g., 'UTC', 'America/New_York')
94
    
95
    Returns:
96
    Timestamp expression
97
    """
98

99
def now():
100
    """
101
    Get current timestamp.
102
    
103
    Returns:
104
    Current timestamp expression
105
    """
106
```
107

108
**Usage Examples:**
109
```python
110
# Specific timestamp
111
event_time = ibis.timestamp(2023, 12, 25, 10, 30, 0)
112

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

116
# Current timestamp
117
current_time = ibis.now()
118
```
119

120
### Interval Construction
121

122
Create interval expressions for date/time arithmetic.
123

124
```python { .api }
125
def interval(years=0, months=0, weeks=0, days=0, hours=0, minutes=0, seconds=0, microseconds=0):
126
    """
127
    Create an interval literal.
128
    
129
    Parameters:
130
    - years: int, number of years
131
    - months: int, number of months
132
    - weeks: int, number of weeks
133
    - days: int, number of days
134
    - hours: int, number of hours
135
    - minutes: int, number of minutes
136
    - seconds: int, number of seconds
137
    - microseconds: int, number of microseconds
138
    
139
    Returns:
140
    Interval expression
141
    """
142
```
143

144
**Usage Examples:**
145
```python
146
# Various intervals
147
one_week = ibis.interval(weeks=1)
148
six_months = ibis.interval(months=6)
149
two_hours = ibis.interval(hours=2)
150

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

154
# Use in arithmetic
155
future_date = table.start_date + ibis.interval(days=30)
156
past_time = ibis.now() - ibis.interval(hours=24)
157
```
158

159
### Date/Time Extraction
160

161
Extract components from temporal values.
162

163
**Date/Time Component Methods:**
164
```python { .api }
165
# Date methods
166
date_expr.year(): int  # Extract year
167
date_expr.month(): int  # Extract month (1-12)
168
date_expr.day(): int  # Extract day of month
169
date_expr.day_of_year(): int  # Day of year (1-366)
170
date_expr.quarter(): int  # Quarter (1-4)
171
date_expr.week_of_year(): int  # Week of year
172

173
# Time methods  
174
time_expr.hour(): int  # Extract hour (0-23)
175
time_expr.minute(): int  # Extract minute (0-59)
176
time_expr.second(): int  # Extract second (0-59)
177
time_expr.microsecond(): int  # Extract microsecond
178

179
# Timestamp methods (combines date and time)
180
timestamp_expr.date(): date  # Extract date part
181
timestamp_expr.time(): time  # Extract time part
182
```
183

184
**Usage Examples:**
185
```python
186
# Extract components
187
result = table.select(
188
    table.created_at,
189
    year=table.created_at.year(),
190
    month=table.created_at.month(),
191
    hour=table.created_at.hour()
192
)
193

194
# Filter by time components  
195
december_data = table.filter(table.date_col.month() == 12)
196
business_hours = table.filter(
197
    (table.timestamp_col.hour() >= 9) & 
198
    (table.timestamp_col.hour() < 17)
199
)
200
```
201

202
### Date/Time Formatting
203

204
Format temporal values as strings.
205

206
```python { .api }
207
temporal_expr.strftime(format_string):
208
    """
209
    Format temporal value as string.
210
    
211
    Parameters:
212
    - format_string: str, format specification (e.g., '%Y-%m-%d')
213
    
214
    Returns:
215
    String expression with formatted temporal value
216
    """
217
```
218

219
**Usage Examples:**
220
```python
221
# Format dates and times
222
result = table.select(
223
    formatted_date=table.date_col.strftime('%Y-%m-%d'),
224
    formatted_time=table.timestamp_col.strftime('%H:%M:%S'),
225
    readable=table.timestamp_col.strftime('%B %d, %Y at %I:%M %p')
226
)
227
```
228

229
### Date/Time Arithmetic
230

231
Perform arithmetic operations on temporal values.
232

233
**Arithmetic Operations:**
234
```python { .api }
235
# Addition and subtraction with intervals
236
temporal_expr + interval_expr: temporal
237
temporal_expr - interval_expr: temporal
238

239
# Difference between temporal values
240
temporal_expr - temporal_expr: interval
241

242
# Comparison operations
243
temporal_expr == temporal_expr: bool
244
temporal_expr < temporal_expr: bool
245
temporal_expr <= temporal_expr: bool
246
temporal_expr > temporal_expr: bool
247
temporal_expr >= temporal_expr: bool
248
```
249

250
**Usage Examples:**
251
```python
252
# Add/subtract intervals
253
future_date = table.start_date + ibis.interval(months=3)
254
past_timestamp = table.event_time - ibis.interval(hours=2)
255

256
# Calculate durations
257
duration = table.end_time - table.start_time
258

259
# Time-based filtering
260
recent = table.filter(
261
    table.created_at > (ibis.now() - ibis.interval(days=30))
262
)
263
```
264

265
### Timezone Operations
266

267
Handle timezone conversions and operations.
268

269
```python { .api }
270
timestamp_expr.to_timezone(timezone):
271
    """
272
    Convert timestamp to different timezone.
273
    
274
    Parameters:
275
    - timezone: str, target timezone name
276
    
277
    Returns:
278
    Timestamp expression in target timezone
279
    """
280
```
281

282
**Usage Examples:**
283
```python
284
# Convert timezones
285
utc_time = table.local_timestamp.to_timezone('UTC')
286
eastern_time = table.utc_timestamp.to_timezone('America/New_York')
287
```
288

289
### Temporal Truncation
290

291
Truncate temporal values to specific units.
292

293
```python { .api }
294
temporal_expr.truncate(unit):
295
    """
296
    Truncate temporal value to specified unit.
297
    
298
    Parameters:
299
    - unit: str, truncation unit ('year', 'month', 'day', 'hour', 'minute', 'second')
300
    
301
    Returns:
302
    Truncated temporal expression
303
    """
304
```
305

306
**Usage Examples:**
307
```python
308
# Truncate to different units
309
daily = table.timestamp_col.truncate('day')
310
hourly = table.timestamp_col.truncate('hour')
311
monthly = table.date_col.truncate('month')
312

313
# Group by truncated time periods
314
daily_stats = (
315
    table
316
    .group_by(day=table.timestamp_col.truncate('day'))
317
    .aggregate(count=table.count())
318
)
319
```
320

321
### Delta Operations
322

323
Calculate differences between temporal values.
324

325
```python { .api }
326
temporal_expr.delta(other, unit):
327
    """
328
    Calculate difference between temporal values.
329
    
330
    Parameters:
331
    - other: temporal expression to subtract
332
    - unit: str, unit for result ('days', 'hours', 'minutes', 'seconds')
333
    
334
    Returns:
335
    Numeric expression with difference in specified unit
336
    """
337
```
338

339
**Usage Examples:**
340
```python
341
# Calculate age in years
342
age = table.birth_date.delta(ibis.today(), 'days') / 365.25
343

344
# Time differences
345
hours_elapsed = table.end_time.delta(table.start_time, 'hours')
346
```
347

348
### Streaming Watermarks
349

350
Create watermark objects for event time processing in streaming applications.
351

352
```python { .api }
353
def watermark(time_col, allowed_delay):
354
    """
355
    Create a watermark for streaming event time processing.
356
    
357
    Parameters:
358
    - time_col: str, timestamp column name for generating watermarks
359
    - allowed_delay: IntervalScalar, allowed lateness for events
360
    
361
    Returns:
362
    Watermark object for streaming processing
363
    """
364
```
365

366
**Usage Example:**
367
```python
368
# Define watermark for late events
369
wm = ibis.watermark('event_time', ibis.interval(minutes=5))
370

371
# Use in streaming table operations (backend-specific)
372
```