Skip to main content
When you create a new Squirrels project using the sqrl new or sqrl init commands, a standard directory structure is generated. This structure is designed to organize your configuration, models, and assets effectively. 
my_project/
├── squirrels.yml
├── .env (and/or .env.local)
├── pyconfigs/
|   ├── connections.py
|   ├── parameters.py
|   ├── context.py
|   └── user.py
├── seeds/
├── macros/
├── models/
|   ├── builds/
|   ├── dbviews/
|   ├── federates/
|   └── sources.yml
└── dashboards/
Only the squirrels.yml file is required for a Squirrels project. Every other file is optional. See the sqrl get-file command for a quick way to add sample files to your Squirrels project.

​
Core configurations

​
squirrels.yml

The manifest file for your project. It defines the datasets and other project-level settings.

​
.env or .env.local

The environment variables file for your project. Squirrels uses environment variables for specific project configuration that may differ based on the hosted environment.

​
duckdb_init.sql

The initialization script for DuckDB. A global initialization script can also be specified at ~/.squirrels/duckdb_init.sql.

​
Python configurations

​
pyconfigs/

The pyconfigs/ directory contains Python modules that configure various aspects of your project.
  • connections.py: Defines database connections. You can specify connection strings for different environments or data sources here.
  • parameters.py: Configures parameters that can be used in your models. This includes defining widgets, default values, and validation logic.
  • context.py: Provides a dictionary of variables and functions available to your Jinja templates and Python models. Useful for sharing constants or helper functions.
  • user.py: Defines the user model and authentication logic. You can customize user attributes and how they map to dataset permissions.

​
Data model configurations

​
models/

The models/ directory holds the logic for transforming your data.
  • builds/: Contains models that are materialized as tables or views in the database. These are typically executed once during the build process.
  • dbviews/: Dynamic SQL views that are executed on the database at query time. These can use parameters to filter or aggregate data dynamically.
  • federates/: Models that can combine data from multiple sources. These can be SQL queries or Python scripts that return dataframes.
  • sources.yml: A YAML file where you define your source tables and their properties. This helps in documenting and managing dependencies.

​
macros/

Custom Jinja macros can be placed here. Macros are reusable snippets of SQL or logic that can be called from your models.

​
seeds/

CSV files that contain static data to be loaded into the database. Seeds are useful for lookup tables or small reference datasets.

​
Dashboard configurations

​
dashboards/

This directory contains dashboard definitions. Dashboards can be defined in YAML or Python and reference the datasets created in your models.

​
Generated outputs

​
target/

Artifacts generated by Squirrels are stored here.
  • compile/: Contains the compiled SQL files generated by sqrl compile.
  • duckdb_init.sql: Generated initialization script for DuckDB. This is generated from the global initialization script (found at ~/.squirrels/duckdb_init.sql) followed by line breaks and the project initialization script (found at my_project/duckdb_init.sql).
  • vdl_catalog.duckdb: The catalog database for the Virtual Data Lake (VDL). This is a DuckDB database that contains the metadata for the VDL, unless specified otherwise through the SQRL_VDL__CATALOG_DB_PATH environment variable.
  • vdl_data/: The data directory for the Virtual Data Lake (VDL). This is a directory that contains the data for the VDL, unless specified otherwise through the SQRL_VDL__DATA_PATH environment variable.