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

# Populate relation

> Fill the empty cells of an existing relation (oneMany) column by matching a key column on this table against a key column on the linked table — the way to…

`populate_relation`

Fill the empty cells of an existing relation (oneMany) column by matching a key column on this table against a key column on the linked table — the way to turn imported text into record links in bulk. Runs as a dry run unless dryRun is false: the report says how many rows would link, how many match nothing, how many match more than one, and how many the column's filter rejects, before anything is written. Only empty cells are written: a cell that already holds links is left as it is (counted as unchanged when it already has the match, keptExisting otherwise). A match the column's relation filter does not allow for that row is not written (rejectedByFilter). Keys are lists and are matched exactly. Use several columns when one is not unique on its own (a term code is usually only unique alongside its codelist code). Re-running is idempotent, and a committed run can be undone.

## Parameters

**tableId** `string` *required*

**relationColumnId** `string` *required*

The oneMany column to fill.

**sourceColumnIds** `array\<string\>` *required*

Key column(s) on THIS table.

**targetColumnIds** `array\<string\>` *required*

The matching key column(s) on the LINKED table, in the same order.

**onAmbiguous** `string, enum: 'skip' | 'first' | 'fail'`

A key matching several rows. Default skip.

**onMissing** `string, enum: 'skip' | 'fail' | 'create'`

A key matching no row. Default skip. "create" adds the missing rows to the linked table and needs its key to be that table's identifier column alone.

**dryRun** `boolean`

Defaults to true. Report only; nothing is written.


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