Custom GraphQL Directives

In Oracle AI Database’s GraphQL integration, directives play a crucial role in adding expressive power and flexibility to queries and view definitions.

Directives are special annotations, prefixed with @, that instruct the GraphQL processor to alter query behavior, control filtering, shape results, or define advanced behaviors such as join logic. Understanding which directives are available in which contexts : runtime querying (table function) versus duality view creation is essential for developers leveraging Oracle’s advanced GraphQL features.

A directive is identified by '@' (at sign) followed by the name of the directive and the list of arguments for it.

@link (from: ["FK_COL"] to: ["PK_COL"] )

In this example, 'link' is the directive and 'from' , 'to' are it's arguments which takes the values ["FK_COL"] and ["PK_COL"] respectively. The directives, and the argument names are case insensitive.

Directives Supported in GraphQL Table Function

The GraphQL table function in Oracle enables querying relational tables using GraphQL syntax and returning JSON documents. Since its purpose is to fetch and shape data at query time (read operations), only a core set of directives is supported. These focus mainly on data selection, joining, filtering, and transformation.

Supported Directives:

  • On Object/Table-Level Fields:
    • @WHERE: Filters rows according to specified predicates.
    • @ORDERBY: Orders the result set based on given columns.
    • @ARRAY: Returns the result as an array of objects.
    • @OBJECT: Returns the result as a single object.
    • @LINK: Explicitly defines join relationships where automatic PK-FK detection is insufficient.
  • On Scalar/Column-Level Fields:
    • @GENERATED: Allows a field’s value to be generated using a SQL expression. In the context of the table function, only the SQL argument is supported; the PATH argument is not available.

Note:

The directives related to data modification, or those only meaningful at the time of view construction, are not available in the table function context. If you attempt to use non-supported directives in this context, an error will occur.

Directives Used for JSON-Relational Duality View Creation

When defining a JSON-relational duality view (using the CREATE JSON RELATIONAL DUALITY VIEW statement), Oracle AI Database offers a broader range of GraphQL directives. Directives in this context impact how the duality view is created, what operations can be performed through it, and how related data is represented in the resulting JSON.

Supported Directives:
  • @INSERT: Enables insert operations through the duality view.
  • @UPDATE: Enables update operations through the duality view.
  • @DELETE: Enables delete operations through the duality view.
  • @NEST and @UNNEST: Control whether related data is embedded as nested objects or unnested.
  • @LINK: Defines join conditions explicitly, particularly important for complex relationships.
  • @ARRAY and @OBJECT: Specify the arrangement of data within the JSON output.
  • @WHERE: Adds filter clauses as part of the view definition.
  • @ORDERBY: Establishes default sort order for data in the view.
  • @GENERATED: Used for both fields and sub-objects, taking either SQL or PATH as arguments, giving flexibility in computed fields and references.

These additional directives are critical when defining duality views to address advanced scenarios, such as updatable JSON views and complex relationships between tables.

Below is a summary differentiating the availability of directives between runtime table function queries and duality view creation:

Table 3-1 Custom Directives Comparison Table

Directive Table Function (Query) Duality View Creation
@WHERE ✔ ✔
@ORDERBY ✔ ✔
@ARRAY ✔ ✔
@OBJECT ✔ ✔
@LINK ✔ ✔
@GENERATED ✔ (SQL only) ✔ (SQL, PATH)
@INSERT X ✔
@UPDATE/@NOUPDATE X ✔
@DELETE X ✔
@CHECK/@NOCHECK X ✔
@NEST/@UNNEST X ✔
@FLEX X ✔
@HIDDEN X ✔
@CAST X ✔