> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prophecy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SurrogateKeyGenerator gem

> Add new column with monotonically-increasing surrogate key

The SurrogateKeyGenerator gem lets you add a *surrogate key* column to an input dataset.

A *surrogate key* is simply a unique, monotonically-increasing integer that serves as a key column for datasets that do not have a key.

To ensure that the key increments steadily across pipeline runs, the SurrogateKeyGenerator gem uses a file, known as the *key file* to store the last used key. For example, if the file lists the last used key as `5000`, the next row will start at `5001`. Once the pipeline run completes, the gem writes the last value used to the key file, so that the next run starts there.

## Parameters

To configure the SurrogateKeyGenerator gem, add the gem to the canvas, link it to an upstream gem, and enter information for the following parameters:

| Parameter | Description |
| - | - |
| Surrogate Column Name | The name for the new surrogate key column. |
| Key File Path | Path to key-tracking file. |
| Key Initial Value (optional) | The starting value for the surrogate key sequence. |

## Example

This example adds a new surrogate key column (`customer_sk`) to a customer dimension DataFrame.

The example:

* Creates a new column called `customer_sk`.
* Looks for a file located at `/mnt/keys/customer_sk.seq`
* Starts key generation at `1`.

### Input schema

| Column name | Type |
| - | - |
| customer\_id | string |
| name | string |
| email | string |

### Gem configuration

| Parameter | Example Value |
| - | - |
| Surrogate Column Name | `customer_sk` |
| Key File Path | `/mnt/keys/customer_sk.seq` |
| Key Initial Value | `1` |

### Output

| customer\_sk | customer\_id | name | email |
| - | - | - | - |
| 1 | C123 | Alice Wong | `alice@example.com` |
| 2 | C456 | Omar Davis | `omar@example.com` |
| 3 | C789 | Priya Shah | `priya@example.com` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.