Configure execution behavior

Configure PyRel client requests to retry transient failures, send request logs through Python logging, or collect in-memory request metrics for debugging. If you don’t need those behaviors, you can usually leave the execution settings alone. This guide shows how to configure these optional settings in raiconfig.yaml and in Python code.

Prerequisites

• 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 Install and run PyRel for instructions.

What execution configuration covers

The execution settings control SQL and HTTP requests made through PyRel’s client. They apply to requests that use this client, not to every operation in a model workflow.

• Retries repeat client requests after errors classified as transient, with a configurable delay between attempts.
• Execution logs report client-request outcomes and timings through Python logging.
• Metrics collection records client-request counters and timings in Python memory.

Note that:

Some operations submit SQL directly to Snowflake, such as deployments or refreshes, without using this client.

• execution.retries does not retry an entire deployment or configure scheduled refresh retries.
• execution.logging does not provide a complete deployment or refresh log.
• execution.metrics does not collect persistent metrics for a deployed model.

For deployment status and refresh diagnostics, see Monitor a deployed model and Troubleshoot a deployed model.

Use the sections below to configure these settings in raiconfig.yaml or in Python code.

Related resources:

• Choose a configuration method

Configure retries

Turn on retries when you want PyRel’s client to repeat a request after a short-lived problem. Retries are disabled by default. They apply only when the client classifies an error as retryable; they do not retry arbitrary model errors or restart a failed deployment.

When enabling retries, start with the default retry settings. Only change the other settings if you need a different attempt limit or backoff window.

To configure retries:

raiconfig.yaml

1. Enable retries in raiconfig.yaml:

   connections:
     # ...
   
   execution:
     retries:
       enabled: true

   If you only want the default retry behavior, you can stop here. PyRel keeps the default values for the other retry settings.

   Note

   Retries are disabled by default. Set enabled: false only if you want to turn them off explicitly.

2. Optionally tune the other retry settings:

   Skip this step unless the default values are not a good fit for your workload. By default, PyRel uses max_attempts: 3, base_delay_s: 0.25, max_delay_s: 5.0, and jitter: 0.2.

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

   In this example:

   • max_attempts defaults to 3. PyRel counts the first try as one of those attempts.
   • base_delay_s defaults to 0.25 seconds. PyRel increases the wait time after each failed try.
   • max_delay_s defaults to 5.0 seconds. PyRel does not wait longer than this before it tries again.
   • jitter defaults to 0.2. This varies the wait time so many requests do not all retry at the exact same moment.

3. Confirm that PyRel loaded your retry settings:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.execution.retries.enabled)
   print(m.config.execution.retries.max_attempts)
   print(m.config.execution.retries.base_delay_s)
   print(m.config.execution.retries.max_delay_s)
   print(m.config.execution.retries.jitter)

   Note that:

   • This step confirms that PyRel loaded the retry policy you configured.
   • A real retry only occurs when a request fails with a retryable transient error, so this example does not demonstrate a retry in progress.

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. Enable retries in code:

   from relationalai.config import ExecutionConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(
      execution=ExecutionConfig(
         retries=ExecutionConfig.RetriesConfig(
            enabled=True,
         ),
      ),
   )
   m = Model("MyModel", config=cfg)
   
   print(m.config.execution.retries.enabled)

   If you only want the default retry behavior, you can stop here. PyRel keeps the built-in values for the other retry settings. Retries are disabled by default. Set enabled=False only if you want to turn them off explicitly.

   You can also configure the same setting with a dict:

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(
      execution={
         "retries": {
            "enabled": True,
         },
      },
   )
   m = Model("MyModel", config=cfg)
   
   print(m.config.execution.retries.enabled)

2. Optionally tune the other retry settings:

   Skip this step unless the default values are not a good fit for your workload. By default, PyRel uses max_attempts=3, base_delay_s=0.25, max_delay_s=5.0, and jitter=0.2.

   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)
   
   print(m.config.execution.retries.enabled)
   print(m.config.execution.retries.max_attempts)
   print(m.config.execution.retries.base_delay_s)
   print(m.config.execution.retries.max_delay_s)
   print(m.config.execution.retries.jitter)

   You can also configure the same settings with a 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)
   
   print(m.config.execution.retries.enabled)
   print(m.config.execution.retries.max_attempts)
   print(m.config.execution.retries.base_delay_s)
   print(m.config.execution.retries.max_delay_s)
   print(m.config.execution.retries.jitter)

In this example:

• max_attempts sets the total number of client-request attempts, including the first try.
• base_delay_s sets the initial wait time between tries. PyRel increases that wait time after each failed try.
• max_delay_s sets the longest time PyRel will wait before it tries again.
• jitter varies the wait time so many requests do not all retry at the exact same moment.

Note that:

• These checks confirm that PyRel loaded the retry policy you configured.
• A real retry only occurs when a request fails with a retryable transient error, so these examples do not demonstrate a retry in progress.

Related resources:

• Create configuration in code
• ExecutionConfig API reference
• Configure compilation behavior

Enable or disable execution logs

Execution logs are structured messages about requests made through PyRel’s client. Enable them when you need client-request outcomes and timings for debugging. Turning this on makes the logs available through Python’s logging system, so you also need to configure Python logging to display them.

Select the tab below for your preferred config method and follow the steps to enable execution logs, confirm that PyRel loaded the setting, and configure Python logging.

raiconfig.yaml

1. Set execution.logging in raiconfig.yaml:

   connections:
     # ...
   
   execution:
     logging: true

2. Confirm that PyRel loaded the configured value:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.execution.logging)

3. Configure Python logging to display execution logs:

   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. Create the config with a typed config class:

   from relationalai.config import ExecutionConfig, create_config
   
   cfg = create_config(execution=ExecutionConfig(logging=True))

2. Alternatively, create the config with a dict:

   from relationalai.config import create_config
   
   cfg = create_config(execution={"logging": True})

3. Confirm that PyRel loaded the configured value:

   from relationalai.semantics import Model
   
   m = Model("MyModel", config=cfg)
   
   print(m.config.execution.logging)

4. Configure Python logging to display execution logs:

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

Note that:

• The config check confirms that PyRel loaded execution.logging.
• These steps configure logging but do not make a client request. Logs are emitted when a request passes through the configured client.
• Request outcome logs include the request type, operation name, elapsed time, and extra context attached to the request.
• These logs summarize what happened, but they do not show the full SQL text or full HTTP request details such as headers or bodies.
• If a request fails, check its exception message for more detailed error information.
• These logs cover client requests, not every deployment operation or scheduled refresh.

Related resources:

• ExecutionConfig API reference
• Configure compilation behavior

Enable or disable metrics collection

Execution metrics are counters and timings for requests made through PyRel’s client. Enable them when you need to inspect client-request attempts, successes, failures, and timings. PyRel keeps these metrics in the current Python process and does not export them automatically.

Select the tab below for your preferred config method and follow the steps to enable execution metrics and confirm that PyRel loaded the setting.

raiconfig.yaml

1. Set execution.metrics in raiconfig.yaml:

   connections:
     # ...
   
   execution:
     metrics: true

2. Confirm that PyRel loaded the configured value:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.execution.metrics)

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. Create the config with a typed config class:

   from relationalai.config import ExecutionConfig, create_config
   
   cfg = create_config(execution=ExecutionConfig(metrics=True))

2. Alternatively, create the config with a dict:

   from relationalai.config import create_config
   
   cfg = create_config(execution={"metrics": True})

3. Confirm that PyRel loaded the configured value:

   from relationalai.semantics import Model
   
   m = Model("MyModel", config=cfg)
   
   print(m.config.execution.metrics)

Note that:

• The config check confirms that PyRel loaded execution.metrics.
• These steps configure metrics collection but do not make a client request or collect request metrics.
• The metrics are held in Python memory and do not persist after the process exits.
• They do not measure every deployment operation or collect metrics for scheduled refreshes.

Related resources:

• ExecutionConfig API reference
• Configure compilation behavior