Workspace Settings
The Settings surface configures workspace-wide behavior for modeling, AI generation, and project conventions. These settings directly influence how Zingle's AI generates SQL, schemas, and semantic definitions.
Accessing settings
Navigate to Settings from the sidebar. The page has three configuration sections, each saved independently.
YAML configuration
The YAML config section stores workspace-level dbt or project configuration:
- Model paths — where models live in your repo
- Materializations — default materialization strategy (view, table, incremental)
- Custom variables — project-level variables used in SQL generation
Changes are saved via PUT /api/v1/settings and take effect immediately for new AI generations.
Empty strings are normalized to null on save. This means "unset" is distinct from "empty" — if you clear a field, it's treated as not configured rather than configured with a blank value.
Modeling guidelines
Free-form text that captures your team's data modeling standards:
- Naming conventions — prefixes like
raw_,bronze_,silver_,int_,fct_,dim_,gold_ - Layer rules — e.g., "No joins in raw/bronze layers; heavy joins in intermediate and gold only"
- Performance patterns — partitioning, clustering, incremental strategies
- Code style — CTE naming, comment formats, SQL formatting preferences
The AI reads these guidelines when generating SQL and schemas. Well-written guidelines significantly improve output quality and consistency.
Example modeling guidelines
Naming:
- Raw tables: raw_{source}_{table}
- Bronze: bronze_{domain}_{entity}
- Intermediate: int_{domain}_{purpose}
- Gold: gold_{domain}_{entity}
Rules:
- No joins in bronze layer
- Use incremental materialization for tables > 1M rows
- Always include created_at and updated_at timestamps
- Primary keys must have not_null and unique tests
Custom instructions
Fine-tune how the AI assistant behaves:
- PR formatting — how titles and bodies should be written
- Code style — comment format, docstring conventions
- PII handling — rules for columns containing sensitive data
- Logging constraints — what should or shouldn't appear in generated code
Custom instructions act as persistent system prompts — they're included in every AI generation within the workspace.
How settings are stored
| Behavior | Details |
|---|---|
| First save | Creates a new settings record for your workspace |
| Subsequent saves | Updates in place, bumps updated_at timestamp |
| Partial updates | Only fields you modify are changed; others remain untouched |
| Empty handling | Empty strings become null (unset) |
API reference
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/settings | Retrieve current workspace settings |
PUT | /api/v1/settings | Update workspace settings (partial update supported) |