Using Data Sources

A standard Cook GraphQL query (called a content retrieval query) allows you to request information about specific resources (sections or content items) stored in the Content Store. It allows you to determine what items of information about a given resource you want to retrieve. You can, for example, specify which fields of a content item you want to retrieve. You can also specify which of the content item's relations you want to follow, and how much information you want to retrieve about each of it's related items. Similarly, for a section page, you can specify which layout groups you are interested in, and how much information you want to retrieve about the content items desked in those groups.

A content retrieval query, however, only lets you request information directly related to the context object — that is, the section page or content item pointed to by the request URL. Sometimes you want to be able to include other information on a page. You might, for example, want to include links to content items with a particular tag, content items belonging to a different section or even a different publication, content items that are tagged with the same tag as the current content item and so on.

Data sources provide a means of including this kind of information in the JSON data returned by the Cook. A data source is a kind of saved search, written in graphQL. You can use the Cook's graphQL editor to write data source queries that are not limited to traversing the Content Store's graph. Data source queries are in fact mostly executed by Solr and offer a great deal of power and flexibility.

You can make the following kinds of data source queries:

  • Get content items related to the current content item

  • Get content items of a specified type

  • Get content items belonging to a specified publication

  • Get content items belonging to a specified sections

  • Get content items with a specified value in a specified field

  • Get content items tagged with a specified tag

  • Get content items that share one or more tags with the current content item

  • Get content items related to the current content item

You can also make more complex queries by combining queries of most of the above types using AND and OR operators. So, for example, the following data source query will get all story content items that have an "Elections" tag:

query {
  and {
    tag(tag: "tag:tomorrowonline@escenic.com,2017:elections")
    type(name: "story")
  }
}

This slightly more complex query will get all story or picture content items that have an "Elections" tag:

query {
  and {
    tag (tag: "tag:tomorrowonline@escenic.com,2017:elections")
    or {
     type (name: "story")
     type (name: "picture")      
    }
  }
}

Executing a data source query returns an intermediate JSON structure containing the results of the query.

You can save data source queries and then execute them from within your content retrieval queries. GraphQL can then be used to pick out the exact items of information required from the results returned by a data source. This effectively makes it possible to construct extremely sophisticated queries that leverage the strengths of both GraphQL and Solr.