Configure PyRel
PyRel configuration helps you set consistent defaults for database connections, job execution, and reasoners across scripts and environments. Use this guide when you’re setting up a new project, switching environments, or troubleshooting surprising behavior.
This overview page explains how configuration works at a high level and links to focused pages for common configuration tasks.
Where configuration comes from
Section titled “Where configuration comes from”You can define config in a raiconfig.yaml file.
You can also build it in code using the create_config() function.
In both cases, PyRel validates your config and loads it into a Config object that your code can inspect and use via Model.config.
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 config file that you can commit to version control. |
Call create_config() in Python | Use when config must be created or overridden at runtime in tests, notebooks, or CI. |
How file discovery works
Section titled “How file discovery works”PyRel supports multiple config sources and looks for them in a fixed priority order. It uses the first source it finds:
PyRel validates the first source it finds. If it is invalid, PyRel raises an error and does not fall back.
What you can configure
Section titled “What you can configure”This configuration guide is split into focused pages, each covering one common setup task.
Use the pages below when you want to change defaults in raiconfig.yaml or understand what the same settings look like in Python.
| Settings | Description |
|---|---|
| Snowflake authentication | Configure Snowflake authentication for PyRel connections. |
| Execution behavior | Configure PyRel metrics, logging, retries, and related client-side defaults. |
| Reasoners | Configure PyRel reasoner backend selection, polling defaults, and logic reasoner settings. |
How validation works
Section titled “How validation works”PyRel validates configuration when it loads it into a Config object.
In most code, that happens when you call create_config() or when you create Model() without passing config=....
For file-based config, discovery starts from your current working directory.
Running the same script from a different directory can change which raiconfig.yaml is found.
If something is missing or inconsistent, PyRel raises an error immediately. It does not fall back to lower-priority sources after a validation error.
How database sessions are managed
Section titled “How database sessions are managed”PyRel does not connect to a database until it needs to. In most workflows, this happens the first time a RelationalAI job is executed. For example, running your first job triggers session creation. PyRel caches the session on the connection. Later jobs reuse that same session.
You usually do not need to create a session yourself.
For example, Model creates a session the first time a RelationalAI job is run, like data synchronization or query execution, and reuses it for later jobs.
If you need a fresh session, for example after rotating credentials, you can clear the cached session by calling BaseConnection.clear_session_cache() on the connection and request it again:
from relationalai.semantics import Model
m = Model("MyModel")
# The first job triggers session creation lazily.m.select("hello world").to_df()
# If you want the underlying session, you can still request it directly.session1 = m.config.get_session()session2 = m.config.get_session()assert session1 is session2
# Force a fresh session on the next lookup.conn = m.config.get_default_connection()conn.clear_session_cache()session3 = m.config.get_session()Follow best practices
Section titled “Follow best practices”These practices make configuration safer and easier to maintain. Use them when you want a single config setup that works across dev, CI, and production.
Use profiles for dev vs prod
Section titled “Use profiles for dev vs prod”Profiles are named overlays on top of your base config. You can override only what changes between environments, such as 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 config.