0
# Expression Building and Computation
1

2
Fundamental expression building blocks for creating scalar values, arrays, structs, and complex computations.
3

4
## Capabilities
5

6
### Literal Values
7

8
Create literal expressions from Python values.
9

10
```python { .api }
11
def literal(value, type=None):
12
    """
13
    Create a literal expression.
14
    
15
    Parameters:
16
    - value: Python value (int, float, str, bool, None, etc.)
17
    - type: optional DataType to cast to
18
    
19
    Returns:
20
    Scalar expression
21
    """
22

23
def null(type=None):
24
    """
25
    Create a null literal.
26
    
27
    Parameters:
28
    - type: optional DataType for the null value
29
    
30
    Returns:
31
    Null scalar expression
32
    """
33
```
34

35
**Usage Examples:**
36
```python
37
import ibis
38

39
# Basic literals
40
num = ibis.literal(42)
41
text = ibis.literal('hello')
42
flag = ibis.literal(True)
43
nothing = ibis.null()
44

45
# Typed null
46
typed_null = ibis.null('string')
47
```
48

49
### Collection Literals
50

51
Create array, map, and struct literal expressions.
52

53
```python { .api }
54
def array(values, type=None):
55
    """
56
    Create an array literal.
57
    
58
    Parameters:
59
    - values: list of values or expressions
60
    - type: optional array DataType
61
    
62
    Returns:
63
    Array expression
64
    """
65

66
def map(keys, values):
67
    """
68
    Create a map literal.
69
    
70
    Parameters:
71
    - keys: list of key values/expressions
72
    - values: list of value values/expressions
73
    
74
    Returns:
75
    Map expression
76
    """
77

78
def struct(mapping):
79
    """
80
    Create a struct literal.
81
    
82
    Parameters:
83
    - mapping: dict of field_name -> value/expression
84
    
85
    Returns:
86
    Struct expression
87
    """
88
```
89

90
**Usage Examples:**
91
```python
92
# Array of numbers
93
arr = ibis.array([1, 2, 3, 4])
94

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

98
# Struct literal
99
person = ibis.struct({
100
    'name': 'Alice',
101
    'age': 30,
102
    'active': True
103
})
104
```
105

106
### Parameters
107

108
Create parameter placeholders for query templates.
109

110
```python { .api }
111
def param(type):
112
    """
113
    Create a parameter placeholder.
114
    
115
    Parameters:
116
    - type: DataType or type string
117
    
118
    Returns:
119
    Parameter scalar expression
120
    """
121
```
122

123
**Usage Example:**
124
```python
125
# Create parameterized query
126
age_param = ibis.param('int64')
127
result = table.filter(table.age > age_param)
128

129
# Execute with parameter value
130
executed = result.execute(params={age_param: 25})
131
```
132

133
### Conditional Expressions
134

135
Build conditional logic with case statements and if-else expressions.
136

137
```python { .api }
138
def case():
139
    """
140
    DEPRECATED: Use ibis.cases() instead.
141
    Create a case expression builder.
142
    
143
    Returns:
144
    Case expression builder with when() and else_() methods
145
    """
146

147
def cases(branch, *branches, else_=None):
148
    """
149
    Create multi-branch if-else expression (SQL CASE statement).
150
    
151
    Parameters:
152
    - branch: tuple of (condition, result) - first required pair
153
    - *branches: additional (condition, result) tuples
154
    - else_: default value if no conditions match (defaults to NULL)
155
    
156
    Returns:
157
    Case expression
158
    """
159

160
def ifelse(condition, true_expr, false_expr):
161
    """
162
    Simple if-else expression.
163
    
164
    Parameters:
165
    - condition: boolean expression
166
    - true_expr: value when condition is true
167
    - false_expr: value when condition is false
168
    
169
    Returns:
170
    Conditional expression
171
    """
172
```
173

174
**Usage Examples:**
175
```python
176
# Case expression
177
grade = (
178
    ibis.case()
179
    .when(table.score >= 90, 'A')
180
    .when(table.score >= 80, 'B') 
181
    .when(table.score >= 70, 'C')
182
    .else_('F')
183
)
184

185
# Cases from tuples
186
grade = ibis.cases(
187
    (table.score >= 90, 'A'),
188
    (table.score >= 80, 'B'),
189
    (table.score >= 70, 'C'),
190
    else_='F'
191
)
192

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

197
### Null Handling
198

199
Functions for working with null values.
200

201
```python { .api }
202
def coalesce(*exprs):
203
    """
204
    Return first non-null expression.
205
    
206
    Parameters:
207
    - *exprs: expressions to check
208
    
209
    Returns:
210
    First non-null expression
211
    """
212

213
def greatest(*exprs):
214
    """
215
    Return greatest value among expressions.
216
    
217
    Parameters:
218
    - *exprs: expressions to compare
219
    
220
    Returns:
221
    Greatest value expression
222
    """
223

224
def least(*exprs):
225
    """
226
    Return least value among expressions.
227
    
228
    Parameters:
229
    - *exprs: expressions to compare
230
    
231
    Returns:
232
    Least value expression
233
    """
234
```
235

236
**Usage Examples:**
237
```python
238
# Coalesce null values
239
result = ibis.coalesce(table.phone, table.mobile, 'N/A')
240

241
# Min/max across columns
242
max_val = ibis.greatest(table.x, table.y, table.z)
243
min_val = ibis.least(table.x, table.y, table.z)
244
```
245

246
### Logical Operations
247

248
Boolean logic operations for combining conditions.
249

250
```python { .api }
251
def and_(*predicates):
252
    """
253
    Logical AND of boolean expressions.
254
    
255
    Parameters:
256
    - *predicates: boolean value expressions
257
    
258
    Returns:
259
    Boolean expression representing AND of all predicates
260
    """
261

262
def or_(*predicates):
263
    """
264
    Logical OR of boolean expressions.
265
    
266
    Parameters:
267
    - *predicates: boolean value expressions
268
    
269
    Returns:
270
    Boolean expression representing OR of all predicates  
271
    """
272
```
273

274
**Usage Examples:**
275
```python
276
# Complex conditions
277
condition = ibis.and_(
278
    table.age >= 18,
279
    table.status == 'active',
280
    table.balance > 0
281
)
282

283
alternative = ibis.or_(
284
    table.vip == True,
285
    table.years_member > 5
286
)
287
```
288

289
### Deferred Expressions
290

291
Use deferred expression builder for complex transformations.
292

293
```python { .api }
294
_ = Deferred()  # Deferred expression builder
295

296
deferred = _  # Alias for the deferred builder (same as _)
297
```
298

299
**Usage Examples:**
300
```python
301
from ibis import _
302

303
# Use in aggregations
304
result = (
305
    table
306
    .group_by(_.department)
307
    .aggregate(avg_salary=_.salary.mean())
308
)
309

310
# Use in selections
311
result = table.select(
312
    _.name,
313
    age_next_year=_.age + 1,
314
    is_senior=_.age > 50
315
)
316
```
317

318
### Random Values
319

320
Generate random values and UUIDs.
321

322
```python { .api }
323
def random():
324
    """
325
    Generate random number between 0 and 1.
326
    
327
    Returns:
328
    Random float expression
329
    """
330

331
def uuid():
332
    """
333
    Generate UUID string.
334
    
335
    Returns:
336
    UUID string expression
337
    """
338
```
339

340
**Usage Examples:**
341
```python
342
# Add random column
343
result = table.mutate(
344
    random_value=ibis.random(),
345
    id=ibis.uuid()
346
)
347
```
348

349
### Mathematical Constants
350

351
Pre-defined mathematical constants.
352

353
```python { .api }
354
e: Scalar  # Mathematical constant e (2.718...)
355
pi: Scalar  # Mathematical constant π (3.14159...)
356
```
357

358
**Usage Example:**
359
```python
360
# Use constants in calculations
361
area = ibis.pi * table.radius ** 2
362
exponential = ibis.e ** table.x
363
```