Configure execution behavior

Control how PyRel runs RelationalAI jobs by enabling optional SDK features (metrics, logging, retries) and setting related compiler and helper defaults. Use it when you need better visibility, more resilience to temporary failures, or consistent defaults across projects.

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.

Note

These settings only affect the PyRel client running in your app or notebook. They do not change Snowflake account settings or warehouse configuration.

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.

Enable or disable metrics collection

Execution metrics are small counters and timings collected by the PyRel SDK while it runs RelationalAI jobs. Enable them when you want visibility into how often operations run and how long they take. PyRel stores these metrics in-process and does not automatically export them to an external monitoring system.

raiconfig.yaml

1. Set execution.metrics in raiconfig.yaml:

   connections:
     # ...
   
   execution:
     metrics: true

2. View the collected metrics:

   from relationalai.client import connect_sync
   from relationalai.semantics import Model
   
   # Get a client.
   client = connect_sync()
   
   # Run a query to generate some metrics.
   m = Model("MyModel")
   m.select("hello world").to_df()
   
   # Inspect the metrics.
   metrics = client.execution_metrics
   print(metrics.counters)
   print(metrics.timings_ms)

Programmatic

Set execution.metrics using ExecutionConfig 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 ExecutionConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(execution=ExecutionConfig(metrics=True))
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.execution.metrics)

2. Alternatively, set the value with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(execution={"metrics": True})
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.execution.metrics)

3. View the collected metrics:

   from relationalai.client import connect_sync
   from relationalai.semantics import Model
   
   # Get a client.
   client = connect_sync(config=cfg)
   
   # Run a job to generate metrics.
   m = Model("MyModel", config=cfg)
   m.select("hello world").to_df()
   
   # Inspect the metrics.
   metrics = client.execution_metrics
   print(metrics.counters)
   print(metrics.timings_ms)

Enable or disable execution logs

Execution logs are structured log messages emitted by the PyRel SDK while it runs RelationalAI jobs. Enable them when you are debugging slow jobs, failures, or retries and want more context. Turning this on does not automatically print logs; you must configure Python logging to display the logger output.

raiconfig.yaml

1. Set execution.logging in raiconfig.yaml:

   connections:
     # ...
   
   execution:
     logging: true

2. Configure Python logging to display relationalai.client.executionlogs:

   import logging
   
   logging.basicConfig(level=logging.INFO)
   logging.getLogger("relationalai.client.execution").setLevel(logging.INFO)

Programmatic

Set execution.logging using ExecutionConfig 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 ExecutionConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(execution=ExecutionConfig(logging=True))
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.execution.logging)

2. Alternatively, set the value with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(execution={"logging": True})
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.execution.logging)

3. Configure Python logging to display relationalai.client.execution logs:

   import logging
   
   logging.basicConfig(level=logging.INFO)
   logging.getLogger("relationalai.client.execution").setLevel(logging.INFO)

Note that:

• Execution log lines include request kind, operation name, elapsed time, and meta.
• PyRel does not log SQL statements or HTTP request bodies/headers in these execution logs.
• Exception messages may include sensitive details, depending on what the backend returns.

Enable or disable retries

Retries are automatic re-attempts the PyRel SDK can make when an operation fails due to a temporary error (for example, a short network hiccup). You can enable retries to reduce flaky failures in scripts and production jobs. max_attempts is the total number of attempts, including the first try.

raiconfig.yaml

Set execution.retries in raiconfig.yaml:

connections:
    # ...

execution:
    retries:
        enabled: true
        max_attempts: 5
        base_delay_s: 0.25
        max_delay_s: 5.0
        jitter: 0.2

Programmatic

Set execution.retries using ExecutionConfig or a plain Python dict. These examples assume you already have a valid connection configured through file discovery.

1. Configure retries and backoff with a typed model:

   from relationalai.config import ExecutionConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(
      execution=ExecutionConfig(
         retries=ExecutionConfig.RetriesConfig(
            enabled=True,
            max_attempts=5,
            base_delay_s=0.25,
            max_delay_s=5.0,
            jitter=0.2,
         ),
      ),
   )
   m = Model("MyModel", config=cfg)

2. Alternatively, configure retries and backoff with a plain dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(
      execution={
         "retries": {
            "enabled": True,
            "max_attempts": 5,
            "base_delay_s": 0.25,
            "max_delay_s": 5.0,
            "jitter": 0.2,
         },
      },
   )
   m = Model("MyModel", config=cfg)

Enable or disable strict mode

Strict mode makes the PyRel compiler validate more aggressively during compilation, so problems are caught earlier. It is disabled by default. Enable it when you want to fail fast in CI, tests, or production jobs where you prefer an error over a partial or ambiguous result.

Caution

Strict mode can surface issues that previously compiled, so you may need to fix types or definitions after turning it on.

raiconfig.yaml

1. Set compiler.strict in raiconfig.yaml:

   connections:
       # ...
   
   compiler:
       strict: true

2. Inspect the parsed config:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   print(m.config.compiler.strict)

Programmatic

Set compiler.strict using CompilerConfig 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 CompilerConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(compiler=CompilerConfig(strict=True))
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.compiler.strict)

2. Alternatively, set the value with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(compiler={"strict": True})
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.compiler.strict)

Enable or disable soft error mode

Soft error mode treats compiler type errors as warnings instead of failures. It is disabled by default, which means type errors will cause compilation to fail. Enable it when you are iterating quickly (for example, in notebooks) and prefer to keep going while you fix types.

Caution

Soft error mode can hide real problems until later, so use it intentionally and consider disabling it in CI and production jobs.

raiconfig.yaml

1. Set compiler.soft_type_errors in raiconfig.yaml:

   connections:
     # ...
   
   compiler:
     soft_type_errors: true

2. Inspect the parsed config

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.compiler.soft_type_errors)

Programmatic

Set compiler.soft_type_errors using CompilerConfig 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 CompilerConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(compiler=CompilerConfig(soft_type_errors=True))
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.compiler.soft_type_errors)

2. Alternatively, set the value with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(compiler={"soft_type_errors": True})
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.compiler.soft_type_errors)

Set the query timeout

Set a client-side default timeout (in minutes) for PyRel queries when you want long-running operations to fail instead of hanging indefinitely (for example, in pipelines). It is unset by default, which means queries will not time out on the client side, though they may still be subject to server-side timeouts.

raiconfig.yaml

1. Set data.query_timeout_mins in raiconfig.yaml:

   connections:
     # ...
   
   data:
     query_timeout_mins: 10

2. Inspect the parsed config

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.data.query_timeout_mins)

Programmatic

Set data.query_timeout_mins using DataConfig or a plain Python dict. These examples assume you already have a valid connection configured through file discovery.

1. Set the query timeout with a typed config class:

   from relationalai.config import DataConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data=DataConfig(query_timeout_mins=10))
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value (in minutes):
   print(m.config.data.query_timeout_mins)

2. Set the query timeout with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data={"query_timeout_mins": 10})
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value (in minutes):
   print(m.config.data.query_timeout_mins)

Enable or disable stream synchronization before query execution

Set data.wait_for_stream_sync to control whether PyRel data helpers wait for data streams to synchronize before running queries. It is enabled by default, which means helpers will wait for streams to be fully synchronized before querying. Disable it when you prefer faster query execution and can tolerate potentially stale data.

Tip

You can also set a data freshness threshold to require data to be no older than a specific window. Note that if wait_for_stream_sync is disabled, the freshness threshold will not be enforced before queries meaning you could still get stale data in query results.

raiconfig.yaml

1. Set data.wait_for_stream_sync in raiconfig.yaml:

   connections:
     # ...
   
   data:
     wait_for_stream_sync: true

2. Inspect the parsed config:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.data.wait_for_stream_sync)

Programmatic

Set data.wait_for_stream_sync using DataConfig 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 DataConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data=DataConfig(wait_for_stream_sync=True))
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.data.wait_for_stream_sync)

2. Alternatively, set the value with a dict

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data={"wait_for_stream_sync": True})
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.data.wait_for_stream_sync)

Set the data freshness threshold for stream synchronization

You can set an optional data freshness threshold (in minutes) that helpers can use when waiting for stream synchronization.

Adjusting this threshold can help balance freshness guarantees with query latency by allowing queries to proceed when data is within an acceptable staleness window, even if streams are not fully synchronized. It is unset by default, which means data must be fully synchronized before queries run.

Tip

You can also disable waiting for stream synchronization entirely if you prefer faster query execution and can tolerate potentially stale data.

raiconfig.yaml

1. Set data.data_freshness_mins in raiconfig.yaml:

   connections:
     # ...
   
   data:
     data_freshness_mins: 5

2. Inspect the parsed config:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.data.data_freshness_mins)

Programmatic

Set data.data_freshness_mins using DataConfig or a plain Python dict. These examples assume you already have a valid connection configured through file discovery.

1. Set the freshness threshold with a typed config class:

   from relationalai.config import DataConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data=DataConfig(data_freshness_mins=5))
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value (in minutes):
   print(m.config.data.data_freshness_mins)

2. Alternatively, set the freshness threshold with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data={"data_freshness_mins": 5})
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value (in minutes):
   print(m.config.data.data_freshness_mins)

Enable or disable automatic enablement of change tracking on Snowflake tables

Set data.ensure_change_tracking to control whether PyRel data helpers attempt to ensure Snowflake change tracking is enabled on tables they read from, which is required for data stream creation and synchronization.

When enabled, helpers will try to turn on change tracking for any table they read from if it is not already enabled. This setting is disabled by default, which means helpers will not modify Snowflake tables and will error if change tracking is not already enabled when they try to create a stream.

Note

Only tables that you have OWNERSHIP privileges can be altered by this setting.

raiconfig.yaml

1. Set data.ensure_change_tracking in raiconfig.yaml:

   connections:
     # ...
   
   data:
     ensure_change_tracking: false

2. Inspect the parsed config:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.data.ensure_change_tracking)

Programmatic

Set data.ensure_change_tracking using DataConfig 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 DataConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data=DataConfig(ensure_change_tracking=False))
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.data.ensure_change_tracking)

2. Alternatively, set the value with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data={"ensure_change_tracking": False})
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.data.ensure_change_tracking)

Enable or disable column type checking during stream synchronization

Set data.check_column_types to control whether PyRel data helpers validate column types during data loading. It is enabled by default, which means helpers will check that incoming data types match the target table schema and fail if there is a mismatch or coercion issue.

Caution

Disabling column type checking can improve performance but allow data with type issues to load, which may lead to downstream errors or incorrect results. Use this setting with caution and consider keeping it enabled in CI and production jobs to catch data issues early.

raiconfig.yaml

1. Set data.check_column_types in raiconfig.yaml:

   connections:
     # ...
   
   data:
     check_column_types: true

2. Inspect the parsed config:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.data.check_column_types)

Programmatic

Set data.check_column_types using DataConfig 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 DataConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data=DataConfig(check_column_types=True))
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.data.check_column_types)

2. Alternatively, set the value with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data={"check_column_types": True})
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.data.check_column_types)

Set the data export URL type (internal vs external)

data.download_url_type selects which URL type helpers should request for export downloads: internal (default) URLs that are only accessible within Snowflake’s network, or external URLs that are accessible from outside Snowflake.

Setting the download URL to external can allow clients without network access to Snowflake (for example, those running on a local machine or in a different cloud) to access query results, but it requires that your Snowflake account is configured to allow external URLs and that you have network access to the external URL endpoints.

raiconfig.yaml

1. Set data.download_url_type in raiconfig.yaml:

   connections:
     # ...
   
   data:
     download_url_type: external

2. Inspect the parsed config:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.data.download_url_type)

Programmatic

Set data.download_url_type using DataConfig or a plain Python dict. These examples assume you already have a valid connection configured through file discovery.

1. Set the download URL type with a typed config class:

   from relationalai.config import DataConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data=DataConfig(download_url_type="external"))
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.data.download_url_type)

2. Alternatively, set the download URL type with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(data={"download_url_type": "external"})
   m = Model("MyModel", config=cfg)
   
   # Inspect the configured value:
   print(m.config.data.download_url_type)