Supported GraphQL Query Structures

When using the GRAPHQL() table function, Oracle Database accepts GraphQL queries in multiple standard shapes, including queries that explicitly specify the query operation and an operation name.

The examples earlier in this chapter use the shorthand GraphQL structure, where you specify the root object (table) directly and list the fields you want returned. Oracle Database also accepts additional standard GraphQL query structures as input to the GRAPHQL() table function, which can help when reusing query text from GraphQL client applications and tools.

Shorthand Query Form

This is the structure used throughout the earlier examples, no explicit query keyword is required.

Example 3-2 List Teams with ID and Name

SELECT JSON_SERIALIZE(data PRETTY) AS data
FROM GRAPHQL('
    team {
        teamId: team_id
        teamName: name
    }
');

This query returns the team_id and name of all the teams which was created in Example 1-2 :

{
  "teamId" : 301,
  "teamName" : "McLaren Mercedes"
}
{
  "teamId" : 302,
  "teamName" : "Ferrari"
}
...

Query operation with an operation name

Using a query operation with an operation name allows you to reuse the same GraphQL query text structure commonly used by GraphQL client applications and tools.

Example 3-3 Standard GraphQL query with operation name

The following example specifies the query operation and provides an operation name (getTeams):

SELECT JSON_SERIALIZE(data PRETTY) AS data
FROM GRAPHQL('
    query getTeams {
        team {
            teamId: team_id
            teamName: name
        }
    }
');

The output is identical to the shorthand form shown above (10 rows, one JSON document per team).

Query Operation (Anonymous) Form

You can also provide the query using the standard GraphQL query operation form (without an operation name). This is functionally equivalent to the shorthand form.

Example 3-4 Anonymous GraphQL Query

SELECT JSON_SERIALIZE(data PRETTY) AS data
FROM GRAPHQL('
    query {
        team {
            teamId: team_id
            teamName: name
        }
    }
');

Document with only a Selection Set (curly braces)

GraphQL also allows a document that contains only a selection set enclosed in curly braces. This is commonly produced by some GraphQL tools.

SELECT JSON_SERIALIZE(data PRETTY) AS data
FROM GRAPHQL('
    {
        team {
            teamId: team_id
            teamName: name
        }
    }
');

The output is identical to the shorthand form shown earlier (10 rows, one JSON document per team).

Query operation with variable definitions and PASSING clause

You can define variables in the query text and bind them at execution time using the SQL PASSING clause. This helps keep the query reusable and avoids hardcoding filter values.

Example 3-5 Standard GraphQL query with variables and PASSING clause

Oracle Database also supports GraphQL variables in the standard query form. Define variables in the query text and bind them using the SQL PASSING clause.

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

In this example, the variable $minPoints is defined in the query and assigned a value (200) via the PASSING clause at execution time. The query lists details of all drivers whose points are greater than or equal to 200.

{
  "driverId" : 101,
  "driverName" : "Lando Norris",
  "points" : 282
}
{
  "driverId" : 102,
  "driverName" : "Oscar Piastri",
  "points" : 384
}
...

Note:

The query structures shown above define only how the GraphQL text is wrapped (for example, shorthand form versus query operation form). They do not change query semantics or filtering behavior. You can continue to use the same GraphQL features described in this chapter such as: nested objects, arguments, QBE filtering (check:), directives, and variables bound through the SQL PASSING clause, regardless of which supported structure you use.