Intro to References

Reference this, reference that. Throughout the past few modules you may have noticed the term reference used a bit.

Believe it or not, you've known about References since you learned about Schemas. Remember this diagram?

Let's add a few labels and more information, now that you've learned a lot since:

In the diagram, we have two documents: Dog and Breed. The Dog document has a Name and Age Field, as well as a Breed Reference. The Breed document only has a name.

As you can see, by referencing Breed in the Dog document, we can use the Breed Data for the Dog documents we make.

Making our First Reference

Let's re-enable our Dog and Pet Info schemas if you removed them:

import blogPost from './blogPost'import labeledLink from './objects/labeledLink'import dog from './dog'import petInfo from './objects/petInfo'
export const schemaTypes = [blogPost, labeledLink, dog, petInfo]

Now, let's make a new Document named Breed:

export default {  name: 'breed',  type: 'document',  title: 'Breed',  fields: [    {      name: 'name',      type: 'string',      title: 'Name',      validation: (Rule) => Rule.required().max(50).min(2),    },  ],}

And add it to our /schemas/index.js:

import blogPost from './blogPost'import labeledLink from './objects/labeledLink'import dog from './dog'import petInfo from './objects/petInfo'import breed from './breed'
export const schemaTypes = [blogPost, labeledLink, dog, petInfo, breed]

Let's add a few Breeds in Studio:

Now, let's create our Reference in our Dog document schema:

...,{  name: 'breed',  type: 'reference',  to: [{type: 'breed'}],  title: 'Breed',},...

However, keep in mind we updated a pre-existing and filled field, so Sanity will ask us to reset the value - which you should do. That will let us try our new reference.

Now that's cleared out of the way, we can add or create a Breed document.

Let's set up a few Dog documents with this new Breed document reference.

And that's how references work! References allow us to connect various Documents and their related data together. However, this is only one part of the puzzle.

References in GROQ

As you remember with Images, we used a special type of query to get the URL, since we made a reference to an Image. We'll have to do the same with our Dog document now. If we use the following query in Vision and fetch, you'll see that our selected Breed doesn't actually show up - but a weird _ref does.

*[_type == "dog"] {  "name": petInfo.name,  "age": petInfo.age,  breed,}

[…] 2 items  0:{…} 3 properties    age:5    breed:{…} 2 properties      _ref:50f1250d-d186-44b7-87e2-a10270da8521      _type:reference    name:Astro  1:{…} 3 properties    age:3    breed:{…} 2 properties      _ref:50f1250d-d186-44b7-87e2-a10270da8521      _type:reference    name:Bean

Remember, we don't actually want the Breed document, but the name field of the Breed document. And we can do that like so:

*[_type == "dog"] {  "name": petInfo.name,  "age": petInfo.age,  "breed": breed->name,}

Now if we run the query, you'll see that our Breed names show up:

[…] 2 items  0:{…} 3 properties    age:5    breed:Shih Tzu    name:Astro  1:{…} 3 properties    age:3    breed:Shih Tzu    name:Bean

And it's once again using that weird -> notation. Why? We'll dive deeper into that next, as we check out how Images really work under the hood.

One more thing

Before we move on, let's fix a bug that you may have noticed:

Naturally, Sanity automatically determines what to put as the preview title for documents. However, since we nested our main fields in an object, we have to manually select what shows up. Lets add a preview field to our Dog document to show the names and breeds of our Dog documents:

export default {  name: 'dog',  type: 'document',  title: 'Dog',  fields: [    ...  ],  preview: {    select: {      title: 'petInfo.name',      subtitle: 'breed.name',    },  },}

Now if we go back to Studio, you'll see that our list of Dog documents is now formatted properly:

But what if we also want to show the Age? Well, we can't add another subtitle, but we can modify what our subtitle is beyond a single field:

...,preview: {  select: {    title: 'petInfo.name',    age: 'petInfo.age',    breed: 'breed.name',  },  prepare(selection) {    const {title, age, breed} = selection    return {      title: title,      subtitle: `${age} years old | ${breed}`,    }  },},...

Here, instead of using the title and select fields in the preview select, we create variables for title, age, and breed. Then, we prepare the selection using these variables, and can create a custom list preview: