> 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

Use these settings to control how Kumo Relational gathers data for a prediction, balances context size against latency, applies time boundaries, and produces its output.
Pass each setting directly to `client.relational(graph).predict(...)`.
Start with the defaults, then change only the settings that address a specific performance or output need.

## Neighborhood sampling

Kumo Relational gathers context for each entity being predicted by sampling its **relational neighborhood**: rows connected to that entity through table relationships.
A **hop** follows one table relationship, so two hops can include rows reached through two successive relationships.
By default, Kumo Relational samples two hops.

Use `num_neighbors` to control both the number of hops and the **fan-out**, or maximum number of neighboring rows sampled 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`.

> **Warning**
>
> Larger fan-outs and deeper neighborhoods can substantially increase sampling time, memory use, and request size.
> If the sampled data assembled for a request exceeds the 30 MB context 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 sets the maximum number of **in-context examples**, which are historical examples included in the request to help the model make its prediction.
When `num_neighbors` is not specified, the run mode also provides the default fan-out for each of the two default hops.
Choose a mode based on the maximum context your request needs; modes with larger limits can increase request size and latency.

| 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

Use these explicit arguments to select prediction entities and control request processing.
Most requests only need `indices`; keep the other defaults unless you need explanations, batching, or additional retries.

| Setting       | Effective default | Meaning                                                                                                                                                                                                                            |
| ------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `indices`     | `None`            | Primary keys of the entity rows to predict; 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, and `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 differs 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 these settings to control which points in time the prediction and its supporting examples can use.
They are especially important for historical evaluation, where data from after the prediction time must not influence the result.

| 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

Use `inference_config` for advanced control over how Kumo Relational combines and varies multiple estimators.
An **estimator** is one component prediction in the ensemble, the group whose results are combined into the final output.
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

These fields control the number and variation of estimators for every supported prediction type.

| 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

Classification tasks also support varying the order of output classes across estimators.

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

### Regression and forecasting fields

Regression and forecasting tasks support additional controls for transforming numeric targets and summarizing the predicted distribution.

| 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](/kumo-relational/user-guide/work-with-prediction-results/prediction-results).

## Output and sampling controls

Use these settings when you need model embeddings, reproducible sampling, or additional attempts to find valid context labels.

| 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.