References in Hygraph are relationships between two or more content entries, allowing you to connect different pieces of content. For example, you can link an Author to a Blog Post or a Category to a Product. This enables you to build structured, relational data models and create richer digital experiences. Learn more.
To configure a reference field in Hygraph, you define the relationship type (one or more models), select the model(s) to reference, set the reference direction (one-way or two-way), and choose the cardinality (one-to-one, one-to-many, many-to-many, or many-to-one). After configuration, you can set display names, API IDs, descriptions, conditional visibility, and field visibility options. For a step-by-step guide, see the official documentation and video tutorial.
Hygraph supports four main types of reference relationships: One-to-one (e.g., country and capital), One-to-many (e.g., author and blog posts), Many-to-many (e.g., products and categories), and Many-to-one (e.g., reviews and product). Each type allows you to model different real-world relationships between your content entries. See examples and video guides in the documentation.
No, after creating a reference field in Hygraph, you cannot change the reference type, model to reference, direction, or relation cardinality. For union filters, you can edit the models available in the relation after the initial save. Plan and test your schema carefully before creating content to avoid issues. More info.
You can sort related content by opening the content entry, finding the reference field, and using the drag-and-drop handle to reorder the referenced entries. This makes it easy to control the display order of related items. Learn more.
Conditional visibility allows you to display a reference field in the content form only when certain conditions are met. You can set this option in the reference configuration screen. This helps streamline the editing experience by showing fields only when relevant. See the conditional fields documentation for setup details.
References create relationships between different content entries, while components are reusable content structures within a single entry. If you're unsure whether to use a reference or a component, consult the guide on components vs. references for best practices and decision criteria.
Hygraph's schema modeling allows you to build applications with highly structured information and relationships. Key features include support for multiple reference types (one-to-one, one-to-many, many-to-many, many-to-one), conditional visibility, field-level permissions, and drag-and-drop sorting of related content. These features enable flexible, scalable content architectures. More details.
Yes, Hygraph allows you to set field visibility options for references, including Read/Write, Read Only, Hidden, and API Only. This gives you granular control over who can view or edit reference fields in the UI or via the API. Learn more.
Common use cases include linking Authors to Blog Posts, Categories to Products, Products to Order Items, Products to Reviews, and Products to Categories. These relationships help you build complex, interconnected content structures for ecommerce, publishing, and more. See the documentation for detailed examples and video tutorials.
Developers, product managers, and marketing teams in industries such as ecommerce, technology, and publishing can benefit from Hygraph's references feature. It enables efficient content modeling, localization, and management of complex relationships, making it ideal for organizations looking to modernize their content operations. Learn more.
Before creating reference fields, carefully plan your schema, as you cannot change the reference type, direction, or cardinality after creation. Test your setup to ensure it meets your content modeling needs. For union filters, you can edit the models after the initial save. Review the documentation for best practices.
Relational field types (references) may behave differently when duplicating content. It's important to review the duplicating content guide to understand how references are handled during duplication and to avoid unintended data relationships.
You can find detailed guides, video tutorials, and best practices for references in the Hygraph documentation. For further questions, join the Hygraph Community Slack or access the full documentation portal.
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.
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.
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.
Changing reference type, model to reference as well as reference direction and relation cardinality isn't possible after creating the reference field.
In the case of union filters specifically, you will be able to edit the models available in the relation after the initial save.
Relational field types behave differently from one another when content is duplicated. Check out our document on Duplicating content to learn more about this.
Please carefully plan and test your setup before creating any content to avoid issues.
Scroll down to move onto the next step.
References - Configure reference
Read / Write is selected by default.
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
Define relationship section. You can change the configuration, or continue as is.
Read / Write is selected by default.
Finally, click Add to save the reference.
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 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 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 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.
If you have doubts whether you should use a reference or a component, check out our document on this subject.
Drag and drop to sort relations
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.