GQL Documentation Organization

Summary

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

Queries and Mutations

Queries and mutations are like functions. 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., system configuration) and administrative data (e.g., users, permissions). They aren't used to retrieve content like server logs and events. For that, 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, depending on the mutation.

Both queries and mutations use datatypes. Some are standard ones, but others are special and add layer of complexity when using GraphQL.

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 functions. For those, special datatypes have been created that are often used by several functions. This makes GQL functions easier to use and 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. See the Wikipedia page on GraphQL for more on how a GraphQL system is typically designed and used.

There are three main special datatypes: input structures, data storage types, and enumerated lists. There are also unions and interfaces, but those are groupings of associated datatypes. These are all explained here:

  • Inputs: These are datatypes used for inputting, 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. Depending on the syntax of the function, you may choose one or more. For some, no selection is required — a default or null value will be used instead.

There are two other datatype classifications of sorts: unions and interfaces. They're not datatypes per se, but segues to other datatypes.

  • Unions: A union allows you to choose one or more datatypes in the same query. For example, you might request data for a group and for users with the execution of one query. You would use ellipses and on (i.e., ... on ) at the start of each (e.g., see testFdrFeed()).

  • Interfaces: An interface connects multiple similar, 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.