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.
  • 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 allow adding a relation to one content entry from the one model configured as referenceable. Each side of the relation can link to only one other entry, as an exclusive relation between two entries.

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

An example of this 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

One to many references allow adding references to multiple content entries from the one model configured as referenceable.

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

An example of this could be an author that is related to many blog posts.

#Many to many

One to many references allow adding references to multiple content entries from the different models configured as referenceable.

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

An example of this 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

One to many references allow adding references to multiple content entries from the one model configured as referenceable.

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

An 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.