GQL Documentation Organization

Summary

GraphQL APIs are comprised of three main elements - Queries, Mutations, and Datatypes. The documentation for GraphQL and its use within LogScale is structured around these concepts.

Queries and Mutations

Queries and mutations work together to perform tasks much like functions do. Queries are used to retrieve data and to confirm the status of tools, processes, or systems.

Note

GraphQL queries can only retrieve data regarding LogScale itself and administrative data, like cluster data and user/permissions settings. They aren't used to retrieve content like server logs and events. To search for that data, instead use Search API.

Mutations change configurations and settings in LogScale. Changes to user accounts, roles, and groups are also made through mutations. When you execute a mutation, LogScale returns confirmation and other data depending on how the mutation is configured.

Both queries and mutations use datatypes. While some implementations are standard, others are more complex, depending on the data being queried.

Datatypes and Special Datatypes

Queries and mutations commonly use standard datatypes such as string, Boolean, and integer. When these are not sufficient for more complex requirements, special datatypes have been created and may be reused by several functions. This makes GraphQL functions easier to use and understand, especially when data requirements demand more sophisticated search capabilities.

Some special datatypes contain sub-datatypes, which allows users to define datatypes and make multiple connections via an established schema that is often less structured than other alternatives. For general information on GraphQL schema structure, see the Official GraphQL schema documentation.

There are three main special datatypes:

  • Input structures - Datatypes used for inputting data. Storing data is not a part of this datatype.

  • Data storage types - Regular data types for storing data, referred to simply as types.

  • Enumerated lists (Enumerators) - An enumerated list of choices. Depending on the syntax of the function, one or more choices may be available, and some may not require a selection at all. Instead a default, or null value will be used.

There are two other datatype classifications:

  • Unions - Unions allow users to choose one or more datatypes in the same query. For example, data for a group and data for users can be chosen in the same query at the same time by using ellipses at the start of each item (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.

For more information, see the Official GraphQL documentation for how a GraphQL system is typically designed and used.