# Cross Dataset References - Quickstart

*This is a paid feature, available on the Enterprise plan.*

A powerful tool in your Shared Content toolbox is the `crossDatasetReference` schema type. This article provides a step-by-step walkthrough of how to get started using it in the studio. For more background on cross-dataset references, please refer to the more in-depth [introductory article](https://www.sanity.io/docs/studio/cross-dataset-references) and the [schema type reference](https://www.sanity.io/docs/cross-dataset-reference-type).

*This is a paid feature, available on the Growth plan.*

## Prerequisites and presumptions

This article presumes that:

- You have access to two different datasets within a single project you’d like to connect
- That both of those datasets belong to projects on an enterprise plan and have the shared content feature enabled
- That the studios you intend to use to interact with these datasets are updated to `v2.34.2` or later
- That you have some prior experience with Sanity and are familiar with concepts such as *the studio*, *datasets, *and *projects*

For the remainder of this guide, we’ll refer to the dataset that will be doing the referencing as the **referencing dataset**, and to the dataset that has the document type that will be referred to as the **referenced dataset**.

Let’s go!

##  Setting up the schema

- Navigate once more to the project folder for the studio you intend to use with your *referencing dataset.* Run `sanity start` again to start up the dev server. (Or, more likely, just keep it running unless you shut it down earlier.)
- Open the project folder in your favorite code editor, and navigate to the location where you want your new `crossDatasetReference` field to show up. You can make a new schema, or make some room in one you’ve already written.
- Once you’ve decided where you want your field, add the following code, substituting the placeholder values for your own.

```javascript
{
  title: 'Reference to documents in a another dataset',
  name: 'myCoolField',
  type: 'crossDatasetReference',
  dataset: '<name-of-other-dataset>',
  to: [
    {
      type: '<blogPostInTargetDataset>',
      preview: {
        select: {
          title: 'title',
          media: 'heroImage',
        },
      },
    },
  ],
}
```

- Let’s go through the code line by line:  - The `title` and `name` fields, you may give whatever values you’d like. `name` is required, `title` is optional, as always.
- The `type` is required and must be `crossDatasetReference`.
- `dataset` is required and should be given the appropriate values from your **referenced dataset**.
- The `to` field should have an array of the document types you’d like to be able to reference in your **referenced dataset**. You can have multiple types defined, but only from one dataset per field.- Each entry in the `to` array is an object specifying the `type` of documents we’re interested in and which of its fields we should use for search and previews, as defined by the `preview` field.


- These are the **required** fields for any `crossDatasetReference` field, but there are several more! Read all about them [here](https://www.sanity.io/docs/cross-dataset-reference-type)!


- Save your work, and navigate to the appropriate content type in your studio. You should see something like this:

![shows cross-dataset reference input](https://cdn.sanity.io/images/3do82whm/next/3589f197b2eb83b83df09f8c65a38bf403dd4105-1800x760.png)

## Querying cross-dataset references

```javascript
// Results include the name of the origin dataset
{
  _type: 'crossDatasetReference',
  _ref: 'id-of-reference-document',
  _dataset: 'name-of-dataset',
}
```

Cross-dataset references work similarly to regular references, except that dereferencing is unidirectional. You can read more about this in the [main article on cross-dataset references](https://www.sanity.io/docs/studio/cross-dataset-references), but in short, it means that expanding references using the `->` operator works as you'd might expect, but using other methods such as the `references()` function will not work.

```groq
// Dereferencing using -> works as normal
*[_type == 'crossDatasetReferringDocument']{
	 // Expand entire referenced document
   personFromDatasetB->,
	 // Expand projection of certain fields
  "personDetails": personFromDatasetB->{
    name, 
    jobTitle,
    awards->name
  }
}
```

```groq
// This is a NOT SUPPORTED query
*[_type == 'crossDatasetReferringDocument']{
	 // Expand entire referenced document
   personFromDatasetB->,
	 // Expand projection of certain fields
  "personDetails": personFromDatasetB->{
    name, 
    jobTitle,
    "awards": *[_type == "awards" && references(^._id)] // <== here the reference function will not work for a cross-dataset reference
  }
}

```

## Further reading:

- [Intro to cross-dataset references](https://www.sanity.io/docs/studio/cross-dataset-references)
- [crossDatasetReference schema type](https://www.sanity.io/docs/cross-dataset-reference-type)
- [Connected Content article](https://www.sanity.io/docs/studio/connected-content)