> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Configuration

> Configure neighborhood sampling, run modes, timing, and inference behavior for Kumo Relational

Configure predictions by passing settings directly to `client.relational(graph).predict(...)`. The following sections describe the available settings, their defaults, and how to use them.

## Neighborhood sampling

Kumo Relational samples a relational neighborhood around each prediction entity. By default, it samples **two hops**.

The `num_neighbors` parameter controls both the number of hops and the maximum neighbor fan-out at each hop:

* The number of entries determines the number of hops.
* Each entry specifies the maximum number of neighbors sampled at that hop. For example, `num_neighbors=[16, 8, 4]` requests three hops, with fan-outs of 16, 8, and 4.
* Kumo Relational supports at most six hops.

To change the neighborhood, pass `num_neighbors` to `client.relational(graph).predict(...)`:

```python
result = client.relational(graph).predict(
    query,
    indices=[870],
    num_neighbors=[16, 8, 4],
)
```

This example samples three hops with fan-outs of 16, 8, and 4.

`num_hops` has an effective default of `2` and accepts values from 1 through 6. When you provide `num_neighbors`, its length determines the sampling depth and takes precedence over `num_hops`.

Larger fan-outs and deeper neighborhoods can substantially increase sampling time, memory use, and request size. If the materialized context exceeds the 30 MB limit, reduce `num_neighbors`, remove unnecessary columns or tables, or select a run mode with a smaller context limit.

## Run modes and defaults

The `run_mode` parameter controls the maximum number of in-context examples. When `num_neighbors` is not specified, the run mode also provides the default fan-out for each of the two default hops.

| Run mode | Maximum context examples | Default `num_neighbors` |
| -------- | -----------------------: | ----------------------- |
| `debug`  |                      100 | `[16, 16]`              |
| `fast`   |                    1,000 | `[32, 32]`              |
| `normal` |                    5,000 | `[64, 64]`              |
| `best`   |                   10,000 | `[64, 64]`              |

The default run mode is `fast`.

```python
result = client.relational(graph).predict(
    query,
    indices=[870],
    run_mode="fast",
)
```

Run-mode values are lowercase. For link-prediction tasks, Kumo Relational uses the `fast` neighborhood defaults regardless of the selected run mode.

## Prediction settings

The following settings are explicit arguments to `client.relational(graph).predict(...)`.

| Setting       | Effective default | Meaning                                                                                                                                                                                                                                |
| ------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `indices`     | `None`            | Entity primary keys for which to generate predictions. When provided, these values override entity IDs embedded in the PQL query.                                                                                                      |
| `run_mode`    | `"fast"`          | Controls the maximum in-context examples and the default neighborhood fan-out.                                                                                                                                                         |
| `explain`     | `False`           | Requests an explanation in addition to the prediction. Explainability supports one entity per request; `normal` and `best` are reset to `fast`.                                                                                        |
| `batch_size`  | `None`            | Splits prediction entities into batches when set to a positive integer or `"max"`.                                                                                                                                                     |
| `num_retries` | `1`               | Application-level retries for a failed relational prediction request or batch, including a request that resolves to a single batch. This is distinct from `RelationalClient(max_retries=...)`, which controls transport-level retries. |

```python
result = client.relational(graph).predict(
    query,
    indices=customer_ids,
    run_mode="fast",
    explain=False,
    batch_size="max",
    num_retries=1,
)
```

## Time controls

Use the following settings to control prediction and context time boundaries.

| Setting               | Effective default | Meaning                                                                                                            |
| --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `anchor_time`         | `None`            | Prediction reference time. `None` uses the maximum timestamp in the data; `"entity"` uses each entity's timestamp. |
| `context_anchor_time` | `None`            | Maximum anchor time for context examples. When omitted, `anchor_time` determines the context boundary.             |
| `use_prediction_time` | `False`           | Includes the prediction anchor timestamp as an input feature.                                                      |
| `lag_timesteps`       | `0`               | Specifies the number of previous target windows to include as lagged features.                                     |

Use a `pandas.Timestamp` object for an explicit time boundary:

```python
import pandas as pd

result = client.relational(graph).predict(
    query,
    indices=[870],
    anchor_time=pd.Timestamp("2025-06-01T00:00:00Z"),
    context_anchor_time=pd.Timestamp("2025-03-01T00:00:00Z"),
    use_prediction_time=False,
    lag_timesteps=3,
)
```

For historical predictions, ensure the request cannot access events after the selected anchor or context boundary.

## Inference configuration

Pass `inference_config` as a dictionary. Kumo Relational selects the applicable configuration type from the prediction task.

```python
result = client.relational(graph).predict(
    query,
    indices=[870],
    inference_config={
        "num_estimators": 4,
        "column_shuffle": True,
        "category_shuffle": True,
        "hop_shuffle": True,
    },
)
```

### Common fields

| Field              | Default | Meaning                                                                |
| ------------------ | ------- | ---------------------------------------------------------------------- |
| `num_estimators`   | `1`     | Number of estimators in the ensemble. Accepted values are 1 through 4. |
| `column_shuffle`   | `False` | Varies column order across estimators.                                 |
| `category_shuffle` | `False` | Varies category order across estimators.                               |
| `hop_shuffle`      | `False` | Varies subgraph depth across estimators.                               |

### Classification field

| Field           | Default | Meaning                               |
| --------------- | ------- | ------------------------------------- |
| `class_shuffle` | `False` | Varies class order across estimators. |

### Regression and forecasting fields

| Field               | Default        | Meaning                                                                                                                            |
| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `target_transforms` | `["quantile"]` | Target transformations used by the estimators. Supported entries are `"clip"`, `"power"`, `"quantile"`, and `None` (no transform). |
| `output_type`       | `"median"`     | Summarizes the output distribution as `"median"`, `"mean"`, or `"quantiles"`.                                                      |

When `output_type="quantiles"`, prediction results include conditional `Q_<Level>` columns. Refer to [Prediction Results](/rfm/prediction-results).

## Output and sampling controls

| Setting             | Effective default | Meaning                                                                                                                                                |
| ------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `return_embeddings` | `False`           | Includes the model embedding associated with each prediction example.                                                                                  |
| `random_seed`       | `42`              | Seed used for pseudo-random sampling and request materialization.                                                                                      |
| `max_pq_iterations` | `10`              | Maximum iterations used to collect valid labels for context examples. Increase it only when strict entity filters make valid labels difficult to find. |

```python
result = client.relational(graph).predict(
    query,
    indices=[870],
    return_embeddings=True,
    random_seed=7,
    max_pq_iterations=20,
)
```

Use the same explicit `random_seed` for reproducible sampling across processes. Set `random_seed=None` for unseeded sampling; this also disables session reuse. SQL samplers that cannot apply a seed issue a warning that the seed is ignored and repeated calls can differ.

Unknown extra prediction keyword arguments are passed through to the relational engine. Unknown keys inside `inference_config` are rejected during configuration validation.

## Choose settings conservatively

Start with the defaults. Change one dimension at a time and measure the effect on latency, request size, and prediction quality with representative data.

If a request becomes too large, first reduce `num_neighbors`. You can also reduce the run mode, remove unused columns or tables, or split entity IDs into batches.