PayloadCMS Relationship, Upload, and Join Fields Explained

In this guide, we’re going to go over relationship fields in PayloadCMS. Let’s dive in.

In the two previous guides, we’ve gone over many of the fields available to us in Payload CMS. Some of these are data fields that store data in your database, and others are presentational fields that simply help you organize your admin panel but don’t save data to your database.

We’ve talked about the main fields you’ll use in most projects, a few layout fields that help you organize and group your data, and now we’ll round off all this talk about Payload CMS fields with relationship fields.

There are three fields that I’d like to discuss today: relationship, upload, and join. The relationship and upload fields are data fields, while the join field is a presentational field. These fields could be considered what I call a main field, but each of these fields is more involved than the main fields we already discussed. So, it makes sense to group these in their own guide.

Relationship field

The relationship field allows you to relate documents together. A good example of this is to have an author field within a post collection. You can have a collection of blog authors then, using a relationship field in your blog entry, assign that author to their respective blog post.

In order to render the relationship on the frontend, you may need to adjust the depth at which you are querying your database. Typically, a depth of 1 will be enough, but if you’re only seeing an id when you request a relationship from your database, you will want to increase the depth.

The name and type options are required when configuring the relationship field. A new option called “relation to” is also required. You can provide the slug of a collection to this field to link that collection (like authors) to the collection you’re adding this option to (like the blog collection). 

This field looks and operates similarly to the select field. First, it looks exactly the same as a select field. It also gives you the ability to have multiple options using the “has many” configuration option. It even shares an admin configuration option. You’re able to set “is sortable” to true to enable drag and drop reordering of the relationships.

Other admin config options include “allow create,” “allow edit,” and “sort options.” “Allow create” allows you to control if you want to allow the creation of documents in the related collection without leaving your current window. “Allow edit” controls if you want to grant the ability to edit related documents from your current window. Lastly, “sort options” lets you use a string or object to set a default sorting configuration for the relationship.

You also have the option to filter what is returned in the relationship field using a query, function, or boolean. To do this, we need to set a function in our filterOptions that take relation to, data, and sibling data as arguments. You can then use the relation to argument to target the collection you want to filter, then use a Where query to filter out based on the data you want to filter on.

For example, we can add an attribute to our author collection. We’ll set a checkbox called active. We’ll create a new author that is active and leave our other author as inactive. We can then go to filterOptions, ({relationTo, data}), if relationTo === authors, then return active: {equals: true}. This will filter out all authors that aren’t active so you’re no longer able to select them.

Upload field

The upload field is another data field and is similar to the relationship field in that it requires another collection to be provided in order for the field to work. This field can be used to provide an image to a section or to deliver assets like a PDF.

Like the relationship field, the upload field requires the name, type, and relationTo options. Unlike the relationship field, you’ll need to go to your collection and opt-in to uploads by setting the collection upload config option to true. We’ll dig more into that in a later guide when we go over collections.

There are no admin configuration options outside of the generic admin options that we’ll discuss in a later guide, but you are able to filter the available options you can choose from by using the filter options configuration option.

Filter options can come in handy when you want to only have one media collection but multiple mime types like image, audio, video, and pdfs.

Join field

The last field we’ll go over in this guide is the join field. The join field is a presentational field, so it will not save data to your database. It simply allows you to send data from the relationship and upload fields in the opposite direction. To use an example from earlier, this allows you to do things like view and edit posts belonging to a certain author.

This field can also simplify how you query relationship data on the frontend. While the join field doesn’t add data to your database, it does surface related documents using Payload’s API, which is similar to how virtual fields work. This gets extremely powerful and flexible as you use the Local API to query your documents.

In order for the join field to work, you need to have an existing relationship or upload field in the collection you’re joining. So, if you’re trying to join your author and post collections in your author collection, you need to have the relationship field configured for authors in your post collection.

There are a few required fields for the join field. Name and type are required, just like most other fields. Two other required fields are new to us: collection and on.

The collection field needs to be the slug of the collection you are trying to join. For example, to join the post collection in your authors collection, you will set the collection option to be collection: "posts".

Then you will need the “on” option, which tells PayloadCMS what you want the join to be performed on. Using our same example, you’d like to join the collection posts on: authors.

Lastly, you can use the where option to set a default query to hide related documents from appearing. So here, we could do where: {active: {equals: true} }

This where query is merged with any where queries you perform on the frontend.

Final Thoughts

These relationship fields are extremely flexible and powerful ways to connect your collections. We just scratched the surface for what each of these fields can do.