0
# Configuration
1

2
Global and backend-specific configuration system for controlling behavior, output formatting, and performance optimizations.
3

4
## Capabilities
5

6
### Configuration Access
7

8
Access and modify Ibis configuration options.
9

10
```python { .api }
11
ibis.options: OptionsManager
12
    """Global options manager for Ibis configuration."""
13

14
ibis.options.get(key): Any
15
    """Get configuration value."""
16

17
ibis.options.set(key, value): None
18
    """Set configuration value."""
19

20
ibis.options.reset(): None
21
    """Reset all options to defaults."""
22
```
23

24
**Usage Examples:**
25
```python
26
import ibis
27

28
# Access options
29
print(ibis.options.sql.default_limit)
30

31
# Set options
32
ibis.options.sql.default_limit = 1000
33
ibis.options.interactive.mode = True
34

35
# Reset to defaults
36
ibis.options.reset()
37
```
38

39
### SQL Configuration
40

41
Control SQL compilation and execution behavior.
42

43
```python { .api }
44
ibis.options.sql.default_limit: int
45
    """Default row limit for query results (default: 10000)."""
46

47
ibis.options.sql.default_backend: str
48
    """Default backend name for new operations."""
49
```
50

51
**Usage Examples:**
52
```python
53
# Set default row limit
54
ibis.options.sql.default_limit = 5000
55

56
# All queries will be limited to 5000 rows by default
57
result = table.select('*')  # Automatically adds LIMIT 5000
58

59
# Override for specific query
60
unlimited = table.select('*').limit(None)  # No limit
61

62
# Set default backend
63
ibis.options.sql.default_backend = 'duckdb'
64
```
65

66
### Interactive Mode Configuration
67

68
Control behavior in interactive environments like Jupyter.
69

70
```python { .api }
71
ibis.options.interactive.mode: bool
72
    """Enable interactive mode (default: True in Jupyter, False otherwise)."""
73

74
ibis.options.interactive.max_rows: int
75
    """Maximum rows to display in interactive repr (default: 10)."""
76

77
ibis.options.interactive.max_columns: int  
78
    """Maximum columns to display in interactive repr (default: None)."""
79

80
ibis.options.interactive.max_length: int
81
    """Maximum string length to display (default: 100)."""
82

83
ibis.options.interactive.max_depth: int
84
    """Maximum nesting depth for nested data (default: 1)."""
85
```
86

87
**Usage Examples:**
88
```python
89
# Configure interactive display
90
ibis.options.interactive.mode = True
91
ibis.options.interactive.max_rows = 20
92
ibis.options.interactive.max_columns = 8
93
ibis.options.interactive.max_length = 50
94

95
# Now table expressions will display nicely in Jupyter
96
table  # Shows formatted preview with configured limits
97
```
98

99
### Representation Configuration
100

101
Control how expressions and results are displayed.
102

103
```python { .api }
104
ibis.options.repr.interactive.show_types: bool
105
    """Show column types in table repr (default: True)."""
106

107
ibis.options.repr.interactive.table_columns: int
108
    """Number of table columns to show (default: None for all)."""
109

110
ibis.options.repr.query_text_length: int
111
    """Maximum query text length in repr (default: 200)."""
112
```
113

114
**Usage Examples:**
115
```python
116
# Configure table representation
117
ibis.options.repr.interactive.show_types = False  # Hide column types
118
ibis.options.repr.interactive.table_columns = 5   # Show max 5 columns
119
ibis.options.repr.query_text_length = 100        # Truncate long queries
120

121
# Display configuration affects how tables look
122
print(table)  # Uses configured representation settings
123
```
124

125
### Backend-Specific Configuration
126

127
Configure behavior for specific backends.
128

129
**Usage Examples:**
130
```python
131
# DuckDB-specific options
132
ibis.options.duckdb.temp_directory = '/tmp/duckdb'
133
ibis.options.duckdb.memory_limit = '4GB'
134

135
# BigQuery-specific options  
136
ibis.options.bigquery.project_id = 'my-default-project'
137
ibis.options.bigquery.dataset_id = 'analytics'
138

139
# PostgreSQL connection pooling
140
ibis.options.postgres.pool_size = 10
141
ibis.options.postgres.max_overflow = 20
142
```
143

144
### Context Managers
145

146
Temporarily change configuration using context managers.
147

148
```python { .api }
149
ibis.options.with_config(**kwargs): ContextManager
150
    """Temporarily set configuration options."""
151
```
152

153
**Usage Examples:**
154
```python
155
# Temporarily change settings
156
with ibis.options.with_config(sql_default_limit=100):
157
    # All queries in this block use limit of 100
158
    result1 = table.select('*')
159
    result2 = other_table.select('*')
160

161
# Outside the block, original limit is restored
162
result3 = table.select('*')  # Uses original default limit
163

164
# Multiple options at once
165
with ibis.options.with_config(
166
    interactive_mode=False,
167
    sql_default_limit=50,
168
    repr_show_types=False
169
):
170
    # Custom behavior for this block
171
    print(table)
172
```
173

174
### Configuration Validation
175

176
Validate configuration values.
177

178
**Usage Examples:**
179
```python
180
# Invalid configuration raises errors
181
try:
182
    ibis.options.sql.default_limit = -1  # Invalid negative limit
183
except ValueError as e:
184
    print(f"Configuration error: {e}")
185

186
try:
187
    ibis.options.interactive.max_rows = "invalid"  # Wrong type
188
except TypeError as e:
189
    print(f"Type error: {e}")
190
```
191

192
### Configuration Persistence
193

194
Save and load configuration settings.
195

196
**Usage Examples:**
197
```python
198
# Get current configuration as dict
199
current_config = ibis.options.to_dict()
200

201
# Save to file (conceptual example)
202
import json
203
with open('ibis_config.json', 'w') as f:
204
    json.dump(current_config, f)
205

206
# Load configuration (conceptual example)
207
with open('ibis_config.json', 'r') as f:
208
    saved_config = json.load(f)
209

210
# Apply saved configuration
211
for key, value in saved_config.items():
212
    ibis.options.set(key, value)
213
```
214

215
### Performance Configuration
216

217
Options that affect query execution performance.
218

219
```python { .api }
220
ibis.options.compute.default_cache: bool
221
    """Enable result caching by default (default: False)."""
222

223
ibis.options.compute.chunk_size: int  
224
    """Default chunk size for streaming operations."""
225

226
ibis.options.compute.parallel: bool
227
    """Enable parallel execution where supported."""
228
```
229

230
**Usage Examples:**
231
```python
232
# Performance tuning
233
ibis.options.compute.default_cache = True     # Cache results
234
ibis.options.compute.chunk_size = 10000      # Process in 10k row chunks
235
ibis.options.compute.parallel = True         # Use parallel processing
236

237
# These affect how backends execute queries
238
result = large_table.group_by('category').aggregate(total=large_table.value.sum())
239
```
240

241
### Debugging Configuration
242

243
Options for debugging and development.
244

245
```python { .api }
246
ibis.options.debug.verbose: bool
247
    """Enable verbose logging (default: False)."""
248

249
ibis.options.debug.show_sql: bool
250
    """Show generated SQL queries (default: False)."""
251

252
ibis.options.debug.show_execution_time: bool
253
    """Show query execution times (default: False)."""
254
```
255

256
**Usage Examples:**
257
```python
258
# Enable debugging
259
ibis.options.debug.verbose = True
260
ibis.options.debug.show_sql = True
261
ibis.options.debug.show_execution_time = True
262

263
# Now operations show debug information
264
result = table.filter(table.value > 100).execute()
265
# Prints:
266
# SQL: SELECT * FROM table WHERE value > 100
267
# Execution time: 0.045 seconds
268
```
269

270
### Option Discovery
271

272
Find available configuration options.
273

274
**Usage Examples:**
275
```python
276
# List all available options
277
all_options = ibis.options.list_options()
278
print("Available options:")
279
for option in all_options:
280
    print(f"  {option}: {ibis.options.get(option)}")
281

282
# Get options by category
283
sql_options = ibis.options.list_options(category='sql')
284
interactive_options = ibis.options.list_options(category='interactive')
285

286
# Get option documentation
287
help_text = ibis.options.get_help('sql.default_limit')
288
print(help_text)
289
```
290

291
### Configuration Inheritance
292

293
How configuration is inherited and overridden.
294

295
**Usage Examples:**
296
```python
297
# Global configuration
298
ibis.options.sql.default_limit = 1000
299

300
# Backend-specific override
301
con = ibis.duckdb.connect()
302
con.options.sql.default_limit = 500  # Override for this connection
303

304
# Query-specific override
305
result = table.limit(100)  # Override for this specific query
306

307
# Precedence: query-specific > connection-specific > global
308
```
309

310
### Environment Variable Configuration
311

312
Configure Ibis through environment variables.
313

314
**Usage Examples:**
315
```python
316
# Environment variables (set before importing ibis)
317
import os
318
os.environ['IBIS_SQL_DEFAULT_LIMIT'] = '5000'
319
os.environ['IBIS_INTERACTIVE_MODE'] = 'true' 
320
os.environ['IBIS_DEBUG_VERBOSE'] = 'false'
321

322
import ibis
323

324
# Options are automatically set from environment
325
print(ibis.options.sql.default_limit)  # 5000
326
print(ibis.options.interactive.mode)   # True
327
print(ibis.options.debug.verbose)      # False
328
```
329

330
### Configuration Profiles
331

332
Use predefined configuration profiles.
333

334
**Usage Examples:**
335
```python
336
# Apply predefined profiles
337
ibis.options.load_profile('development')
338
# Sets: debug.verbose=True, debug.show_sql=True, sql.default_limit=100
339

340
ibis.options.load_profile('production')  
341
# Sets: debug.verbose=False, sql.default_limit=10000, compute.parallel=True
342

343
ibis.options.load_profile('jupyter')
344
# Sets: interactive.mode=True, interactive.max_rows=20, repr.show_types=True
345

346
# Custom profile
347
custom_profile = {
348
    'sql.default_limit': 2000,
349
    'interactive.max_rows': 15,
350
    'debug.show_sql': True
351
}
352
ibis.options.load_profile(custom_profile)
353
```