Entity relationships are a powerful tool that allow you to connect entities in the Knowledge Graph. When a set of entities are related to each other, that entire set of data is immediately accessible in your frontend application — fetchable both server-side for Pages and client-side for Search.

Common Pages Use Cases

There are many reasons to want to link entities together. For example:

Fetch data between directly related entities. If you are building a product page, you could use relationships to display all location entities at which that product is available.

Fetch data from entities multiple hops away through an intermediary relationship. If you are building a doctor page, given the Knowledge Graph setup below, you could access the promotion entity through a multi-hop relationship to conditionally render promotion-specific content.

The relationship system is extremely powerful — you can pull related data from entities as many hops away as desired.

Organize your data for easier management (e.g., bulk editing). Relationships allow you to update one entity and propagate that update to all entities related to it. In the example below, you can define one menu and relate all restaurants to it, as opposed to defining menu items on each restaurant entity individually.

Setting Up a Relationship

To use relationships in your Pages frontend, you must:

1. Define an entity relationship custom field (refer to the Linking Entities unit to learn more).
2. Populate data in the Knowledge Graph to relate a set of entities to each other.
3. Reference that field in your stream configuration (see below).

Update Your Stream Configuration

To fetch relationship data in your Pages frontend, add the entity relationship field to your stream configuration. You must explicitly reference each field you want streamed to your document from each related entity.

For example, assume the related FAQs for a given entity are configured as shown:

The stream configuration must be updated to reference the question and answer of each related FAQ entity:

export const config: TemplateConfig = {
  stream: {
    $id: "location-stream",
    fields: [
      "id",
      "uid",
      "meta",
      "name",
      "address",
      "mainPhone",
      "description",
      "hours",
      "slug",
      "geocodedCoordinate",
      "services",
      "c_featuredFAQs.question",   // new
      "c_featuredFAQs.answer"      // new
    ],
    filter: {
      entityTypes: ["location"],
    },
    localization: {
      locales: ["en"],
      primary: false,
    },
  },
};

If you run npm run dev during local development and inspect your localData folder, you will see this related data available in your stream documents. From there, you can pass that array to your component and easily render your related data.

Note: You must explicitly reference each field you want streamed from each related entity. Adding c_featuredFAQs.question and c_featuredFAQs.answer to your stream configuration ensures data from those fields is returned. It is not sufficient to only include c_featuredFAQs.

Pages will return an error if you include both the top-level name of the entity list and a field simultaneously — for example, including both c_featuredFAQs and c_featuredFAQs.question will cause an error. Reference only c_featuredFAQs.question.