Configure PyRel
PyRel can be configured to fit different use cases and workflows. This overview helps you understand what configuration methods are available, when PyRel loads and validates configuration, and find the right guide for the settings you want to change.
Where configuration comes from
Section titled “Where configuration comes from”You can supply configuration using a configuration file or programmatically in Python. Use this table to choose the right configuration approach for your project:
| What to use | When to use it |
|---|---|
Load a raiconfig.yaml file | Default for new projects. Use when you want auto-discovery and a shareable, repo-friendly configuration file that you can commit to version control. |
Call create_config() in Python | Use when configuration must be created or overridden at runtime in tests, notebooks, or CI. |
What you can configure
Section titled “What you can configure”Once you know how configuration will be supplied, use the following table to choose the PyRel execution workflow stage you want to customize:
| Step | Guides |
|---|---|
| 1. Load and validate configuration | Load configuration from files Create configuration in code Configure Snowflake authentication |
| 2. Build model and query | Configure compilation behavior |
| 3. Submit RelationalAI job | Configure execution behavior Configure data sync behavior |
| 4. Run job with reasoners | Configure reasoners |
| 5. Materialize results | Configure results access |
- PyRel resolves and validates configuration during config loading.
- PyRel acquires a database session later, when work needs one.
- This separation affects where errors appear. Some issues surface during config loading, while others appear only when PyRel needs a session.
How validation works
Section titled “How validation works”PyRel validates configuration when it resolves it into a Config object.
This usually happens at one of these entry points:
- You call
create_config()to create configuration programmatically. - You create a
Modelobject without passingconfig=...to the constructor. PyRel then resolves configuration from its supported sources, including configuration file discovery.
If PyRel cannot resolve a valid configuration source, config loading fails with an error.
Validation is separate from database session acquisition. If an issue affects only session creation, such as missing or incorrect Snowflake credentials, you might not see it until PyRel needs a session.
How database sessions are managed
Section titled “How database sessions are managed”PyRel does not open a database session when it loads configuration. You do not need to create a database session yourself.
Instead, session access follows this lifecycle:
- In Snowflake-hosted environments, PyRel reuses an active Snowpark session when one is already available.
- Otherwise, PyRel creates and caches a session on the connection when it runs work that needs one.
Follow configuration best practices
Section titled “Follow configuration best practices”These practices make configuration safer and easier to maintain.
Use profiles for development and production
Section titled “Use profiles for development and production”Profiles are named overrides on top of your base configuration. You can override only what changes between environments, such as the warehouse or database, without duplicating the whole file.
Store secrets in environment variables
Section titled “Store secrets in environment variables”Avoid committing secrets like passwords and tokens. Instead, store them in environment variables and reference them from your configuration.
Where to go next
Section titled “Where to go next”If you are setting up PyRel configuration for the first time, start with Load configuration from files. If you already know how configuration will be supplied, choose the topic guide for the workflow stage you want to customize.