GraphQL
GraphQL Data Connector Documentation
Last updated
Was this helpful?
GraphQL Data Connector Documentation
Last updated
Was this helpful?
The Data Connector enables federated SQL queries on any GraphQL endpoint by specifying graphql
as the selector in the from
value for the dataset.
Limitations
The GraphQL data connector does not support variables in the query.
Filter pushdown, with the exclusion of LIMIT
, is not currently supported. Using a LIMIT
will reduce the amount of data requested from the GraphQL server.
from
The from
field takes the form of graphql:your-graphql-endpoint
.
name
The dataset name. This will be used as the table name within Spice.
params
unnest_depth
Depth level to automatically unnest objects to. By default, disabled if unspecified or 0
.
graphql_auth_token
The authentication token to use to connect to the GraphQL server. Uses bearer authentication.
graphql_auth_user
The username to use for basic auth. E.g. graphql_auth_user: my_user
graphql_auth_pass
The password to use for basic auth. E.g. graphql_auth_pass: ${secrets:my_graphql_auth_pass}
graphql_query
json_pointer
Example using the GitHub GraphQL API and Bearer Auth. The following will use json_pointer
to retrieve all of the nodes in starredRepositories:
The query must have the correct pagination arguments in the associated paginated field.
Forward Pagination:
Backward Pagination:
You can access the fields of the object using the square bracket notation. Arrays are indexed from 1.
Example query:
You can also use the unnest_depth
parameter to control automatic unnesting of objects from GraphQL responses.
This examples uses the GitHub stargazers endpoint:
If unnest_depth
is set to 0, or unspecified, object unnesting is disabled. When enabled, unnesting automatically moves nested fields to the parent level.
Without unnesting, stargazers data looks like this in a query:
With unnesting, these properties are automatically placed into their own columns:
By default, the Spice Runtime will error when a duplicate column is detected during unnesting.
For example, this example spicepod.yml
query would fail due to name
fields:
This example would fail with a runtime error:
The example below uses a GraphQL alias to rename emergency_contact.name
as emergencyContactName
.
The GraphQL data connector can be configured by providing the following params
. Use the to load the password from a secret store, e.g. ${secrets:my_graphql_auth_token}
.
The username to use for basic auth. See for a sample GraphQL query
The into the response body. When graphql_query
is , the json_pointer
can be inferred.
The GraphQL Data Connector supports automatic pagination of the response for queries using .
The graphql_query
must include the pageInfo
field as per . The connector will parse the graphql_query
, and when pageInfo
is present, will retrieve data until pagination completes.
Tips for working with JSON data. For more information see .
Example for the stargazers query from :
You can use Datafusion unnest
function to pipe values from array into rows. We'll be using as an example.
Avoid this error by where possible. In the example above, a duplicate error was introduced from emergency_contact { name }
.