9 GraphQL Language Used for JSON-Relational Duality Views

GraphQL is an open-source, general query and data-manipulation language that can be used with various databases. A subset of GraphQL syntax and operations are supported by Oracle Database for creating JSON-relational duality views.

This chapter describes this supported subset of GraphQL. It introduces syntax and features that are not covered in Creating Car-Racing Duality Views Using GraphQL, which presents some simple examples of creating duality views using GraphQL.

The Oracle syntax supported for creating duality views with GraphQL is a proper subset of GraphQL as specified in Sections B.1, B.2, and B.3 of the GraphQL specification (October 2021), except that user-supplied names must follow satisfy some Oracle-specific rules specified here.

The Oracle GraphQL syntax also provides some additional, optional features that facilitate use with JSON-relational duality views. If you need to use GraphQL programmatically, and you want to stick with the standard GraphQL syntax, you can do that. If you don't have that need then you might find the optional syntax features convenient.

For readers familiar with GraphQL, the supported subset of the language does not include these standard GraphQL constructs:

  • Mutations and subscriptions. Queries are the only supported operations.

  • Inline fragments. Only a predefined FragmentSpread syntax is supported.

  • Type definitions (types interface, union, enum, and input object, as well as type extensions). Only GraphQL Object and Scalar type definitions are supported.

  • Variable definitions.

Using GraphQL to define a duality view has some advantages over using SQL to do so. These are covered in Creating Car-Racing Duality Views Using GraphQL. In sum, the GraphQL syntax is simpler and less verbose. Having to describe the form of supported documents and their parts using explicit joins between results of JSON-generation subqueries can be a bother and error prone.

Oracle GraphQL support for duality views includes these syntax extensions and simplifications:

  1. Scalar Types

    Oracle Database supports additional GraphQL scalar types, which correspond to Oracle JSON-language scalar types and to SQL scalar types. See Oracle GraphQL Scalar Types.

  2. Implicit GraphQL Field Aliasing

    A GraphQL field name can be preceded by an alias and a colon (:). Unaliased GraphQL field names in a duality-view definition are automatically taken as aliases to the actual GraphQL field names. In effect, this is a shorthand convenience for providing case-sensitive matching that corresponds to field names in the documents supported by the duality view. See Implicit GraphQL Field Aliasing.

  3. GraphQL Directives For Duality Views

    Oracle GraphQL provides directives (@link, @[un]nest, @flex, @generated, and @hidden), which specify particular handling when defining duality views. See Oracle GraphQL Directives for JSON-Relational Duality Views.

  4. GraphQL Names in Duality-View Definitions

    If the table and column names you use in a duality-view definition are directly usable as standard GraphQL field names then they are used as is. This is the case, for instance in the car-racing duality views.

    More generally, a duality-view definition specifies a mapping between (1) JSON field names, (2) GraphQL type and field names, and (3) SQL table and column names. The first two are case-sensitive, whereas unquoted SQL names are case-insensitive. Additionally, the characters allowed in names differ between GraphQL and SQL.

    For these reasons, Oracle relaxes and extends the unquoted GraphQL names allowed in duality-view definitions.

    See Names Used in GraphQL Duality-View Definitions.

Oracle GraphQL Scalar Types

Table 9-1 lists the Oracle-supported GraphQL scalar types that correspond to Oracle JSON scalar types and to Oracle SQL scalar types. It lists both standard GraphQL types and custom, Oracle-specific GraphQL types.

Table 9-1 Scalar Types: Oracle JSON, GraphQL, and SQL

Oracle JSON-Language Scalar Type GraphQL Scalar Type SQL Scalar Type

binary

Binary (Oracle-specific)

 RAW or BINARY

date

Date (Oracle-specific)

DATE

day-second interval

DaysecondInterval (Oracle-specific)

INTERVAL DAY TO SECOND

double

Float (standard GraphQL)

BINARY_DOUBLE

float

Float (standard GraphQL)

BINARY_FLOAT

timestamp

Timestamp (Oracle-specific)

TIMESTAMP

vector

Vector (Oracle-specific)

VECTOR

timestamp with time zone

TimestampWithTimezone (Oracle-specific)

TIMESTAMP WITH TIME ZONE

year-month interval

 YearmonthInterval (Oracle-specific)

INTERVAL YEAR TO MONTH

Implicit GraphQL Field Aliasing

The body of a duality view definition is a GraphQL query. If a GraphQL field name is used in that query with no alias then it is matched case-insensitively to pick up the actual GraphQL field name. In a standard GraphQL query, such matching is case-sensitive.

This convenience feature essentially provides the unaliased field with an alias that has the lettercase shown in the view definition; that is, it's taken case-sensitively. The alias corresponds directly with the JSON field name used in supported documents. The actual GraphQL field name is derived from a SQL table or column name.

For example, if a GraphQL field name is defined as myfield (lowercase), and a duality view-creation query uses myField then the queried field is implicitly treated as if it were written myField : myfield, and a JSON document supported by the view would have a JSON field named myField.

Names Used in GraphQL Duality-View Definitions

Oracle relaxes and extends the unquoted GraphQL names allowed in duality-view definitions. This is done to facilitate (1) specifying the field names of the JSON documents supported by a duality view and (2) the use of SQL identifier syntax (used for tables and columns) in GraphQL names.

If none of the names you use in a GraphQL duality-view definition contain the period (dot) character, (.) or need to be quoted, then the corresponding GraphQL schema is fully compliant with the GraphQL standard. In this case, it should work with all existing GraphQL tools.

Otherwise (the more typical case), it is not fully standard-compliant. It can be used to create a JSON-relational duality view, but it might not work correctly with some GraphQL tools.

Standard GraphQL names are restricted in these ways:

  • They can only contain alphanumerical ASCII characters and underscore (_) characters.

  • They cannot start with two underscore characters: __.

SQL names, if quoted, can contain any characters except double-quote (") (also called quotation mark, code point 34) and null (code point 0). Unquoted SQL names can contain alphanumeric characters (ASCII or not), underscores (_), number signs (#), and dollar signs ($). A fully qualified table name contains a period (dot) character (.), separating the database schema (user) name from the table name.

The following rules apply to GraphQL names allowed in duality-view definitions. The last of these rules applies to fully qualified SQL table names, that is, to names of the form <schema name>.<table name>, which is composed of three parts: a database schema (user) name, a period (dot) character (.), and a database table name. The other rules apply to SQL names that don't contain a dot.

  • The GraphQL name that corresponds to a quoted SQL name (identifier) is the same quoted name.

    For example, "this name" is the same for SQL and GraphQL.

  • The GraphQL name that corresponds to an unquoted SQL name that is composed of only ASCII alphanumeric or underscore (_) characters is the same as the SQL name, except that:

    • A GraphQL field name is lowercase.

      For example, GraphQL field name MY_NAME corresponds to SQL name my_name.

    • A GraphQL type name is capitalized.

      For example, GraphQL type name My_name corresponds to SQL name MY_NAME.

  • The GraphQL name that corresponds to an unquoted SQL name that has one or more non-ASCII alphanumeric characters, number sign (#) characters, or dollar sign ($) characters is the same name, but uppercased and quoted. (In Oracle SQL, such a name is treated case-insensitively, whether quoted or not.)

    For example, GraphQL name "MY#NAME$4" corresponds to SQL name my#name$4

  • The GraphQL name that corresponds to a fully qualified SQL table name, which has the form <schema name>.<table name>, is the concatenation of (1) the GraphQL name corresponding to <schema name>, (2) the period (dot) character (.), and (3) the GraphQL name corresponding to <table name>. Note that the dot is not quoted in the GraphQL name.

    Examples for fully qualified SQL names:

    • GraphQL name My_schema.Mytable corresponds to SQL name MY_SCHEMA.MYTABLE.

    • GraphQL name "mySchema".Mytable corresponds to SQL name "mySchema".mytable.

    • GraphQL name "mySchema"."my table" corresponds to SQL name "mySchema"."my table".

    • GraphQL name "Schema#3.Table$4" corresponds to SQL name SCHEMA#3.TABLE$4.

_________________________________________________________

See Also:

Graph QL

Related Topics