Take part in the GraphQL Challenges Survey 2023

Using references

OverviewAnchor

References are relations between two or more content entries that you can create in Hygraph.

This document gets into how to use the different reference types in the Hygraph app.

What you can doAnchor

  • You can use the reference field in the Content editor to connect content entries to one another according to schema configuration.

Examples of this could be linking an Author to a Blog Post, or a Category to a Product.

Reference typesAnchor

There are four different reference types according to reference cardinality, which determines if it will be possible to connect one or many entries to the parent entry, as well as the directions of that relation.

  • One to one references: They allow adding a reference to one content entry from the model configured as referenceable. An example of this reference type could be the relation between a country and its capital. Each country has only one capital, and each capital belongs to only one country.
  • One to many references: They allow adding references to multiple content entries from the model configured as referenceable. An example of this reference type could be an author that is related to many blog posts.
  • Many to many references: They allow adding references to multiple content entries from the different models configured as referenceable. An example of this reference type could be the relation between product and category. A product can belong to multiple categories and the category may also have many products linked to it.
  • Many to one references: They allow adding references to multiple content entries of the parent model to the model configured as referenceable above. An example of this reference type could be a number of blog posts related to a single author.

How to use referencesAnchor

References are used in similar ways, irrespective of their type. In general terms, you have the option to add an existing content entry, or create & save a new one.

Depending on reference type and configuration, you may have to select a model before you can select an entry, and then you will be able to select one or more content entries to relate to the parent entry.

Here is a detailed explanation on how to work with each reference type:

One to oneAnchor

Use the Add existing <model_name> button to select a content entry from the referenceable model. Simply click on the selection icon to select the entry you want. You will then return to the current content creation screen, and will find the selected entry added as reference.

You can also use the + Create & add new <model_name> button to create and save a new related content entry. This button takes you to the content creation form for the configured model, where you can create a new entry then click on Save or Save & Publish. You will then return to the current content creation screen, and will find the new reference added to the reference field.

The referenceable model is the one configured in the Schema. Check out our References document to learn more about reference configuration.

One to manyAnchor

Use the Add existing <model_name> button to select one or more content entries from the referenceable model. Simply click on the checkboxes of the entries you want to reference in order to select them, then click on Add selected <model_name>. You will then return to the current content creation screen, and will find the selected entries added as references.

You can also use the + Create & add new <model_name> button to create and save a new related content entry. This button takes you to the content creation form for the configured model, where you can create a new entry then click on Save or Save & Publish. You will then return to the current content creation screen, and will find the new reference added to the reference field.

The referenceable model is the one configured in the Schema. Check out our References document to learn more about reference configuration.

Many to manyAnchor

Use the Add existing <model_name> button to select one of the referenceable models. Clicking on a model name takes you to the entry selection screen for that model. Simply click on the checkboxes of the entries you want to reference in order to select them, then click on Add selected <model_name>. You will then return to the current content creation screen, and will find the selected entries added as references.

You can optionally click on Add existing <model_name> again to select entries from a different model.

You can also use the + Create & add new <model_name> button to select one of the referenceable models that you want to use to create and save a new related content entry. This button takes you to the content creation form for the configured model, where you can create a new entry then click on Save or Save & Publish. You will then return to the current content creation screen, and will find the new reference added to the reference field.

The referenceable model is the one configured in the Schema. Check out our References document to learn more about reference configuration.

Many to oneAnchor

Use the Add existing <model_name> button to select one of the referenceable models. Clicking on a model name takes you to the entry selection screen for that model. Simply click on the selection icon to select the entry you want. You will then return to the current content creation screen, and will find the selected entry added as reference.

You can also use the + Create & add new <model_name> button to select one of the referenceable models that you want to use to create and save a new related content entry. This button takes you to the content creation form for the configured model, where you can create a new entry then click on Save or Save & Publish. You will then return to the current content creation screen, and will find the new reference added to the reference field.

The referenceable model is the one configured in the Schema. Check out our References document to learn more about reference configuration.