Gatsby: Query array of references returns _ref instead of full documents

Good news - you can absolutely retrieve the actual documents instead of just the reference objects! The gatsby-source-sanity plugin handles reference resolution automatically through Gatsby's GraphQL layer.

Using GraphQL Fragments (Recommended)

When querying in Gatsby, you can directly access the referenced documents' fields. The plugin automatically creates relationships between your documents, so you can query the actual content using GraphQL fragments:

query {
  sanityGrid {
    name
    items {
      ... on SanityTrack {
        _id
        _type
        # add your track fields here
        title
      }
      ... on SanityLink {
        _id
        _type
        # add your link fields here
        url
      }
      ... on SanityPicture {
        _id
        _type
        # add your picture fields here
        image {
          asset {
            url
          }
        }
      }
      ... on SanityJournal {
        _id
        _type
        # add your journal fields here
        title
      }
    }
  }
}

The plugin dereferences the relationships automatically when you query the actual fields of those referenced documents. This approach is clean, type-safe, and gives you better autocomplete in your Gatsby queries.

Using _rawItems with resolveReferences

Alternatively, you can use the special _raw fields that gatsby-source-sanity provides. These give you access to the raw Sanity data with reference resolution:

query {
  sanityGrid {
    name
    _rawItems(resolveReferences: {maxDepth: 2})
  }
}

The resolveReferences option tells Gatsby to dereference the references up to a specified depth. This is particularly useful when you need the raw data structure or when working with Portable Text content.

The first approach (GraphQL fragments) is generally preferred for most use cases since it's more explicit about what data you're fetching and integrates better with Gatsby's type system!