Shopify + Sanity: Read about the investment and partnership –>

Cross Dataset Reference

A schema type for referencing documents in another dataset. The external dataset can be within the same project, or belonging to another project (and indeed, account, and organization) entirely.

Cross Dataset References allow you to connect documents across projects and datasets. While similar to the reference type, they have their own, distinct schema type of crossDatasetReference and the two can not be used interchangeably.

To learn about how to set up your datasets for cross dataset referencing, please refer to the article Getting Started with Cross Domain References.

Properties

  • REQUIREDtypestring

    Value must be set to crossDatasetReference.

  • REQUIREDnamestring

    The field name. This will be the key in the data record.

  • REQUIREDtoarray

    Must contain an array naming all the types from the target dataset which may be referenced e.g. [{type: 'someTypeFromAnotherDataset'}]. See more examples below.

    Note: While you may refer to several types in your target dataset in the to array, you are limited to types from a single dataset for each field.

  • REQUIREDdatasetstring

    The name of the target dataset.

  • REQUIREDprojectIdstring

    The ID of the project of target dataset.

  • tokenIdstring

    Unique identifier for cross dataset token. Used to distinguish between multiple tokens belonging to the same dataset.

    Learn how to add a unique token identifier.

  • studioUrlfunction

    A function that is invoked with the type and id of the referenced document, and returns a string.

    Example:

    studioUrl: ({ type, id }) => `https://target-studio.url/desk/${type};${id}`;

  • weakboolean

    Default false. If set to true the reference will be made weak. This allows references to point at documents that may or may not exist, such as a document that has not yet been published or a document that has been deleted (or indeed an entirely imagined document).

  • titlestring

    Human readable label for the field.

  • hiddenboolean | function

    If set to true, this field will be hidden in the studio. You can also return a callback function to use it as a conditional field.

  • readOnlyboolean | function

    If set to true, this field will not be editable in the content studio. You can also return a callback function to use it as a conditional field.

  • descriptionstring

    Short description to editors how the field is to be used.

  • initialValueObjectOrResolverFunction

    The initial value that will be used when creating new values from this type. Can be either the literal value or a resolver function that returns either the literal value or a promise that resolves to the initial value.

Options

  • filterstring | function

    Additional GROQ-filter to use when searching for target documents. The filter will be added to the already existing type name clause.

    If a function is provided, it is called with an object containing document, parent and parentPath properties, and should return an object containing filter and params. As of v2.4.0 this function can optionally be async and return a Promise that resolves to an object containing filter and params.

    Note: The filter only constrains the list of documents returned at the time you search. It does not guarantee that the referenced document will always match the filter provided.

  • filterParamsobject

    Object of parameters for the GROQ-filter specified in filter.

Validation

Learn more about validation
  • required()function

    Ensures that this field exists.

  • custom(fn)function

    Creates a custom validation rule.

Cross Dataset Reference

A minimal example of a crossDatasetReference field:

Input

{
  title: `Person in another dataset"`,
  name: 'personReference',
  type: 'crossDatasetReference',
  dataset: 'production',
  projectId: 'other-project',
  to: [
    {
      type: 'person',
      __experimental_search: [{ path: ['name'] }],
      preview: {
        select: {
          title: 'name',
          media: 'image',
        },
      },
    },
  ],
}

Output

  {
    "_type": "crossDatasetReference",
    "_ref": "person_andrew-stanton",
    "_projectId": "other-project",
    "_dataset": "production"
  }

Weak reference

Defining the crossDatasetReference as weak, will unblock publishing of documents that has a (cross-domain) reference to a non-existing document.

Input

{
  title: `Person in another dataset"`,
  name: 'personReference',
  type: 'crossDatasetReference',
  dataset: 'production',
  projectId: 'other-project',
  weak: true,
  to: [
    {
      type: 'person',
      __experimental_search: [{ path: ['name'] }],
      preview: {
        select: {
          title: 'name',
          media: 'image',
        },
      },
    },
  ],
}

Output

  {
    "_type": "crossDatasetReference",
    "_ref": "person_andrew-stanton",
    "_projectId": "other-project",
    "_dataset": "production",
    "_weak": true,
  }

Reference multiple types

The directors field is an array that can contain both person and bovinae (in the rare occasion a cow would direct a movie) references:

Input

{
  title: `Person or cow in another dataset"`,
  name: 'personOrCowReference',
  type: 'crossDatasetReference',
  dataset: 'production',
  projectId: 'other-project',
  to: [
    {
      type: 'person',
      __experimental_search: [{ path: ['name'] }],
      preview: {
        select: {
          title: 'name',
          media: 'image',
        },
      },
    },
    {
      type: 'bovinae',
      __experimental_search: [{ path: ['name'] }],
      preview: {
        select: {
          title: 'name',
          media: 'avatar',
        },
      },
    },
  ],
}

Output

[
  {
    "_type": "crossDatasetReference",
    "_ref": "person_andrew-stanton",
    "_projectId": "other-project",
    "_dataset": "production"
  },
  {
    "_type": "crossDatasetReference",
    "_ref": "bovinae_ferdinand-bull",
    "_projectId": "other-project",
    "_dataset": "production"
  }
]

Additional static filter

If providing a target schema type is not enough to provide a meaningful set of search results, you may want to further constrain the search query:

Input

{
  title: `Person in another dataset"`,
  name: 'personReference',
  type: 'crossDatasetReference',
  dataset: 'production',
  projectId: 'other-project',
  options: {
    filter: 'role == $role',
    filterParams: {role: 'director'}
  },
  to: [
    {
      type: 'person',
      __experimental_search: [{ path: ['name'] }],
      preview: {
        select: {
          title: 'name',
          media: 'image',
        },
      },
    },
  ],
}

Output

{
    "_type": "crossDatasetReference",
    "_ref": "person_steven-spielberg",
    "_projectId": "other-project",
    "_dataset": "production",
  }

Additional dynamic filter

If you want to further constrain the search result, but need properties from the surrounding document or object/array, you can use the function form for filter:

Input

{
  title: `Person in another dataset"`,
  name: 'personReference',
  type: 'crossDatasetReference',
  dataset: 'production',
  projectId: 'other-project',
  to: [
    {
      type: 'person',
      __experimental_search: [{ path: ['name'] }],
      preview: {
        select: {
          title: 'name',
          media: 'image',
        },
      },
    },
  ],
  options: {
  filter: ({document}) => {
    // Always make sure to check for document properties
    // before attempting to use them
    if (!document.releaseYear) {
      return {
        filter: 'role == $role',
        params: {role: 'director'}
      }
    }
    
    return {
      filter: 'role == $role && birthYear >= $minYear',
      params: {
        role: 'director',
        minYear: document.releaseYear
      }
    }
  }
}

Output

{
    "_type": "crossDatasetReference",
    "_ref": "person_steven-spielberg",
    "_projectId": "other-project",
    "_dataset": "production",
  }

Nonexistent reference

Sometimes the reference field may show an error message like <nonexistent reference>. This usually happens when creating documents with a client library and can mean one of two things:

  • The document with the ID you are referencing does not exist
  • The field does not allow references to the document type of the document ID you tried to reference

Was this article helpful?