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

# Onboarding configuration

An onboarding configuration defines how a datasource is prepared for training. An onboarding job runs that configuration and produces a dataset. Create the configuration, run the job and check the resulting dataset, then create a workspace to organise model development.

> **Note**
>
> Before choosing onboarding settings, review [Prepare data](/ui-guides/data/prepare-data), especially the guidance on missing values, categorical values and targets. Use those preparation choices to guide preprocessing.

## Before you begin

Have an **AVAILABLE** datasource, its data schema and a processing compute configuration ready. Identify the prediction type and target fields for the model before creating the onboarding configuration. Use one target for single-output or multi-class predictions, and more than one target for multi-valued output predictions.

The Datasets area has three tabs: **Configurations** stores onboarding settings, **Onboarding Jobs** lists processing runs, and **Datasets** lists the resulting datasets.

![Datasets tabs and existing artifacts](/_fern-files/_img/e8f9e221630d50048ddbcfec91c88e37b13ebaeffe30f5cb1a3cef01fbbdeed1.webp)

## Configure initial dataset onboarding

1. Open **Data Lab > Datasets > Configurations**, then select **Create**.

2. Enter a **Configuration name** and select **Initial** for the first onboarding of a dataset.

3. Choose the **Prediction type** for your task. Use **Classification** for a class or category, or **Regression** for a numeric value. The example uses Classification.

4. Select the **Data schema**, then select the model's target field or fields in **Targets** to match the intended outputs. The payments fraud example uses **fraud_flag**.

5. Review the encoding, sharding, masking and additional settings before selecting **Create**.

6. Return to **Configurations** and verify that the saved configuration is present before creating a job.

![Initial onboarding configuration with fraud\_flag selected](/_fern-files/_img/ed18fdd253de3225f2b9fec2f76de5e06f60fffed0aab8d89c08e569b43707c2.webp)

The example shows **One hot encoding max categories** as **64** and **Infrequency threshold** as **1**. These control categorical encoding and the treatment of infrequent categories. The **Shards** control shows **256m**, a memory limit per shard. Use its mode selector to choose a memory limit or a shard count, and review **Sharding strategy** for your prediction task.

## Review processing settings

Review the masking fractions and additional preprocessing controls below. Keep the defaults unless your data requires a specific change. Decide how to handle unseen categories, missing values and categorical whitespace before saving the configuration.

| **Control**              | **Example value or purpose**                                                              |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| Mask category fraction   | 0.37                                                                                      |
| Mask fraction            | 0.8                                                                                       |
| Mask median fraction     | 0.15                                                                                      |
| Mask rows fraction       | 0.3                                                                                       |
| Handle unseen categories | Enabled in the example; enables masking for categories not seen during training.          |
| Impute                   | Disabled in the example; controls whether missing values are imputed.                     |
| Encoding strategy        | Select Stream or Shard as the encoding strategy for the onboarding configuration.         |
| Strip categories         | Disabled in the example; removes leading and trailing whitespace from categorical values. |

![Masking fractions and additional processing settings](/_fern-files/_img/2058a9ec8aa24e897a3454eca46709cb8e22fccd18e3ec0064201746efcc3549.webp)

## Choose categorical and missing-value handling

For encoding examples and the relationship between schema settings and onboarding, see [Encoding](/ui-guides/data/encoding).

| Control                         | How to choose                                                                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| One hot encoding max categories | Threshold beyond which categorical fields switch from one-hot to target encoding. The UI starts at 64; review the number of distinct categories in your data. |
| Infrequency threshold           | Groups infrequent categories under an infrequent-category representation. The UI starts at 1.                                                                 |
| Handle unseen categories        | Enables masking for categories absent during training. Keep prediction-time input conventions consistent with this choice.                                    |
| Strip categories                | Removes leading and trailing whitespace. Enable it when that whitespace is incidental, after checking whether trimming would merge meaningful categories.     |
| Impute                          | Controls imputation of missing values. Decide whether missingness should be cleaned before ingestion or handled during onboarding.                            |
| Encoding strategy               | Choose **Stream** or **Shard** when the workflow requires an explicit strategy; otherwise leave the optional choice unset.                                    |

## Choose sharding

Sharding divides the data for processing and training. **Shards** has two modes: **Max. Memory Per Shard** takes a memory value such as `256m` or `1g`; **Shards** takes a positive count. Switching mode resets the value, so check it again before creating the configuration.

| Sharding strategy                       | Intended use                                                                                                                     |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Proportionate                           | Retain class proportions when dividing classification data. This is the default for classification when no strategy is supplied. |
| Disproportionate Minority Oversampling  | Increase representation of minority classes for an imbalanced classification task.                                               |
| Disproportionate Majority Undersampling | Reduce representation of majority classes for an imbalanced classification task.                                                 |
| Random                                  | Divide data using random assignment.                                                                                             |
| Random Approximate                      | Use approximate random sharding. This is the default for regression when no strategy is supplied.                                |

Choose a disproportionate strategy deliberately and evaluate against a population that represents your intended use. Changing the balance used in training does not change the population against which performance should be assessed.

## Understand masking settings

Masking settings determine how observations and categorical values are sampled for masking during preprocessing. Their values are fractions, not percentages entered as whole numbers.

| Control                | Purpose                                                  |
| ---------------------- | -------------------------------------------------------- |
| Mask category fraction | Fraction used to select categorical columns for masking. |
| Mask fraction          | Fraction used to mask the selected categorical column.   |
| Mask median fraction   | Fraction sampled per categorical value.                  |
| Mask rows fraction     | Fraction sampled from each shard and target for masking. |

Start with the form's values unless the preprocessing task calls for a deliberate change. Review the resulting dataset's distribution and special categories before training.

## Create an incremental configuration

Choose **Incremental Update** when preparing settings for an existing dataset. The form retains masking, missing-value and additional preprocessing controls while the dataset's existing context supplies the prediction task. Initial-only settings, including the target, prediction type and sharding setup, are not entered again.

Save this configuration separately and select it in an incremental onboarding job. Use **Initial** when you need a new dataset with a different prediction task.

## Review and reuse a configuration

Open the saved configuration and verify its type and preprocessing choices. For an initial configuration, check the target and prediction type. Select a configuration matching the job type when running onboarding; saving it alone does not process a datasource.

## Next steps

Continue to [Onboarding jobs](/ui-guides/data/onboarding-jobs).