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 processing, control filtering, shape results, or define advanced features 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 not case-sensitive.

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.

  • @NEST and @UNNEST: Controls nesting and unnesting (flattening) of intermediate objects to shape the JSON output.

  • @HIDDEN: Hides a scalar field from the output.

• 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.

  • @HIDDEN: Hides a scalar field from the output.

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:

• @WHERE: Adds filter clauses as part of the view definition.

• @ORDERBY: Establishes default sort order for data in the view.

• @ARRAY and @OBJECT: Specify the arrangement of data within the JSON output.

• @LINK: Defines join conditions explicitly, particularly important for complex relationships.

• @GENERATED: Used for both fields and sub-objects, taking either SQL or PATH as arguments, giving flexibility in computed fields and references.

• @NEST and @UNNEST: Control whether related data is embedded as nested objects or unnested.

• @HIDDEN: Hides fields from the resulting JSON output.

Duality View-Specific Directives:

• @INSERT and @NOINSERT: Enables insert operations through the duality view.

• @UPDATE and @NOUPDATE: Enables update operations through the duality view.

• @DELETE: Enables delete operations through the duality view.

• @IDENTIFIEDBY: Specifies the fields that identify rows for a table in a duality view.

• @CHECK and @NOCHECK: Controls whether a field is included in the ETAG calculation for JSON-relational duality view documents.

• @FLEX: Enables flexible schema by exposing dynamic fields from JSON columns.

• @ALIAS: Provides an alternative name for a table or field.

• @CAST: Enables type conversion or casting within the duality view.

Starting in 23.26.3, @delete can also be used with shared dimension tables. A shared row is deleted only when no child row references it, and the shared table joining columns must have an enabled RESTRICT foreign-key constraint.

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

The following summary differentiates the availability of directives between runtime table function queries and duality view creation:

Table 1 Custom Directives Comparison Table

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

• @WHERE Directive
  Use the @WHERE directive for filtering specific information from a larger dataset.

• @ORDERBY Directive
  The directive @orderby provides an orderby clause on the field in which it is specified.

• @ARRAY Directive
  The @array directive can be used to explicitly shape the nested object as an array.

• @OBJECT Directive
  The @object directive can be used to explicitly shape the nested object as an object.

• @LINK Directive
  The @LINK directive disambiguates multiple foreign-key relationships between tables or to specify self-referencing foreign keys within the same table.

• @GENERATED Directive
  Directive @generated generates a field from existing fields/columns of the table or from SQL expressions.

• @NEST and @UNNEST Directives
  Directives @nest and @unnest specify nesting and unnesting (flattening) of intermediate objects in both table function as well as in duality-view definition.

• @FLEX Directive
  The @flex GraphQL directive in Oracle is used to designate a column typically of JSON data type as a flex column. @flex directive is used with JSON relational duality views and is not supported in the GraphQL table function.

• @HIDDEN Directive
  The @hidden GraphQL directive in Oracle is used to hide a JSON field in the output. Starting in 23.26.1, @hidden can be used both in duality view creation and in GraphQL table function queries.

• @SKIP and @INCLUDE Directives
  The directives @skip and @include allow conditional inclusion of fields at query time.

• @ALIAS Directive
  The directive @alias provides an alternative name to the table on which the field is specified.