Content Relationship

The content relationship Field allows you to create taxonomies, nested menus, and complex data structures. Content relationships allow you to link between documents internally and retrieve data.

Usage

Thumbnails

You can use content relationships to display linked data. For example, on a marketing page, you could have a list of blog posts with the posts’ titles, images, and descriptions.

On one custom type, include a content relationship Field for your link. In your API query, include a fetchLinks or GraphQuery API option to retrieve the data that you would like to display in your thumbnail. See more information on fetchLinks and GraphQuery below.

Taxonomies

Create a custom type for your taxonomy, such as “Author” or “Category.” On your content custom type (like “Blog Post” or “Article”), create a content relationship Field that links to your taxonomy custom type. Create taxonomy documents and then connect them from your content documents.

For example, if you have a blog, you’ll create a Blog Post custom type and an Author custom type. On each Blog Post document, you can link to an Author document. When you make your query to the API, you can include a fetchLinks or GraphQuery API option to retrieve the Author data to display the author’s name and photo in your Blog Post header. See below for more information on retrieving data from a content relationship.

To create an author page on your website, fetch your Author document and then query all Blog Posts that link to the Author document by doing a query by content relationship. See how to query by content relationship below.

Nested menus

Create a Menu custom type and a Child Menu custom type. On your Menu custom type, include a content relationship Field that links to your Child Menu custom type. Create your Child Menu documents and then create a Menu document that links to the Child Menu documents.

When you query your Menu document, include a fetchLinks or GraphQuery API option to retrieve the Child Menu documents. You’ll receive the data for your whole menu.

Complex data structures

Content relationships provide a flexible way to make complex data structures. See below for information on how to retrieve linked data with fetchLinks or GraphQuery. When creating complex data structures, remember that GraphQuery will only allow you to query three levels deep (document, parent document, grandparent document). However, you can always fetch deeply linked data with additional API requests.

To fetch documents by a content relationship field (for example, all of the Blog Posts that link to a specific author), you will need to provide the API ID of the linked document. For more information on constructing that query, see below.

API response example

Here is an API response example of a content relationship field:

{
  // ...
  "example_content_relationship": {
    "id": "XxnD3REAACYAk_CJ",
    "type": "page",
    "tags": ["…"],
    "slug": "vaporwave",
    "lang": "en",
    "uid": "unique_uid",
    "link_type": "Document",
    "isBroken": false
  }
}

Query by content relationship

You can query by a content relationship using the at, not, any, has, and missing filters.

To use the at, not, and any filters, pass the ID of the linked document.

const document = await client.get({
  filters: prismic.filter.at(
    "my.example_custom_type.example_content_relationship",
    "YesUgRIAACEA-UZD",
  ),
});

Retrieve data from a content relationship

You can fetch data from a document linked by a content relationship using the fetchLinks or GraphQuery API options:

client.getByType('blog_post', { fetchLinks: 'author.first_name' })