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
Name | Description | Default |
---|---|---|
| Sub-path to the GraphQL service endpoint |
|
| Root query field in the GraphQL schema |
|
| The paging strategy to be used currently supports only the "NextPageInfoInResponse" value |
|
| Path of the field containing the input argument for the next page |
|
| Path to the field indicating whether more pages are available |
|
| Input argument specifying the next page in the query |
|
| Path of the input argument that contains the page size value. This is optional; if not configured, the page size will not be specified in queries, leaving it to the GraphQL service to determine the number of rows to return along with information about the next page |
|
| Page size value specified for each pageable query |
|
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".