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

# Document relations

> Automatically enrich search results with related data from other indexes using foreign keys.

Foreign keys let you link documents across indexes so that search results are automatically enriched with related data. Instead of duplicating information, you store it once in a dedicated index and reference it by ID.

For example, a `movies` index can reference actors by ID. When you search for movies, Meilisearch automatically replaces the actor IDs with full actor documents from the `actors` index. This approach also works with [multi-search](/capabilities/multi_search/overview) when querying across related indexes.

<Warning>
  Foreign keys is an experimental feature. Its API and behavior may change in future releases. It is not supported in remote sharding environments.
</Warning>

## Step 1: Enable the experimental feature

Foreign keys must be activated through the [experimental features endpoint](/reference/api/experimental-features/list-experimental-features) before you can use them:

<CodeGroup>
  ```bash theme={null}
  curl \
    -X PATCH 'MEILISEARCH_URL/experimental-features' \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "foreignKeys": true
    }'
  ```
</CodeGroup>

## Step 2: Create your related index

Add documents to the index you want to reference. In this example, create an `actors` index with actor data:

<CodeGroup>
  ```bash theme={null}
  curl \
    -X POST 'MEILISEARCH_URL/indexes/actors/documents' \
    -H 'Content-Type: application/json' \
    --data-binary '[
      { "id": 1, "name": "Tom Hanks", "born": 1956 },
      { "id": 2, "name": "Robin Wright", "born": 1966 },
      { "id": 3, "name": "Gary Sinise", "born": 1955 }
    ]'
  ```
</CodeGroup>

## Step 3: Configure foreign keys in the main index

Use the settings endpoint to define which fields contain foreign references and which index they point to:

<CodeGroup>
  ```bash theme={null}
  curl \
    -X PATCH 'MEILISEARCH_URL/indexes/movies/settings' \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "foreignKeys": [
        {
          "fieldName": "actors",
          "foreignIndexUid": "actors"
        }
      ]
    }'
  ```
</CodeGroup>

This tells Meilisearch that the `actors` field in the `movies` index contains IDs that reference documents in the `actors` index.

## Step 4: Add documents with foreign IDs

Add documents to your main index. Use arrays of IDs for the foreign key field:

<CodeGroup>
  ```bash theme={null}
  curl \
    -X POST 'MEILISEARCH_URL/indexes/movies/documents' \
    -H 'Content-Type: application/json' \
    --data-binary '[
      { "id": 1, "title": "Forrest Gump", "actors": [1, 2, 3] },
      { "id": 2, "title": "Cast Away", "actors": [1] }
    ]'
  ```
</CodeGroup>

## Step 5: Search and see hydrated results

When you search the `movies` index, Meilisearch automatically replaces foreign IDs with full documents from the referenced index:

<CodeGroup>
  ```bash theme={null}
  curl \
    -X POST 'MEILISEARCH_URL/indexes/movies/search' \
    -H 'Content-Type: application/json' \
    --data-binary '{ "q": "forrest" }'
  ```
</CodeGroup>

Without foreign keys, a result would look like this:

<CodeGroup>
  ```json theme={null}
  {
    "id": 1,
    "title": "Forrest Gump",
    "actors": [1, 2, 3]
  }
  ```
</CodeGroup>

With foreign keys configured, the same result is automatically hydrated:

<CodeGroup>
  ```json theme={null}
  {
    "id": 1,
    "title": "Forrest Gump",
    "actors": [
      { "id": 1, "name": "Tom Hanks", "born": 1956 },
      { "id": 2, "name": "Robin Wright", "born": 1966 },
      { "id": 3, "name": "Gary Sinise", "born": 1955 }
    ]
  }
  ```
</CodeGroup>

## Limitations

* **Experimental**: This feature may change or be removed in future versions.
* **No remote [sharding](/resources/self_hosting/sharding/overview)**: Foreign keys are not supported in environments using remote sharding.
* **One direction**: Hydration works from the main index to the referenced index. The referenced index does not automatically link back.

## Next steps

<CardGroup cols={2}>
  <Card title="Foreign keys settings API" href="/reference/api/settings/get-foreignkeys">
    Full API reference for foreign key settings
  </Card>

  <Card title="Experimental features API" href="/reference/api/experimental-features/list-experimental-features">
    Enable and manage experimental features
  </Card>

  <Card title="Indexing overview" href="/capabilities/indexing/overview">
    Learn more about how indexing works in Meilisearch
  </Card>
</CardGroup>