The GraphQL API documentation is extensive. It includes several hundred of pages of information. Those pages are sorted into groups: queries, mutations, and datatypes.

Queries and mutations are like functions & they're actually fields of two core datatypes. Queries are used to retrieve data from LogScale, and sometimes just confirmation of the status of something. Note, that the GraphQL queries can only get data on LogScale itself (e.g., a cluster) and administrative data (e.g., users, permissions). You can't use it to get content (e.g., server logs, events themselves). For those queries, you would use instead the Search API.

Mutations are used to change configurations or settings in LogScale. You can also make changes to user accounts, roles, groups, etc. In return, you'll receive confirmation of execution and possibly other data.

This is all fairly straightforward. It's when you get to the datatypes used by queries and mutations that it gets complicated.

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. To fulfill those needs, special datatypes have been created. Although they may be composed of clusters of standard datatypes, they may be reused. This makes GQL functions easier to use or comprehend — especially when the sub-choices are optional. To add to the complexity, some special datatypes contain other special datatypes, sub-datatypes.

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.