The squirrels.yml file is the main manifest configuration file for a Squirrels project. It defines your project’s metadata, database connections, datasets, and other settings. The file supports Jinja templating, allowing you to use environment variables and dynamic values.
The major version number of the project. Used in API versioning (e.g., /analytics/my-project/v1).Increment this when there are breaking changes in the Squirrels datasets (e.g., removing/renaming columns). See below for more information.
The authentication enforcement for the project. One of:
optional: Authentication is optional (default). Datasets and dashboards default to public scope.
required: Authentication is required. Datasets and dashboards default to protected scope, and public scope is explicitly forbidden.
Defaults:
If auth_strategy is managed, the default is optional.
If auth_strategy is external, the default is required.
Notes:
auth_strategy: external does not allow auth_type: optional.
The project_variables section allows additional custom fields beyond the ones listed above. These extra fields can be accessed in your Python configurations and Jinja templates.
When to increment the major version?For an API client that relies on your Squirrels API server, it may expect specific parameter names, parameter options to accept a range of values, or datasets to contain specific column names. If you were to remove a column from a dataset on your existing service for instance, this may break the API client.To account for this, it is recommended to avoid removing or renaming columns or parameters, and document it as deprecated in its description instead. Once you are ready to remove the deprecated feature, increment the major version, and deploy a new service without removing the old version. Since the major version is included in the API path, deploying both versions on the same domain is possible. The old version can be removed after all clients have migrated to the new version.See mounting Squirrels to an existing FastAPI server for guidance on hosting multiple Squirrels apps in one API server.
The connection URI. Format varies by database and connection type. The special placeholder {project_path} is replaced with the absolute path to your project directory.For details on URI formats for each connection type, see URI formats.
Defining parameters here in yaml is not recommended. Defining parameters with Python in pyconfigs/parameters.py is preferred, especially when using an IDE that provides linting and autocomplete for Python.
Defines parameter widgets for your datasets with YAML.
Copy
parameters: - type: SingleSelectParameter factory: CreateWithOptions arguments: name: region label: Region all_options: - id: na label: North America is_default: true - id: eu label: Europe
Each parameter is defined as a list item with the following properties:
Arguments passed to the factory method. The available arguments depend on the type and factory combination. Common arguments include name, label, description, and type-specific options.
Defines project-level configurables that can be set at runtime via HTTP headers. Unlike parameters, these do not get exposed as arguments for MCP tools (i.e., AI agents cannot control them). The default values can also be overridden at the dataset level.
Copy
configurables: - name: schema_name label: Database Schema description: The schema to query from default: public
Each configurable is defined as a list item with the following properties:
Dataset-level overrides for project configurables. Each item specifies a name (which must be a valid name from the configurables section) and default (for a different default value for this dataset).See the configurables section above for more information on project configurables.
Configurable name-value pairs to use for the test set.
A test set named default is automatically used when no test set is specified during compilation. You can override the default behavior by defining a test set with this name.
