References

#Overview

References are relations between two or more content entries that you can create in Hygraph. You can configure them in different ways.

This document gets into the schema configuration of the different types.

#What you can do

You can use references to connect content entries to one another.

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

#Schema configuration

When you add a reference to your schema, you will need to configure its type, direction and cardinality. Four types of references can result from this configuration.

References - Define relationship

• Define relationship

  • Reference type: Use the radio buttons to select whether the field will be able to reference one model, or more.

  • Model to reference: Use the dropdown to select one or more models, depending on your previous selection.

  • Reference directions: Use the radio buttons to define if content will be queryable from one side or both.

    In the case of one-way references, the reference will only be seen in one model in the UI. The referenced model will not have a reference field and users won't be able to see the connected entries.

  • Reference cardinality: Use the dropdown to define whether 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: Available for one-way and two-way references. It allows adding a reference to one content entry from the model configured as referenceable above.
    • One to many: Available for one-way and two-way references. It allows adding references to multiple content entries from the model configured as referenceable above.
    • Many to many: Available for two-way references. It allows adding references to multiple content entries from the different models configured as referenceable above.
    • Many to one: Available for two-way references. It allows adding references to multiple content entries of the parent model to the model configured as referenceable above.

Scroll down to move onto the next step.

References - Configure reference

• Configure reference: This section will initially display complete, based on your selections in the previous section. You can change the configuration, or continue as is.
  • Display name: Display name for your reference in the schema and the content editor.
  • API ID: API ID of your reference.
  • Description: The system does not autocomplete this field. You can optionally add a description to your reference here.
  • Conditional visibility: You can optionally use the dropdown menus to set conditional visibility for this field in the UI. Check out our conditional visibility documentation to learn more.
  • Field visibility: Use the dropdown menu to select an option. Read / Write is selected by default.
    • Read / Write: The field can be read and edited.
    • Read only: The field is shown but can't be edited in the UI, only through the API.
    • Hidden: The field is not shown, but can be used by other fields such as slugs or UI extensions.
    • API only: The field is not shown, and can only be read or edited through the API.

At this point of the configuration process you will have different options depending on the direction you selected. If you are creating a one-way reference, you can finalize the process here by clicking on Add. If you are creating a two-way reference, you need to scroll down to configure the reverse field:

References - Configure reverse field

• Configure reverse field: This section contains the information for the reverse field, which is the field that will appear in the referenceable model. It will initially display complete, based on your selections in the Define relationship section. You can change the configuration, or continue as is.
  • Display name: Display name for the reverse field in the schema.
  • API ID: API ID of the reverse field.
  • Description: The system does not autocomplete this field. You can optionally add a description for the reverse field here.
  • Field visibility: Use the dropdown menu to select an option. Read / Write is selected by default.
    • Read / Write: The field can be read and edited.
    • Read only: The field is shown but can't be edited in the UI, only through the API.
    • Hidden: The field is not shown, but can be used by other fields such as slugs or UI extensions.
    • API only: The field is not shown, and can only be read or edited through the API.

Finally, click Add to save the reference.

#One to one

One-to-one references let you add a relation to a content entry from the model or models configured as referenceable. A referenceable model is one you link during field configuration.

Editors using the content form will be able to link to only one other entry from the selected model, as an exclusive relation between two entries.

A great example to show this type of relation is a country and its capital. Each country has one capital, and each capital belongs to only one country.

The following video shows an example of how to set up a one-to-one reference:

#One to many

One-to-many references let you add references to multiple content entries from the model or models configured as referenceable. A referenceable model is one you link during field configuration.

Editors using the content form will be able to link to multiple content entries from the selected model or models.

A great example to show this type of relation is a schema where you have a product model and an order item model, in which you can relate one product to many order items.

The following video shows an example of how to set up a one-to-many reference:

Another example of this type of reference could be an author that is related to many blog posts.

#Many to many

Many-to-many references let you add references to multiple content entries from the model or models that you link to during configuration, while also allowing content entries from the other model or models to link to several content entries from this one.

A great example to show this type of relation is a schema where you have a product model and a category model, in which one product can be related to multiple categories, and one category can be related to multiple products.

The following video shows an example of how to set up a many-to-many reference:

#Many to one

Many-to-one references let you add a reference to one content entry from the model or models that you link to during configuration, while allowing entries from the referenced model or models to link to multiple entries from this one.

A great example to show this type of relation is a schema where you have a product model and a reviews model, in which one product can be related to multiple reviews, but a review can be related to only one product.

The following video shows an example of how to set up a many-to-one reference:

Another example of this could be a number of blog posts related to a single author.

#References or components?

If you have doubts whether you should use a reference or a component, check out our document on this subject.

#Sorting related content

Drag and drop to sort relations

1. Open the content entry that contains the references you want to sort.
2. Find the reference field in the form.
3. Using the six-dots handle, drag and drop to reorder.

#Conditional references

You can use the Conditional visibility option in a reference field so that the reference only displays in the content form when needed.

You can find the Conditional visibility checkbox in the Configure section of your reference configuration screen:

Conditional references

Check out this document to learn how to set up conditional visibility.