Skip to content

Gradle GraphQL Schema Exploration Language

Jump to bottom
dermakov edited this page Jan 4, 2026 · 1 revision

Table of contents

Introduction

The GraphQL Schema Exploration Language (GSEL) was developed to enable searching for fields in various GraphQL types based on a set of conditions. The Kobby plugin uses this language to truncate GraphQL schemas before generating DSL, as well as to serve as a GraphQL schema analysis tool.

Queries in this language look like this:

kobby {
    schema {
        analyze {
            byQuery {
                forType("Genre") {
                    // Select values 'COMEDY' and 'HORROR' in the 'Genre' enumeration.
                    include {
                        enumValue("COMEDY|HORROR")
                    }
                }
                forQuery {
                    // Select all 'Query' type fields except 'film' and 'films'.
                    exclude {
                        field("film")
                        field("films")
                    }
                }
                forMutation {
                    // Select all 'Mutation' type fields where one of the argument types is `FilmInput`.
                    include {
                        argumentDependency("FilmInput")
                    }
                }
                forAny {
                    // For any type, select all fields of type 'Country' or 'Film'.
                    include {
                        dependency("Country|Film")
                    }
                }
            }
        }
    }
}

Kobby Pattern

The GSEL query uses the Kobby pattern matching tool to find target types or fields. The Kobby pattern syntax is as follows: ↑

  • ? - matches one character.
  • * - matches zero or more characters.
  • | - OR operator.
  • __query - alias for Query type.
  • __mutation - alias for Mutation type.
  • __subscription - alias for Subscription type.
  • __root - alias for Query, Mutation and Subscription types.
  • __any - alias for any type in the GraphQL schema.
  • __anyScalar - alias for any scalar in the GraphQL schema.
  • __anyObject - alias for any object in the GraphQL schema.
  • __anyInterface - alias for any interface in the GraphQL schema.
  • __anyUnion - alias for any union in the GraphQL schema.
  • __anyEnum - alias for any enum in the GraphQL schema.
  • __anyInput - alias for any input object in the GraphQL schema.

For example:

forType("__root|Actor*") {
    include {
        argumentDependency("__anyEnum|Film*")
    }
}

GSEL query syntax

The GSEL query consists of 3 nested layers: ↑

  1. Schema Query layer — responsible for searching types in a GraphQL schema (the forXXX queries).
  2. Operation Query layer — responsible for applying the type subquery to the target GraphQL type (include and exclude operations).
  3. Type Query layer — responsible for selecting fields in the target GraphQL type.
forType("Actor") { // Schema Query layer
    include { // Operation Query layer
        dependency("Country") // Type Query layer
    }
}

The GSEL query may contain multiple forXXX schema queries. In this case, the schema queries conditions are combined using the "or" operator:

// Find the fields in the "Actor" type or in the "Movie" type.  

forType("Actor") {
    include {
        dependency("Country")
    }
}

forType("Film") {
    include {
        dependency("Country")
    }
}

To simplify this query, you can use the Kobby Pattern:

forType("Actor|Film") {
    include {
        dependency("Country")
    }
}

Schema Query

The part of the query that is responsible for selecting the GraphQL types in which to look for fields. ↑

Select type by pattern

fun forType(pattern: String) ↑

Apply the operation subquery to all types in the GraphQL schema that match the pattern.

forType("Actor") {
    // Operation subquery
}

Select Query type

fun forQuery() ↑

Apply the operation subquery to a Query type in the GraphQL schema. Synonym for forType("__query").

forQuery {
    // Operation subquery
}

Select Mutation type

fun forMutation() ↑

Apply the operation subquery to a Mutation type in the GraphQL schema. Synonym for forType("__mutation").

forMutation {
    // Operation subquery
}

Select Subscription type

fun forSubscription() ↑

Apply the operation subquery to a Subscription type in the GraphQL schema. Synonym for forType("__subscription").

forSubscription {
    // Operation subquery
}

Select root types

fun forRoot() ↑

Apply the operation subquery to root types in the GraphQL schema - Query, Mutation and Subscription. Synonym for forType("__root").

forRoot {
    // Operation subquery
}

Select any type

fun forAny() ↑

Apply the operation subquery to any type in the GraphQL schema. Synonym for forType("__any").

forAny {
    // Operation subquery
}

Select any object type

fun forAnyObject() ↑

Apply the operation subquery to any object in the GraphQL schema. Synonym for forType("__anyObject").

forAnyObject {
    // Operation subquery
}

Select any interface type

fun forAnyInterface() ↑

Apply the operation subquery to any interface in the GraphQL schema. Synonym for forType("__anyInterface").

forAnyInterface {
    // Operation subquery
}

Select any union type

fun forAnyUnion() ↑

Apply the operation subquery to any union in the GraphQL schema. Synonym for forType("__anyUnion").

forAnyUnion {
    // Operation subquery
}

Select any enum type

fun forAnyEnum() ↑

Apply the operation subquery to any enum in the GraphQL schema. Synonym for forType("__anyEnum").

forAnyEnum {
    // Operation subquery
}

Select any input type

fun forAnyInput() ↑

Apply the operation subquery to any input object in the GraphQL schema. Synonym for forType("__anyInput").

forAnyInput {
    // Operation subquery
}

Operation Query

The part of the query responsible for applying the type subquery to the target GraphQL type. ↑

An "Operation Query" contains both include and exclude operation. The exclude operation excludes all fields that match the include operation from the query result. If the include operation is not specified, the "include all" operation is assumed to apply.

For example, this query will find all fields of type Film in the Query type and exclude the field named "films" from the query results.

forType("__query") {
    include {
        dependency("Film")
    }
    exclude {
        field("films")
    }
}

Include operation

fun include() ↑

Apply the type subquery to a target GraphQL type. Put fields of the target type that match the subquery into the query result.

forType("Actor") {
    include {
        // Type subquery
    }
}

Exclude operation

fun exclude() ↑

Apply the type subquery to a target GraphQL type. Put fields of the target type that do not match the subquery into the query result.

forType("Actor") {
    exclude {
        // Type subquery
    }
}

Type Query

The part of the query that is responsible for selecting fields in the target GraphQL type. ↑

A "Type Query" may contain multiple conditions. In this case, the conditions are combined using the "or" operator:

forQuery { // For type Query 
    include {
        field("country") // include a field named "country",
        field("countries") // or a field named "countries",
        dependency("Film") // or a field of type "Film"
        dependency("Actor") // or a field of type "Actor"
    }
}

To simplify this query, you can use the Kobby Pattern:

forQuery {
    include {
        field("country|countries")
        dependency("Film|Actor")
    }
}

Select enum value by pattern

fun enumValue(pattern: String) ↑

Select enum values whose name matches the pattern.

forType("Genre") {
    exclude {
        enumValue("DRAMA|COMEDY")
    }
}

Select field by pattern

fun field(pattern: String) ↑

Select fields whose name matches the pattern.

forQuery {
    include {
        field("country|countries")
    }
}

Select any overridden field

fun anyOverriddenField() ↑

Select fields that override any fields from the supertype.

forType("Actor") {
    include {
        anyOverriddenField()
    }
}

Select dependency by pattern

fun dependency(pattern: String) ↑

Select fields whose type matches the pattern.

forQuery {
    include {
        dependency("Film|Actor")
    }
}

Select any scalar dependency

fun anyScalarDependency() ↑

Select fields whose type is scalar. Synonym for dependency("__anyScalar").

forType("Film") {
    exclude {
        anyScalarDependency()
    }
}

Select any object dependency

fun anyObjectDependency() ↑

Select fields whose type is object. Synonym for dependency("__anyObject").

forType("Film") {
    include {
        anyObjectDependency()
    }
}

Select any interface dependency

fun anyInterfaceDependency() ↑

Select fields whose type is interface. Synonym for dependency("__anyInterface").

forType("Country") {
    include {
        anyInterfaceDependency()
    }
}

Select any union dependency

fun anyUnionDependency() ↑

Select fields whose type is union. Synonym for dependency("__anyUnion").

forType("Country") {
    include {
        anyUnionDependency()
    }
}

Select any enum dependency

fun anyEnumDependency() ↑

Select fields whose type is enum. Synonym for dependency("__anyEnum").

forType("Film") {
    include {
        anyEnumDependency()
    }
}

Select subtype dependency by pattern

fun subTypeDependency(pattern: String) ↑

Select fields where one of the subtypes matches the pattern.

forAny {
    include {
        subTypeDependency("Actor|Film")
    }
}

Select supertype dependency by pattern

fun superTypeDependency(pattern: String) ↑

Select fields where one of the supertypes matches the pattern.

forAny {
    include {
        superTypeDependency("Taggable|Native")
    }
}

Select argument dependency by pattern

fun argumentDependency(pattern: String) ↑

Select fields where one of the argument types matches the pattern.

forMutation {
    include {
        argumentDependency("ActorInput|FilmInput")
    }
}

Select any scalar argument dependency

fun anyScalarArgumentDependency() ↑

Select fields where one of the arguments is of type scalar. Synonym for argumentDependency("__anyScalar").

forType("Country") {
    exclude {
        anyScalarArgumentDependency()
    }
}

Select any enum argument dependency

fun anyEnumArgumentDependency() ↑

Select fields where one of the arguments is of type enum. Synonym for argumentDependency("__anyEnum").

forMutation {
    include {
        anyEnumArgumentDependency()
    }
}

Select any input argument dependency

fun anyInputArgumentDependency() ↑

Select fields where one of the arguments is of type input object. Synonym for argumentDependency("__anyInput").

forMutation {
    include {
        anyInputArgumentDependency()
    }
}

Select transitive dependency by pattern

fun transitiveDependency(pattern: String) ↑

Select fields where one of the transitive dependencies matches the pattern.

The transitive dependencies of a GraphQL field are all types (except scalars) returned by a query on that field, as well as the types of the field's arguments.

forAny {
    include {
        transitiveDependency("Tag")
    }
}

Select fields whose weight at least the minimum weight

fun minWeight(minWeight: Int) ↑

Select fields whose weight is greater than or equal to the minWeight param.

The weight of a GraphQL type is the number of types (excluding scalars) that are available for querying on a field that returns the given type.

The weight of a GraphQL field is the weight of its type plus the weights of the types of its arguments.

forMutation {
    include {
        minWeight(9)
    }
}

Select fields whose weight not greater than the maximum weight

fun maxWeight(maxWeight: Int) ↑

Select fields whose weight is less than or equal to the maxWeight param.

The weight of a GraphQL type is the number of types (excluding scalars) that are available for querying on a field that returns the given type.

The weight of a GraphQL field is the weight of its type plus the weights of the types of its arguments.

forMutation {
    include {
        maxWeight(9)
    }
}

Home

Clone this wiki locally