# Viewing and adding foreign keys
Foreign keys define relationships between tables. The value of a foreign key column in a table is the primary key of a row from a different table.
For example, a `transactions` table includes a `customer_id` column. The value of `customer_id` is a primary key value from the `id` column in the `customers` table.
A table can also have composite foreign keys that consist of multiple columns.
Tonic Structural uses foreign keys when it generates subsets and when it applies generators to primary keys or foreign keys.
During data generation, when [generators are assigned to primary key columns](https://docs.tonic.ai/app/generation/generators/generator-types/primary-key-generators), Structural ensures that the foreign keys are synchronized with the primary keys.
When Structural creates a subset, it [uses foreign keys to identify the related tables and rows ](https://docs.tonic.ai/app/generation/subsetting/subsetting-foreign-keys)to include in the subset.
Often, foreign key relationships are defined in the source database. When you have missing relationships or cannot define them in the source database, Structural offers a virtual foreign key tool to allow you to add additional foreign keys. This can ensure that all relationships are maintained. Structural only uses these virtual foreign keys during the data generation process. It does not write the virtual foreign keys to the destination database.
From **Foreign Keys** view, you can:
* [View the current foreign keys](#foreign-keys-view) (all license plans).
* [Add virtual foreign keys](#foreign-key-virtual-add) (Professional and Enterprise plans only).
To display **Foreign Keys** view:
* On the workspace management view, in the workspace navigation bar, click **Foreign Keys**.
* On **Workspaces** view, from the dropdown menu in the **Name** column, select **Foreign Keys**.
## Viewing the current foreign keys
On **Foreign Keys** view, the **View Foreign Key Relationships** tab contains the list of foreign keys in the source database.
For each foreign key:
* **Foreign Key** contains the name of the columns (`tableName.columnName`) that contain the foreign key values.
* **Primary Key** contains the name of the column (`tableName.columnName`) that contains the primary key value that is used to populate the foreign key column.
### Identifying virtual foreign keys
Virtual foreign keys that you added are displayed with a checkbox.
You can delete those keys. You cannot delete keys that are defined in the source database.
### Filtering the foreign keys
You can filter the foreign keys by the name of the foreign key column or the primary key column.
In the filter field, begin to type text that is in the column name. As you type, Structural filters the list.
### Sorting the foreign keys
You can sort the foreign keys by the name of the foreign key column or primary key column.
To sort the list:
1. Click the **Sort** dropdown for the column that you want to use to sort the list.
2. On the sort panel, click the sort order to use.
## Adding virtual foreign keys
{% hint style="info" %}
**Required license:** Professional or Enterprise
**Required workspace permission:** Configure virtual foreign keys
{% endhint %}
Tonic allows you to add virtual foreign keys to your source database. You would use this feature to add a specific foreign key that is missing, or if your source database does not use foreign keys.
You can either:
* Add the foreign keys one at a time from the **Add Foreign Key Relationships** tab.
* Upload a JSON file that contains the foreign keys.
If your database uses polymorphic keys (typically if you have a Ruby on Rails application), then you must use the JSON file upload to configure those keys.
You can also [create virtual foreign keys from a table details panel in **Subsetting** view](https://docs.tonic.ai/app/subsetting/subsetting-foreign-keys#subsetting-foreign-keys-adding).
You cannot create virtual foreign keys from a [child workspace](https://docs.tonic.ai/app/workspace/managing-workspaces/workspaces-inheritance). You can only create virtual foreign keys from a parent workspace.
### Adding virtual foreign keys from Add Foreign Key Relationships
You can configure virtual foreign keys from the **Add Foreign Key Relationships** tab.
You cannot configure polymorphic keys here. Polymorphic keys must be uploaded from a JSON file.
To add virtual foreign keys to your source database:
1. Under **Select Foreign Keys**, check the checkboxes to identify the foreign key fields. These are the fields that contain a value that is a primary key from another table.\
\
The **Select Foreign Keys** list contains the columns that are not already configured as foreign key columns.\
\
The top level of the **Select Foreign Keys** list displays the unique column names. This is the column name only, without the table name. Next to each column name is the number of times that it appears in the source database.\
\
You can use the sort dropdown list to sort the list either by the column name or by the number of times the column appears.\
\
You expand the column name to display the list of columns that have that name. This list uses the `tableName.columnName` format.\
\
For example, a database has a `customer_id` column in both the `sales` and `customers` tables. On the **Select Foreign Keys** tab, the top level entry is `customer_id`. Under `customer_id` are entries for `sales.customer_id` and `customers.customer_id`.
2. As you select and deselect columns, they are added to or removed from the **Foreign Key Preview** list.\
\
Under **Create New Foreign Key**, Structural also updates the number of keys to add.\
\
From **Foreign Key Preview**, to remove a selected column, click its delete icon. This performs the same function as unchecking the checkbox in the **Select Foreign Keys** list.
3. From the **Select Primary Key** dropdown list, select the column that provides the values for the selected foreign key columns.
4. To create the virtual foreign keys, click **Create *****n***** foreign keys**. *n* is the number of keys that are created, based on the number of foreign key columns that you selected.
### Uploading a JSON file of virtual foreign keys
You can upload a JSON file that contains the virtual foreign keys. For example, you can create a JSON file that you can use to populate virtual foreign keys in multiple workspaces that have the same source data structure.
If you already configured virtual foreign keys, then the uploaded virtual foreign keys replace the existing ones.
The virtual foreign key JSON also allows you to add polymorphic keys. You cannot add polymorphic keys from the **Add Foreign Key Relationships** tab.
On the **Foreign Key Relationships** view, to upload a foreign keys file:
1. Click **Upload Foreign Key JSON**. If you already have virtual foreign keys configured, then the button is **Update Foreign Key JSON**.
2. On the upload dialog, to search for and select the file, click **Browse**.
3. After you select the file, click **Upload**.
The uploaded keys are added to the **View Foreign Key Relationships** list. Those keys replace any existing virtual foreign keys.
### JSON format for the foreign key file
The foreign key JSON is an array of foreign key entries. Here is an example of a foreign key file that contains a single entry:
```
[
{
"fk_schema": "public",
"fk_table": "paystubs",
"fk_columns": ["employee_id"],
"target_schema": "public",
"target_table": "employees",
"target_columns": ["id"]
}
]
```
To illustrate the field values, we'll use the following example, which reflects the example entry above.
A `paystubs` table lists the pay stubs that were issued to employees. `paystubs` contains an `employee_id` field.
`employee_id` identifies the employee that received the pay stub. `employee_id` is a foreign key. It contains the value of the `id` field in `employees`, which is the primary key field for the `employees` table.
Both `paystubs` and `employees` are in the `public` schema.
In the foreign keys JSON, each entry contains the following fields.
* `fk_schema` - The name of the schema for the table that contains the foreign key. For our example, `fk_schema` is `public`.
* `fk_table` - The name of the table that contains the foreign key. For our example, `fk_table` is `paystubs`.
* `fk_columns` - An array that contains the names of the foreign key columns. In our example, the `fk_columns` array contains a single value, `employee_id`.
* `target_schema` - The name of the schema for the table that contains the referenced primary key. In our example, `target_schema` is `public`.
* `target_table` - The name of the table that contains the referenced primary key. In our example, `target_table` is `employees`.
* `target_columns` - An array that contains the names of the primary key columns. In our example, the `target_columns` array contains a single value, `id`.
### JSON format for composite keys
The ability to provide multiple columns in `fk_columns` and `target_columns` is used to support composite foreign keys.
`fk_columns` and `target_columns` must contain the same number of columns. The corresponding columns must be in the same order in both arrays.
For example, a `sales` table contains `sales_person_id` and `sales_manager_id`, which refer to the `id` and `manager_id` columns in the `employees` table.
In the JSON:
* `fk_table` is `sales`, and `fk_columns` is `[sales_person_id, sales_manager_id]`.
* `target_table` is `employees`, and `target_columns` is `[id, manager_id]`.
The entry for this example would look like:
```
[
{
"fk_schema": "public",
"fk_table": "sales",
"fk_columns": ["sales_person_id","sales_manager_id"],
"target_schema": "public",
"target_table": "employees",
"target_columns": ["id","manager_id"]
}
]
```
### JSON format for polymorphic keys
Some application types have polymorphic keys. Polymorphic keys allow a single column in one table to contain foreign key values that refer to primary keys from multiple other tables. These types of keys cannot be represented in a traditional relational database, but are common in application frameworks such as Ruby on Rails.
For example, a person can have multiple addresses, and a company can have multiple addresses. To support this without complicated joins between tables, the addresses table includes the following columns:
* A column that contains the identifier of the company or the person that the address belongs to.
* Another column that identifies whether the identifier is a company or a person.
For example, the `people` table contains:
| id | first_name | last_name |
|---|
| 1 | John | Doe |
| 2 | Mary | Smith |
The `companies` table contains:
| id | company_name |
|---|
| 1 | My Company |
| 2 | Example Company |
The `addresses` table contains:
| id | address | address_owner_id | address_owner_type |
|---|
| 1 | 123 Main Street | 1 | Person |
| 2 | 234 Elm Street | 1 | Company |
In the `addresses` table, to identify the address owner:
* The `address_owner_id` column contains an `id` value from either the `people` or `companies` table.
* The `address_owner_type` column identifies whether the identifier is a person or a company.
The value of `address_owner_id` is `1` for both records. However, address 1 belongs to John Doe, and address 2 belongs to My Company.
Each entry in the polymorphic keys JSON identifies the fields that contain the foreign key values and the foreign key type. It also lists the foreign key types, and identifies the source of the identifier for that foreign key type.
The following is the JSON for the example above:
```
[
{
"fk_table": "addresses",
"fk_schema": "public",
"fk_columns": ["address_owner_id"],
"nullable": false,
"polymorphic_target": {
"fk_type_column": "address_owner_type",
"types": {
"Person": {
"target_schema": "public",
"target_table": "people",
"target_columns": ["id"]
},
"Company": {
"target_schema": "public",
"target_table": "companies",
"target_columns": ["id"]
}
}
}
}
]
```
Each entry contains the following fields:
* `fk_table` - The name of the table that contains the foreign key values. In our example, this is the `addresses` table.
* `fk_schema` - The name of the schema for the table that contains the foreign key. In our example, the schema is `public`.
* `fk_columns` - An array that contains the names of the columns that contain the foreign key values. In our example, the value is `address_owner_id`.
* `nullable` - Whether the foreign key column is nullable.
* `polymorphic_target` - Identifies the target types and the identifier source for each type.
`polymorphic_target` contains the following fields:
* `fk_type_column` - In the table that contains the foreign key, the name of the column that contains the foreign key type. In our example, this is the `address_owner_type` column in `addresses`.
* `types` - A list of the target types.
Each entry in `types` identifies the name of the type. In our example, our types are `Person` and `Company`. Note that these are the values of the type column in the polymorphic table, not necessarily the names of the tables they point to. For example, the `Person` type refers to the `people` table.
Each type has the following attributes:
* `target_schema` - The schema that contains the target table. In our example, the tables for both types belong to the `public` schema.
* `target_table` - The table that contains the primary key value. In our example, for the `Person` type, the target table is `people`. For the `Company` type, the target table is `companies`.
* `target_columns` - An array containing the column that contains the primary key value. In our example, the name of the identifier column in both tables is `id`.
## Downloading virtual foreign keys
If you created virtual foreign keys, then you can download those keys to a JSON file. For example, you might want to upload the same set of virtual foreign keys to another workspace that uses the same source data.
To download the virtual foreign keys, click **Download Foreign Key JSON**.
## Deleting a virtual foreign key
You can delete virtual foreign keys. You cannot delete foreign keys that are defined in the source database.
To delete an individual virtual foreign key, click its delete icon.
To delete multiple virtual foreign keys:
1. Check the checkbox next to each virtual foreign key to delete.
2. Click **Bulk Delete**.