Content stages in Hygraph
#Overview
You can create your own content stages inside the Hygraph UI, and query content from these stages, as well as publish to.
By default all content is served from the DRAFT stage, unless configured otherwise via a Permanent Auth Token, or by filtering.
You can create custom content stages to publish to from DRAFT. Each project comes with stages DRAFT, and PUBLISHED.
Custom content stages are available to paid plans. Upgrade your plan.
Content stages are environment specific. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.
#Create a content stage
- Navigate to your project settings.
- Open the Content Stages tab.
- Press "Add Stage" at the bottom of the list of stages.
- Provide the Display name, API ID, a Color for the label and Description in the modal.
- Click
Create.
Creating content stages besides the two offered by default - DRAFT & PUBLISHED - is available to paid plans. Upgrade your plan.
#Edit a content stage
- Navigate to the content stage you want to edit.
- Press "edit" in the lower left corner of the stage card.
- Click
Updatein the lower right corner of the card.
System content stages - DRAFT & PUBLISHED - cannot be edited.
#Delete a content stage
- Navigate to the content stage card you want to delete.
- Click
Deleteand confirm your choice.
System content stages - DRAFT & PUBLISHED - cannot be deleted.
#Publishing content
Hygraph automatically generates a publish mutation for each of your content models, including the asset model.
If the models have localized fields, you can greater control the locales you want to publish, and if you want to publish the base entry.
Each time you publish to a content stage, you will create a snapshot of the data as a version.
For example, if we have a product model, the mutation publishProduct will exist. You can use this mutation to publish content to a content stage.
| Argument | Input Tpye | Description |
|---|---|---|
where | ProductWhereUniqueInput | The content entry you want to publish, using a filter. |
to | [Stage!]! = [PUBLISHED] | The target published content stage. |
locales | [Locale!] | Optional locales to publish. |
publishBase | Boolean = true | Whether to publish the base content entry. |
withDefaultLocale | Boolean = true |
Every mutation besides publish and unpublish, will only update the DRAFT version.
For instance, when you update an entry in the UI, you are doing an updateMutation, which changes the DRAFT version.
To update the published version, you would need to publish that DRAFT.
#Unpublishing content
Similar to publishing content, you can unpublish from a selected content stage.
For example, if we have a product model, the mutation unpublishProduct will exist. You can use this mutation to unpublish content from a content stage.
| Argument | Input Tpye | Description |
|---|---|---|
where | ProductWhereUniqueInput | The content entry you want to unpublish, using a filter. |
from | [Stage!]! = [PUBLISHED] | The target content stage to unpublish from. |
locales | [Locale!] | Optional locales to unpublish. |
unpublishBase | Boolean = true | Whether to unpublish the base content entry or not. |
#Versioning
Versioning allows you to work non-destructively with content. Make changes, and recover previous versions with Hygraph.
Each time you publish to a content stage, history is written.
Versions of documents are kept for a minimum of 30 days, for paid plans. Upgrade your plan for longer history retention.
#Fetching version history
You can fetch all of the history by stage. history is a system field.
For example, let's get all of the history for products.
Replace stage: PUBLISHED with stage: QA to get history from custom stage QA.
#Fetching a single version
You can use a the generated [model]Version query to fetch a single version of a content entry.
Since models can be complex, and change over time. The data field is a JSON field that returns a snapshot of the content entry at that time.
Using the id, and revision from the previous query, we can fetch the data of the version, including the relations metadata.