0
# Configuration and Optimization
1

2
Global configuration system for controlling formatting, streaming behavior, optimization settings, and execution engines with context managers and persistent configuration options.
3

4
## Capabilities
5

6
### Configuration Management
7

8
Global configuration class for controlling Polars behavior across all operations.
9

10
```python { .api }
11
class Config:
12
    # Display and Formatting
13
    @classmethod
14
    def set_fmt_str_lengths(cls, n: int) -> type[Config]:
15
        """Set maximum string length in display."""
16
    
17
    @classmethod
18
    def set_fmt_float(cls, fmt: str) -> type[Config]:
19
        """Set float number formatting."""
20
    
21
    @classmethod
22
    def set_tbl_cols(cls, n: int) -> type[Config]:
23
        """Set maximum columns in table display."""
24
    
25
    @classmethod
26
    def set_tbl_rows(cls, n: int) -> type[Config]:
27
        """Set maximum rows in table display."""
28
    
29
    @classmethod
30
    def set_tbl_width_chars(cls, width: int) -> type[Config]:
31
        """Set table width in characters."""
32
    
33
    # Streaming Configuration
34
    @classmethod
35
    def set_streaming_chunk_size(cls, size: int) -> type[Config]:
36
        """Set streaming chunk size."""
37
    
38
    # Global Settings
39
    @classmethod
40
    def set_auto_structify(cls, active: bool) -> type[Config]:
41
        """Enable/disable automatic struct creation."""
42
    
43
    @classmethod
44
    def set_thousands_separator(cls, separator: str) -> type[Config]:
45
        """Set thousands separator in display."""
46
    
47
    @classmethod
48
    def set_decimal_separator(cls, separator: str) -> type[Config]:
49
        """Set decimal separator in display."""
50
    
51
    # Configuration Management
52
    @classmethod
53
    def restore_defaults(cls) -> type[Config]:
54
        """Restore all settings to defaults."""
55
    
56
    @classmethod
57
    def save(cls, file: str) -> None:
58
        """Save current configuration to file."""
59
    
60
    @classmethod
61
    def load(cls, file: str) -> type[Config]:
62
        """Load configuration from file."""
63
    
64
    # Context Manager Support
65
    def __enter__(self):
66
        """Enter configuration context."""
67
    
68
    def __exit__(self, exc_type, exc_val, exc_tb):
69
        """Exit configuration context."""
70
```
71

72
### Query Optimization
73

74
Configuration for query optimization flags and execution strategies.
75

76
```python { .api }
77
class QueryOptFlags:
78
    def __init__(
79
        self,
80
        *,
81
        type_coercion=True,
82
        predicate_pushdown=True,
83
        projection_pushdown=True,
84
        simplify_expression=True,
85
        slice_pushdown=True,
86
        comm_subplan_elim=True,
87
        comm_subexpr_elim=True,
88
        cluster_with_columns=True,
89
        streaming=False
90
    ):
91
        """
92
        Query optimization flags.
93
        
94
        Parameters:
95
        - type_coercion: Enable type coercion optimization
96
        - predicate_pushdown: Push predicates down to data sources
97
        - projection_pushdown: Push column projections down
98
        - simplify_expression: Simplify expressions
99
        - slice_pushdown: Push slice operations down
100
        - comm_subplan_elim: Eliminate common subplans
101
        - comm_subexpr_elim: Eliminate common subexpressions
102
        - cluster_with_columns: Cluster with_columns operations
103
        - streaming: Enable streaming execution
104
        """
105
```
106

107
### GPU Engine
108

109
GPU acceleration configuration for supported operations.
110

111
```python { .api }
112
class GPUEngine:
113
    def __init__(
114
        self,
115
        *,
116
        device=None,
117
        memory_resource=None,
118
        raise_on_fail=False
119
    ):
120
        """
121
        GPU execution engine configuration.
122
        
123
        Parameters:
124
        - device: GPU device ID
125
        - memory_resource: GPU memory resource
126
        - raise_on_fail: Raise error if GPU execution fails
127
        """
128
```
129

130
## Usage Examples
131

132
### Basic Configuration
133

134
```python
135
import polars as pl
136

137
# Set display options
138
pl.Config.set_tbl_rows(20)
139
pl.Config.set_tbl_cols(10)
140
pl.Config.set_fmt_str_lengths(50)
141

142
# Create DataFrame to see formatting
143
df = pl.DataFrame({
144
    "long_column_name": ["very long string value"] * 100,
145
    "numbers": range(100)
146
})
147

148
print(df)  # Will use new display settings
149
```
150

151
### Context Manager Configuration
152

153
```python
154
# Temporary configuration changes
155
with pl.Config() as cfg:
156
    cfg.set_tbl_rows(5)
157
    cfg.set_fmt_str_lengths(10)
158
    
159
    # DataFrame display uses temporary settings
160
    print(df.head(10))
161

162
# Settings restored after context
163
print(df.head(10))  # Uses default settings
164
```
165

166
### Query Optimization Configuration
167

168
```python
169
# Custom optimization flags
170
opt_flags = pl.QueryOptFlags(
171
    predicate_pushdown=True,
172
    projection_pushdown=True,
173
    streaming=True
174
)
175

176
# Use with LazyFrame collection
177
result = (
178
    pl.scan_csv("large_file.csv")
179
    .filter(pl.col("amount") > 1000)
180
    .select(["id", "amount", "date"])
181
    .collect(**opt_flags.__dict__)
182
)
183
```
184

185
### Persistent Configuration
186

187
```python
188
# Save current configuration
189
pl.Config.save("my_polars_config.json")
190

191
# Modify settings
192
pl.Config.set_tbl_rows(50)
193
pl.Config.set_streaming_chunk_size(1000000)
194

195
# Later, restore saved configuration
196
pl.Config.load("my_polars_config.json")
197

198
# Or restore defaults
199
pl.Config.restore_defaults()
200
```