Understanding GQL Documentation Organization

Summary

The GraphQL API documentation is extensive. It includes several hundred of pages of information. Those pages are grouped by queries, mutations, and datatypes.

Document Groups

The GraphQL API documentation pages are organized into three primary groups: queries, mutations, and datatypes. Many queries and mutations use standard datatypes, such as string, boolean, and integer. However, these are not always sufficient for more complex requirements of most LogScale queries and mutations (i.e., functions). To fulfill those needs, special datatypes have been created for them. Although these special datatypes may be composed of standard dataypes, by making special datatypes that contain clusters of standard ones, they may be reused And they make GQL functions easier to use or comprehend — especially when the sub-choices are optional. Of course, some special datatypes contain more special datatypes, sub-datatypes, so to speak.

This may be overwhelming and confusing to a newcomer, but it's the nature of a Graph Query Language. It's less structured per se, and allows for defining datatypes and making multiple connections through a schema. Queries are used for connecting nodes of data and retrieving results. Mutations are used for changing data, for which results are returned — often confirmation of success, but sometimes data that might normally be gotten through use of a query. See the WikiPedia page on GraphQL for more on how GraphQL is typically designed and used.

There are three main special datatypes:

  • Input Structures: These are datatypes used for inputing, not storing data.

  • Types: These are regular datatypes for storing data, referred to simply as types.

  • Enumerators: Each of these contain an enumerated list of choices. For some you may choose more than one, depending on the syntax of the function. And for some you can forego choosing a value and a default or null value will be used.

There are two other datatype classifications of sorts:

  • Unions: A union allows you to choose one or more datatypes in the same query. For example, you might get data for a group and for users with the execution of one query.

  • Interfaces: An interface connects multiple similiar, possibly identical datatypes to the same function — or another datatype. For example, the datatype SearchDomain is an interface for the Repository and the View datatypes — after all, a search domain can be a repository or a view.