Configuration

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(...):

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.

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.

The default run mode is fast.

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.

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.

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

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.

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.

Classification field

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

Regression and forecasting fields

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

When output_type="quantiles", prediction results include conditional Q_<Level> columns. Refer to Prediction Results.

Output and sampling controls

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

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.