Query and Variable Descriptions, and Default Variable Values

GraphQL supports descriptions to provide documentation for operations and variables.

These descriptions are intended to improve readability and maintainability, and are analogous to documentation strings in GraphQL tools. Oracle AI Database supports query descriptions and variable descriptions in GraphQL input text. Oracle also supports default values for variables in the query definition. A default value is used when no overriding value is supplied at execution time.

Query Description (string)

You can provide a query description as a quoted string immediately before the query operation.

Example 3-25 Query description (string): List drivers with a minimum points threshold

SELECT JSON_SERIALIZE(data PRETTY) AS data
FROM GRAPHQL('
    "List drivers with a minimum points threshold"
    query getDrivers($minPoints: Int!) {
        driver (check: {points: {_gte: $minPoints}}) {
            driverId: driver_id
            driverName: name
            points
        }
    }
' passing 200 as "minPoints");

In this example:

• The description string documents the purpose of the query.

• The variable $minPoints is defined in the query and assigned a value at runtime using the SQL PASSING clause.

Output lists the details of drivers whose points are at least 200:

{
  "driverId" : 101,
  "driverName" : "Lando Norris",
  "points" : 282
}
{
  "driverId" : 102,
  "driverName" : "Oscar Piastri",
  "points" : 384
}
{
  "driverId" : 103,
  "driverName" : "Charles Leclerc",
  "points" : 312
}
{
  "driverId" : 104,
  "driverName" : "Carlos Sainz Jr.",
  "points" : 340
}
{
  "driverId" : 105,
  "driverName" : "Max Verstappen",
  "points" : 456
}
{
  "driverId" : 107,
  "driverName" : "Lewis Hamilton",
  "points" : 240
}
{
  "driverId" : 108,
  "driverName" : "George Russell",
  "points" : 228
}

Variable descriptions (string or block string) and default values

You can provide descriptions for variables using either an ordinary string or a block string ("""..."""). You can also specify default values as part of the variable definition.

Example 3-26 Variable descriptions (string or block string) and default values

SELECT JSON_SERIALIZE(data PRETTY) AS data
FROM GRAPHQL('
    query getTeams(
        "Minimum points to include" $minPoints: Int = 200
        """Optional team name filter""" $teamName: String = "McLaren Mercedes"
    ) {
        team (name: $teamName) {
            teamId: team_id
            teamName: name
            teamPoints: points
            driver (check: {points: {_gte: $minPoints}}) {
                driverId: driver_id
                driverName: name
                points
            }
        }
    }
' passing 'Ferrari' as "teamName");

In this example:

• $minPoints has a default value of 200, and will be used if no value is passed at runtime.

• $teamName has a default value of “McLaren Mercedes”, but it is overridden at runtime using the PASSING clause.

• Variable descriptions are included to document the intent of each variable.