Create a model instance

Create a Model object so you can declare concepts, add definitions, and run queries against a shared semantic model. This guide shows how to instantiate Model, control which connection configuration it uses, and tune compiler strictness for type errors.

PyRel is installed and configured. See Set Up Your Environment for instructions.

Create a Model instance

A Model instance is the entry point for semantic modeling in PyRel. Keep one model object as the shared handle for concept declarations, definitions, and queries in the same workflow. If you do not pass an explicit config, Model() loads config from the filesystem using discovery rules.

There are three things you need to do:

Import Model from relationalai.semantics:

from relationalai.semantics import Model

Instantiate the model:
```
from relationalai.semantics import Model

m = Model("MyModel")
```
Model() eagerly loads configuration from the filesystem and will raise an error if no config source is discoverable. See Configure a model’s connection for details and workarounds.

Reuse the model across declarations:

from relationalai.semantics import Model

m = Model("MyModel")

Customer = m.Concept("Customer")

Configure a model’s connection

A model uses configuration to choose which connection it will use when it runs RelationalAI jobs. By default, Model() discovers configuration from files on disk (for example raiconfig.yaml) based on your current working directory. If you need repeatable behavior (for example, tests, CI, or notebooks), pass configuration explicitly when you create the model.

Use a configuration file

Choose this when you want a repo-friendly default and you do not need runtime overrides. This workflow lets Model() discover configuration automatically from your project.

Do the following:

Create a minimal raiconfig.yaml in your project root:
raiconfig.yaml
```
default_connection: snowflake
connections:
  snowflake:
    type: snowflake
    authenticator: username_password
    account: "my_account"
    user: "my_user"
    warehouse: "my_warehouse"
    password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
```
Use environment variables for secrets and sensitive values. Refer to them with {{ env_var('VAR_NAME') }} in config files. Set the environment variable in your shell before you run your Python code, for example export SNOWFLAKE_PASSWORD="my_password".

Instantiate Model and confirm what it loaded:

from relationalai.semantics import Model

m = Model("MyModel")

print(m.config.default_connection)
print(type(m.config.get_default_connection()))

If you run the same code from a different directory, discovery can find a different raiconfig.yaml.
If you define multiple connections, set default_connection explicitly so the selection is unambiguous.

Use explicit programmatic configuration

Choose this when you need runtime isolation or explicit overrides (for example, tests, CI, or notebooks). This workflow bypasses file discovery and uses only the config you build in Python.

Do the following:

Create a config in code with create_config():

import os

from relationalai.config import create_config

cfg = create_config(
    connections={
        "sf": {
            "type": "snowflake",
            "authenticator": "username_password",
            "account": os.environ["SNOWFLAKE_ACCOUNT"],
            "warehouse": os.environ["SNOWFLAKE_WAREHOUSE"],
            "user": os.environ["SNOWFLAKE_USER"],
            "password": os.environ["SNOWFLAKE_PASSWORD"],
        },
    },
)

Instantiate Model with config=cfg and confirm what it will use:

from relationalai.semantics import Model

m = Model("MyModel", config=cfg)

# View details for the default connection
print(m.config.default_connection)

create_config(...) creates a validated config instance.
Model("MyModel", config=cfg) bypasses filesystem discovery and uses your explicit config for execution.
When you define multiple connections, always set default_connection so m.config.get_default_connection() is well-defined. See Use profiles to manage multiple configurations for details.

Configure compiler strictness for type errors

Compiler settings control whether type issues stop compilation or show up as warnings while translating your model and queries. Strict mode is a good fit for tests and CI. Soft error mode is a good fit for early iteration. Both settings default to false.

compiler.strict enables stricter validation during compilation.
compiler.soft_type_errors (soft error mode) treats type errors as warnings instead of failures.

Set these options when you create a config for your model. Although you can set them in a raiconfig.yaml file, setting them in code is more explicit and easier to change at runtime:

from relationalai.config import create_config
from relationalai.semantics import Model

cfg = create_config(
    compiler={
        "strict": True,
        "soft_type_errors": True,
    },
)

m = Model("MyModel", config=cfg)

print(m.config.compiler.strict)
print(m.config.compiler.soft_type_errors)

create_config(...) creates a validated config instance with compiler overrides.
"strict": True enables strict mode.
"soft_type_errors": True enables soft error mode.
Printing m.config.compiler.* confirms what the model will use.

If you pass a config without connection details, the model still needs a connection from a discoverable config source, or from an active session.
Strict mode can surface new compilation errors. Plan to fix missing types and other schema issues when you enable it.

Avoid common pitfalls

Model initialization is usually where configuration and connection issues show up first. Use this table to map common symptoms to likely causes and quick remediation steps:

Symptom	Likely cause	Fix
`Model()` raises an error because no config source is discoverable.	You did not pass an explicit config, and discovery could not find a config source on disk.	Add a minimal `raiconfig.yaml` in your project root (or run from a directory where one is discoverable), or pass an explicit config with `create_config(connections=...)` and `Model("MyModel", config=cfg)`.
`Model()` loads the wrong config (or a different connection/profile) depending on where you run it from.	File discovery found a different `raiconfig.yaml` because your current working directory changed (discovery searches upward from your current working directory).	Run from the project root, or make behavior repeatable by passing `config=` explicitly when you create the model.
`Model()` fails while loading a discovered `raiconfig.yaml`.	The discovered file is invalid YAML or contains invalid fields, so config loading fails.	Fix the YAML/fields, or temporarily rename or move the file out of the discovery path to confirm discovery is the cause.
`m.config.get_default_connection()` fails, or the default connection is ambiguous.	You defined multiple connections but did not set `default_connection`.	Set `default_connection` in `raiconfig.yaml` (or in `create_config(...)`) and re-run.
Config loads, but secrets are missing (for example, authentication fails or `{{ env_var('...') }}` resolves to nothing).	A referenced environment variable is not set in the environment where Python is running.	Set or export the environment variable in the same shell/session (or configure it in your notebook or CI environment) and re-run.
`Model()` fails because the config you passed does not include a connection.	You passed a partial programmatic config (for example, compiler settings), but the model still needs connection details.	Include connection settings in `create_config(...)` (and set `default_connection` when you define multiple connections), or ensure a discoverable config source exists before you construct `Model()`.