GraphQuery vs FetchLinks


I just came across GraphQuery - up to now I've been using fetchLinks to do my content relationship queries. Even though it says in the official documentation that you can't query group, richtext, etc fields, the fact is that you indeed can (that has been the case for over two years and I'm not sure why this hasn't been reflected in the documentation).

I decided to try GraphQuery to see how it compares vs fetchlinks.

This is my fetchlinks query to retrieve a group field and a title from a submenu.

export const submenuFetchLinks = ["submenu.leftTitle", "submenu.leftLinks"];

This is the equivalent query in GraphQuery:

export const submenuGraphQuery = `{
        ...on submenu{

Besides being much longer and complicated, it also means that I can't reuse this query in other API calls for other custom types (since it's scoped to header). As opposed to fetchLinks which is model independent).

Could you explain why would I want to use GraphQuery instead of fetchLinks?


These two Query Options exist on the REST API for getting content from linked documents.

Fetchlinks allows you to get a specific field and all its content from the document. You can get Rich Text, but it only returns the first element. You can't get information from Slices or these other fields:

  • Embed
  • GeoPoint
  • Link
  • Link to Media

Also, it's limited to getting info from 2 documents deep.

I will update the docs in regards to the group field information.

Whereas GraphQuery allows you to do selective fetching (i.e., fetch only the required fields) and you can go deeper than 2 documents in content fetching, plus grab Slice data.

I was actually asking myself the same questions about these 2 methods:

  • Which of these Query Options to get linked content do you prefer to use?
  • Would you like to see improvements in either of these options?
  • Is it confusing having both of these methods?

@Phil Thanks for the explanation. From personal experience, fetchLinks does work for Link - probably worth exploring if it works for the other fields you have mentioned.

I personally never had to retrieve the slices from a linked document, but I do foresee a future where this could happen. I usually use it to retrieve article card information, author info, pricing tier, sub menu and things like this.

To answer you questions

  • I prefer fetchLinks due to simplicity
  • both seem to be working fine for me, GraphQuery has a lot more complicated syntax but once you learn it, I assume it wouldn't be a big problem
  • Don't think so.

Do you plan to depreciate fetchLinks at some point in the future?

I'll add this to our documentation backlog for someone to test and update.

Thanks for the feedback in clarifies a few things for me. We don't have plans to deprecate fetchlinks, but I wanted to open this conversation about these 2 options we are offering and if we should simplify them somehow, maybe by only recommending one of them.

I'll have to continue this conversation internally. Hopefully more people see this thread though.

This thread is being monitored as an open ticket in the documentation backlog. We will update this post once we update the documentation. If you want to contribute to this conversation, you can ‘Flag’ this topic to reopen.