GraphQL Connector (Preview)

The GraphQL connector simplifies integration with GraphQL data sources by converting GraphQL objects into relational tables, allowing for complex queries to be executed effortlessly. This enables the seamless combination of GraphQL's flexible data fetching with powerful data management, streamlining data access and manipulation.

Type Name

graphql

Connection Properties

Template name: ws

Appropriate translator name: graphql

Data Source Creation

Data sources can be created using SQL queries, as illustrated in the following examples:

--Without pagination
CALL SYSADMIN.createConnection(name => 'railway', jbossCliTemplateName => 'ws', connectionOrResourceAdapterProperties => 'EndPoint=https://spacex-production.up.railway.app,decompressCompressedFiles=false,SecurityType=None', encryptedProperties => '') ;;
CALL SYSADMIN.createDatasource(name => 'railway', translator => 'graphql', modelProperties => 'importer.graphqlUrl=graphql', translatorProperties => '', encryptedModelProperties => '', encryptedTranslatorProperties => '') ;;

--With pagination
CALL SYSADMIN.createConnection(name => 'rickandmorty', jbossCliTemplateName => 'ws', connectionOrResourceAdapterProperties => 'EndPoint=https://rickandmortyapi.com,decompressCompressedFiles=false,SecurityType=None', encryptedProperties => '') ;;
CALL SYSADMIN.createDatasource(name => 'rickandmorty', translator => 'graphql', modelProperties => 'importer.graphqlUrl=graphql,graphql.pagingStrategy=NextPageInfoInResponse,graphql.paging.nextPage=info.next,graphql.paging.nextPageInputArg=page', translatorProperties => '', encryptedModelProperties => '', encryptedTranslatorProperties => '') ;;

Data Source Properties

Usage

The CData Virtuality Server represents GraphQL objects as tables and their fields as table columns preserving the same names.

Nested Non-array Objects

Nested non-array objects are flattened into table columns, adhering to the convention <parent field name>_<child field name>. Presently, a maximum of 5 levels beneath the root object are supported. For instance, consider the SQL query:

SELECT id, name, second_stage_payloads_composite_fairing_diameter_feet, second_stage_thrust_kN, second_stage_engines FROM "railway.rockets" ;;

It is translated into the following GraphQL query:

query {
  rockets {
    id
    name
    second_stage {
      payloads {
        composite_fairing {
          diameter {
            feet
          }
        }
      }
      thrust {
        kN
      }
      engines
    }
  }
}

Array Fields

Array fields are mapped to separate child tables, with one table for each array field. These child tables include all columns from the parent table and those of the objects within the parent's array field. Values from parent columns are duplicated for the same parent across each distinct value in its array field, effectively simulating a join. For instance, if the launchesUpcoming object contains an array field named ships, it will be represented in CData Virtuality as a launchesUpcoming parent table and a launchesUpcoming_ships child table. The child table will include all columns from the parent table, in addition to columns for each object in the ships array.

Query Input Arguments

Query input arguments are mapped to table columns, prefixed with arg_. For example, find_landings is mapped to arg_find_landings, as demonstrated in the following SQL query:

SELECT "id", "landings" FROM "railway.capsules" WHERE "arg_find_landings" = 5 ;;

Fields of nested input objects are flattened following the same convention as output object types' fields. It's important to note that array input arguments are not currently supported. Consider the example below, where landing is nested within find:

SELECT * FROM "railway.capsules" WHERE "arg_find_landings" = 5 AND "status" = 'active';;

Filtering results

Filter criteria specified in WHERE clauses are forwarded to the GraphQL service if they are query input arguments. Those that are not query input arguments are filtered in CData Virtuality Server memory. For example, in the query:

SELECT * FROM "railway.capsules" WHERE "arg_find_landings" = 5 AND "status" = 'active' ;;

arg_find_landings is pushed as an input argument into the GraphQL query and then filtered by status on the CData Virtuality side when the result set is obtained from the GraphQL service. If the input argument is mandatory, the remaining filtering criteria should be added with an AND and enclosed in brackets, as in the following example:

SELECT * FROM "railway.mission" where arg_id = '1' AND ("description" IS NOT NULL OR "name" IS NOT NULL) ;;

Otherwise, the "The following mandatory filter criteria have not been specified" error will be thrown.

Pagination

Automatic paging is supported if configured, meaning the SQL query will be automatically translated into multiple GraphQL queries to fetch all response pages. To configure paging per data source, use the model properties described above, which have the graphql.paging prefix in their names.

If the paging input argument is explicitly specified in the command, CData Virtuality does not perform automatic paging, as the client has indicated the paging information themselves. For example, in the query:

SELECT * FROM "rickandmorty.locations_results" WHERE arg_page = 2 ;;

CData Virtuality simply forwards the query to the target GraphQL service and does not perform any automatic paging.

Limitations

• Only 5 levels of nesting beneath the root object are currently supported for non-array nested objects;
• Array input arguments are not supported;
• Only input arguments are pushed down from all criteria passed in the WHERE part of the query;
• The only supported paging strategy is "NextPageInfoInResponse".

GraphQL connector available since v4.3