Configure reasoners

Configure how PyRel talks to reasoners and how it waits for long-running reasoner operations. Use these settings when you want consistent defaults across scripts, notebooks, and CI.

The following sections show how to configure these settings in both raiconfig.yaml and programmatically with Python code. See the API reference for details on all available options and their 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 working PyRel installation. See Set Up Your Environment for instructions.

Choose a reasoner backend (SQL vs Direct Access)

PyRel talks to the RelationalAI native app by calling internal reasoner APIs. Those internal APIs can be reached through Snowflake SQL (sql) or through a Direct Access HTTP API (direct_access):

Backend	Benefits	Tradeoffs and requirements
sql (default)	Works anywhere you can run Snowflake SQL, and typically requires no additional networking setup.	Not preferred when Direct Access is available, and latency/availability follow your Snowflake environment.
direct_access (preferred when available)	Calls internal HTTP APIs directly, which can reduce overhead in some environments.	Requires admin setup plus reasoners.direct_access_base_url and a pre-issued token, and it may be blocked by network policy or unavailable in some deployments.

raiconfig.yaml

1. Set reasoners.backend (and reasoners.direct_access_base_url for Direct Access):

   connections:
     # ...
   
   reasoners:
     # Options: sql (default) | direct_access
     backend: direct_access
     direct_access_base_url: https://reasoners.example.com

   If you prefer the SQL backend, set backend: sql (or omit the field).

2. Verify the effective backend in Python:

    from relationalai.config import create_config
    from relationalai.semantics import Model
   
    cfg = create_config()
   
    # Use the config
    m = Model("MyModel", config=cfg)
   
    # Verify the backend selection:
    print(m.config.reasoners.backend)
   
    # When using Direct Access, verify the base URL:
    print(m.config.reasoners.direct_access_base_url)

Programmatic

Set reasoners.backend with ReasonersConfig or a plain Python dict. These examples assume you already have a valid connection configured through file discovery.

1. Set the value with a typed config class:

    from relationalai.config import ReasonersConfig, create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       reasoners=ReasonersConfig(
           backend="direct_access",
           direct_access_base_url="https://reasoners.example.com",
       )
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured values:
   print(m.config.reasoners.backend)
   print(m.config.reasoners.direct_access_base_url)

2. Alternatively, set the value with a dict:

    from relationalai.config import create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       reasoners={
           "backend": "direct_access",
           "direct_access_base_url": "https://reasoners.example.com",
       }
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured values:
   print(m.config.reasoners.backend)
   print(m.config.reasoners.direct_access_base_url)

Legacy behavior

Older configs may use the deprecated top-level use_direct_access: true toggle. If use_direct_access is true and reasoners.backend is still sql, PyRel switches the backend to direct_access automatically.

Configure reasoner polling behavior

Polling settings control how PyRel waits for long-running reasoner operations. Use them when you want waiting to be more responsive (more polls) or less chatty (fewer polls).

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. These examples assume you already have a valid connection configured through file discovery.

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)

Configure logic reasoner defaults

Logic reasoner settings live under reasoners.logic.*. Use them when you want a consistent default for logic execution and related compiler behavior. See the API reference for details on all available options, their behavior, and how they interact with compiler settings.

Enable or disable constraint emission

Requirements are checks you add with require() in your model. When emit_constraints is enabled, PyRel asks the reasoner to include a “constraints” report about those requirements in the response. It defaults to false, which means validation messages will not appear when a requirement is violated. Enable it if you want that extra output for debugging, but be aware that it may increase response size and latency.

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. These examples assume you already have a valid connection configured through file discovery.

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)

Enable or disable incremental maintenance

Incremental maintenance can improve performance for repeated logic executions by reusing computed definitions after your underlying data changes. It helps most when updates are frequent and small relative to the total data, and when small input changes lead to small changes in results.

Caution

Incremental maintenance is a performance and cost tradeoff. It can make the first execution more expensive, and it may not help if your data is mostly static or if a large fraction of rows change between runs. As a rule of thumb, it tends to work best when less than about 1% of the input data changes between runs.

Use one of these modes:

• "off" (default): Disable incremental maintenance.
• "auto": Only maintain definitions that are inferred to be efficiently maintainable.
• "all": Try to maintain all definitions that can be incrementally maintained.

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. These examples assume you already have a valid connection configured through file discovery.

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)