Using references

#Overview

References connect two or more content entries in Hygraph.

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

#What you can do

• 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 types

There are four types of references based on how many entries you can link and in which direction:

• One-to-one references: They connect one entry to one other entry from a specific model. For example, a country can have one capital, and a capital belongs to only one country.
• One-to-many references: They link one entry to multiple entries from a specific model. For example, an author can be linked to many blog posts.
• Many-to-many references: They allow multiple entries to connect to multiple other entries, but only within the allowed models. For example, a product can belong to multiple categories, and a category can contain multiple products.
• Many-to-one references: They let multiple entries from specific models link to a single entry from a configured model. For example, many blog posts can reference the same author.

#How to use references

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-one references

Click Add existing <model_name> to pick a content entry from an allowed model configured in the schema. Select an entry, then return to the content editor, where it will appear as a reference.

Click + Create new <model_name> - called + Create & replace <model_name> if you have already selected an existing entry - to create, save and relate a new content entry. After saving, it will appear as a reference in the content editor.

The model available for selection is preconfigured in the Schema. Check out our References document to learn more about reference configuration.

#One-to-many references

Use the Add existing <model_name> button to select one or more content entries from a preconfigured 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.

Click + Create new <model_name> to create, save and relate a new content entry. After saving, it will appear as a reference in the content editor.

The model available for selection is preconfigured in the Schema. Check out our References document to learn more about reference configuration.

#Many-to-many references

Use the Add existing entries button to select from the preconfigured models available in the schema. Click on a model name to select entries from that model. Use the checkboxes of the entries you want to reference to select them, then click on Add selected entries. When you return to the content editor, they will appear as references.

You can optionally click on Add existing entries again to add more entries from the same model or from a different one.

You can also use the + Create new entry to create, save and relate a new content entry. After saving, it will appear as a reference in the content editor.

The models available for selection are preconfigured in the Schema. Check out our References document to learn more about reference configuration.

#Many-to-one references

Use the Add existing entries button to select from the preconfigured models available in the schema. Click on a model name to select an entry from that model, and use the reference icon to select & add one. When you return to the content editor, they will appear as references.

Click + Create new entry - called + Create & replace entry if you have already selected an existing entry - to create, save and relate a new content entry. After saving, it will appear as a reference in the content editor.

The models available for selection are preconfigured in the Schema. Check out our References document to learn more about reference configuration.

#Conditional references

If the reference field has Conditional visibility configured, it will only display in the content form when the condition is met.

You can find out if a reference field has a condition configured by looking at the Conditional visibility checkbox in the Configure section of your reference configuration screen:

Conditional references

Check out this document to learn how conditional visibility works.

#Related documents

• References: This document explains how to configure the different types of references in the schema builder.
• Components or references?: This document explains how to choose between a reference or a component depending on your content.
• Reference field type: API Reference document on reference configuration. Use this document to configure references through the API.