Configure reasoners

Use reasoner settings to choose which reasoners PyRel uses for your workloads and how PyRel waits for results. This guide covers reasoner selection, logic reasoner settings, and polling behavior.

Before you start, make sure that:

• You have access to a Snowflake account with the RelationalAI Native App installed. If you are unsure, contact your Snowflake administrator.
• You have a working PyRel installation. See Set Up Your Environment for instructions.

Note

This guide covers only the reasoner settings that PyRel reads from config. As of PyRel 1.0.7, auto_suspend_mins and await_storage_vacuum are managed on the reasoner itself, not in raiconfig.yaml or a programmatic Config. To manage those lifecycle settings, use the workflows in Manage compute resources or CLI commands such as reasoners:create and reasoners:alter.

Understand what reasoner configuration covers

These settings apply after PyRel submits work and a reasoner runs your job:

Use the sections in this guide to tune three parts of that step:

• Reasoner selection controls which logic and/or prescriptive reasoner PyRel uses for a workload.
• Logic reasoner settings control constraint reporting and incremental maintenance.
• Polling behavior controls how PyRel waits for long-running operations.

Each section shows the raiconfig.yaml form, the programmatic form, and a quick way to verify the setting.

Select which reasoners to use

Use reasoner name and size settings to configure specific reasoners for PyRel to use.

There are a couple of common patterns for using these settings. Use the following table to choose the workflow that matches your use case:

Workflow	Use it when
Create a new reasoner and use it	You have no existing reasoners and need to fully manage them from config.
Use a reasoner that already exists	You already have a named reasoner and want PyRel to use it as-is.

The following examples show both the raiconfig.yaml and programmatic config patterns for each workflow.

Create a new reasoner and use it

Use this workflow when you have no existing reasoners and want to manage them from your config.

Logic

If you want to create the logic reasoner yourself first, use the CLI:

rai reasoners:create --type logic --name team_logic --size HIGHMEM_X64_S --wait

Then configure PyRel to use that reasoner name and size:

raiconfig.yaml

connections:
    # ...

reasoners:
    logic:
        name: team_logic
        size: HIGHMEM_X64_S

Programmatic

from relationalai.config import create_config

cfg = create_config(
        reasoners={
                "logic": {
                        "name": "team_logic",
                        "size": "HIGHMEM_X64_S",
                }
        }
)

print(cfg.reasoners.logic.name)
print(cfg.reasoners.logic.size)

Prescriptive

If you want to create the prescriptive reasoner yourself first, use the CLI:

rai reasoners:create --type prescriptive --name team_prescriptive --size HIGHMEM_X64_S --wait

Then configure PyRel to use that reasoner name and size:

raiconfig.yaml

connections:
    # ...

reasoners:
    prescriptive:
        name: team_prescriptive
        size: HIGHMEM_X64_S

Programmatic

from relationalai.config import create_config

cfg = create_config(
        reasoners={
                "prescriptive": {
                        "name": "team_prescriptive",
                        "size": "HIGHMEM_X64_S",
                }
        }
)

print(cfg.reasoners.prescriptive.name)
print(cfg.reasoners.prescriptive.size)

Note that:

• If name and size are configured and the named reasoner does not exist, PyRel creates it using the configured size.
• If the named reasoner already exists, PyRel uses it as-is and does not resize it from config.

Related resources:

• Create a reasoner from SQL or the CLI
• Configure logic reasoner settings

Use a reasoner that already exists

Use this workflow when the named reasoner already exists and you want PyRel to use it.

Logic

Set reasoners.logic.name to the existing logic reasoner name:

raiconfig.yaml

connections:
  # ...

reasoners:
  logic:
    name: team_logic

Programmatic

from relationalai.config import create_config

cfg = create_config(
    reasoners={
        "logic": {
            "name": "team_logic",
        }
    }
)

print(cfg.reasoners.logic.name)

In this example:

• reasoners.logic.name tells PyRel which existing logic reasoner to use for model work.
• The example omits size because the reasoner already exists.
• PyRel uses the named reasoner as-is and does not change its size from config.

Prescriptive

Set reasoners.prescriptive.name to the existing prescriptive reasoner name:

raiconfig.yaml

connections:
  # ...

reasoners:
  prescriptive:
    name: team_prescriptive

Programmatic

from relationalai.config import create_config

cfg = create_config(
    reasoners={
        "prescriptive": {
            "name": "team_prescriptive",
        }
    }
)

print(cfg.reasoners.prescriptive.name)

In this example:

• reasoners.prescriptive.name is the public config field for solver workloads.
• The example omits size because the prescriptive reasoner already exists.
• PyRel uses the existing reasoner as-is and does not resize it from config.

Note that:

• If the reasoner is ever deleted, PyRel will create a new one with the same name if necessary, but it will use the default size for that reasoner type instead of the old size.
• For both logic and prescriptive reasoners, the default size is HIGHMEM_X64_S.

Related resources:

• ReasonerConfig API reference
• Create a reasoner from SQL or the CLI

Configure logic reasoner settings

The logic reasoner runs the rules-based parts of your semantic model. PyRel uses it when it evaluates definitions, requirements, and queries.

The settings in this section live under reasoners.logic.*. Most users can leave them at their defaults. If you do need to change a setting, use this table to find the right subsection:

Subsection	Use it when
Constraint emission	You want more detail about requirement failures for debugging.
Incremental maintenance	You want to tune repeated runs that process small data changes.

Related resources:

• LogicReasonerConfig API reference

Enable or disable constraint emission

Use emit_constraints when you need more detail while debugging a failed require() check. This setting controls whether PyRel asks the logic reasoner for additional diagnostics when a requirement fails.

Requirements still pass or fail the same way whether this setting is on or off. It defaults to false, so PyRel returns its usual failure information unless you enable it. When extra diagnostics are available, they may include backend-dependent details such as the violated requirement text or the entities involved in the failing case.

Select the tab for your preferred configuration method and follow the steps to set emit_constraints and verify it.

raiconfig.yaml

1. Set reasoners.logic.emit_constraints in raiconfig.yaml:

   connections:
     # ...
   
   reasoners:
     logic:
       emit_constraints: true

2. Verify the configured value:

    from relationalai.config import create_config
    from relationalai.semantics import Model
   
    cfg = create_config()
   
    # Use the config.
    m = Model("MyModel", config=cfg)
   
    # Verify the configured value.
    print(m.config.reasoners.logic.emit_constraints)

Programmatic

Set reasoners.logic.emit_constraints with LogicReasonerConfig or a plain Python dict.

1. Set the value with a typed config class:

   from relationalai.config import LogicReasonerConfig, ReasonersConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(
       reasoners=ReasonersConfig(
           logic=LogicReasonerConfig(
               emit_constraints=True,
           )
       )
   )
   
   # Use the config.
   m = Model("MyModel", config=cfg)
   
   # Verify the configured value.
   print(m.config.reasoners.logic.emit_constraints)

2. Alternatively, set the value with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(
       reasoners={
           "logic": {
               "emit_constraints": True,
           }
       }
   )
   
   # Use the config.
   m = Model("MyModel", config=cfg)
   
   # Verify the configured value.
   print(m.config.reasoners.logic.emit_constraints)

Related resources:

• Create configuration in code
• LogicReasonerConfig API reference

Enable or disable incremental maintenance

Use reasoners.logic.incremental_maintenance to control whether the logic reasoner reuses work from an earlier run when you rerun the same query after your source data changes. This matters most when you regularly rerun the same query or regenerate the same report on refreshed data, such as rerunning the same weekly report after the underlying source tables update.

Leave this setting at "off" unless that repeated-query pattern is important for your workload. "off" is the default and the safest place to start.

Choose one of these modes:

• "off" (default): Do not use incremental updates.
• "auto": Use incremental updates where they are supported.
• "all": Try incremental updates more broadly than "auto".

Caution

Incremental maintenance is a performance tradeoff, not a guaranteed speedup. It usually helps most when you rerun the same query after small data updates, and it may not help when updates are large or infrequent. As a rough heuristic, it works best when less than about 1% of the input data changes between runs.

Select the tab for your preferred configuration method and follow the steps to set incremental_maintenance and verify it.

raiconfig.yaml

1. Set reasoners.logic.incremental_maintenance in raiconfig.yaml:

   connections:
     # ...
   
   reasoners:
     logic:
       incremental_maintenance: "auto"

2. Verify the configured value:

    from relationalai.config import create_config
    from relationalai.semantics import Model
   
    cfg = create_config()
   
    # Use the config.
    m = Model("MyModel", config=cfg)
   
    # Verify the configured value.
    print(m.config.reasoners.logic.incremental_maintenance)

Programmatic

Set reasoners.logic.incremental_maintenance with LogicReasonerConfig or a plain Python dict.

1. Set the value with a typed config class:

   from relationalai.config import LogicReasonerConfig, ReasonersConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(
       reasoners=ReasonersConfig(
           logic=LogicReasonerConfig(
               incremental_maintenance="auto",
           )
       )
   )
   
   # Use the config.
   m = Model("MyModel", config=cfg)
   
   # Verify the configured value.
   print(m.config.reasoners.logic.incremental_maintenance)

2. Alternatively, set the value with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(
       reasoners={
           "logic": {
               "incremental_maintenance": "auto",
           }
       }
   )
   
   # Use the config.
   m = Model("MyModel", config=cfg)
   
   # Verify the configured value.
   print(m.config.reasoners.logic.incremental_maintenance)

Related resources:

• Create configuration in code
• LogicReasonerConfig API reference

Configure reasoner polling behavior

Polling settings control how often PyRel checks the status of a long-running reasoner operation. Most users should keep the defaults. Change them only if the default wait behavior is already a problem, for example if status updates feel too slow or you need to reduce polling noise.

Select the tab for your preferred configuration method and follow the steps to set the polling settings and verify them.

raiconfig.yaml

1. Set polling settings under reasoners in raiconfig.yaml:

   connections:
     # ...
   
   reasoners:
     poll_initial_delay_s: 0.5
     poll_overhead_rate: 0.2
     poll_max_delay_s: 2.0

2. Verify the configured values:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config()
   
   # Use the config.
   m = Model("MyModel", config=cfg)
   
   # Verify the polling settings.
   print(m.config.reasoners.poll_initial_delay_s)
   print(m.config.reasoners.poll_overhead_rate)
   print(m.config.reasoners.poll_max_delay_s)

Programmatic

Set polling settings with ReasonersConfig or a plain Python dict.

1. Set the values with a typed config class:

   from relationalai.config import ReasonersConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(
       reasoners=ReasonersConfig(
           poll_initial_delay_s=0.1,
           poll_overhead_rate=0.25,
           poll_max_delay_s=5.0,
       )
   )
   
   # Use the config.
   m = Model("MyModel", config=cfg)
   
   # Verify the configured values.
   print(m.config.reasoners.poll_initial_delay_s)
   print(m.config.reasoners.poll_overhead_rate)
   print(m.config.reasoners.poll_max_delay_s)

2. Alternatively, set the values with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(
       reasoners={
           "poll_initial_delay_s": 0.1,
           "poll_overhead_rate": 0.25,
           "poll_max_delay_s": 5.0,
       }
   )
   
   # Use the config.
   m = Model("MyModel", config=cfg)
   
   # Verify the configured values.
   print(m.config.reasoners.poll_initial_delay_s)
   print(m.config.reasoners.poll_overhead_rate)
   print(m.config.reasoners.poll_max_delay_s)

Related resources:

• Create configuration in code
• ReasonersConfig API reference