GraphQL Client
In this article
Overview
You can use this Snap to run queries and access resources on a GraphQL endpoint. This Snap includes a built-in query builder that enables you to build queries with optimal efficiency. GraphQL queries provide a flexible and efficient way to fetch data from a server by allowing clients to retrieve precisely the data they require, minimizing the amount of unnecessary data transferred over the network.
Snap Type
The GraphQL Client Snap is a Read-type Snap that queries a GraphQL endpoint and retrieves data.
Prerequisites
A valid API Suite account with the required permissions. An API Suite account is required only if the GraphQL end point requires credentials to function. Otherwise, the account can be omitted.
A GraphQL end point, which is the server URL.
A GraphQL schema defined on the server.
Pagination prerequisites:
In the schema provided by the server at the GraphQL endpoint, the root field that you want to query must implement cursor based pagination. It should use field parameters that enable pagination to be controlled by the user-defined variables at the top level of your GraphQL query (and pass them as arguments to the root field).
The schema must contain a
Boolean
field whose return value indicates the presence of additional pages of data.The schema must contain a field whose value can be used to represent
Position
in the queried data (acting as a cursor). The field’s value must be usable directly for this purpose (without transformation or combination with another field’s value).
Support for Ultra Pipelines
Works in Ultra Pipelines.
Limitations
This Snap does not support subscriptions.
For key-value pairs defined in the GraphQL variables settings, string values must be contained in double quotes (
" "
).
Behavior Changes
The improved error-handling mechanism (to reflect how errors are reported in the raw GraphQL responses) in the GraphQL Client Snap has resulted in the following behavior changes:
Error output:
Any error document caused by an error reported in the GraphQL Client Snap response now has a generic error message, similar to the errors reported by the GraphQL server while processing requests. The specific error message (and other additional details) are now available under the
graphqlErrors
field of the error document.Data for all GraphQL errors reported for a single request (or single page request when pagination is enabled) is now available in the same error document under the
graphqlErrors
field.Any error document generated by an error reported in the GraphQL Client Snap response now includes the query and variables for the request that caused it in the
query
andgraphqlVariables
fields, respectively.
If you want to access the same error message string that is written to the error
field in the previous Snap version (because it is now generalized to mimic the error reporting of the GraphQL endpoint), you can access the previous error output with the following expression:
jsonPath($, "$graphqlErrors[0].message")
Standard output:
Before: The GraphQL Client Snap returned no output document for the partially successful requests.
After: The Snap now returns the successful data processed from the GraphQL response in the output document, even if some GraphQL errors are also reported.
You can check downstream Snaps of the GraphQL Client Snap to verify if the Snaps appropriately handle successful output especially when the output wasn’t expected before, or a mix of error documents and successful output documents.
Pagination:
When you enable pagination (wherein each input document may trigger multiple GraphQL requests for separate pages as you process the document), GraphQL errors in the response of one page will not cause page requests to stop early. Subsequent pages will continue to be requested as long as the data necessary to prepare the next page request is available in the previous page’s response.
Snap Views
Type | Format | Number of Views | Examples of Upstream and Downstream Snaps | Description |
---|---|---|---|---|
Input | Document
|
|
| Each input document includes a set of variables that are used to create the GraphQL query. You can use the input view for GraphQL variables, but it’s not required. |
Output | Document
|
|
| Each output document contains data retrieved from the GraphQL server.
|
Error | Error handling is a generic way to handle errors without losing data or failing the Snap execution. You can handle the errors that the Snap might encounter when running the pipeline by choosing one of the following options from the When errors occur list under the Views tab:
Learn more about Handling Errors with an Error Pipeline. |
Snap Settings
Asterisk ( * ): Indicates a mandatory field.
Suggestion icon (): Indicates a list that is dynamically populated based on the configuration.
Expression icon ( ): Indicates the value is an expression (if enabled) or a static value (if disabled). Learn more about Using Expressions in SnapLogic.
Add icon ( ): Indicates that you can add fields in the field set.
Remove icon ( ): Indicates that you can remove fields from the field set.
Upload icon ( ): Indicates that you can upload files.
Field Name | Field Type | Field Dependency | Description | |
---|---|---|---|---|
Label*
Default Value: GraphQL Client | String | None. | Specify a unique name, especially if you have more than one of the same Snap in your pipeline.
| |
GraphQL endpoint*
Default Value: None. | String | None. | Specify the server URL that the Snap uses to connect to the GraphQL endpoint. | |
Query builder | Button | None. | If you need help to form the query, click on this button to open the query builder. If the account is valid, the fields available from the server schema appear on the left side of the query builder. You can choose any fields to query on by clicking the dropdown lists and checkboxes. The formed query appears on the right. Click Ok to close the UI component and the query appears in under Query in the Snap Settings. | |
Query
Default Value: None. | String | None. | ||
GraphQL variables | Use this field set to add query parameters to be included in the request. This is optional and can either be defined directly in the URL, as separate parameters, or both. | |||
Variable name
Default value: None. | String/Expression/Suggestion | None. | Specify the name of the query variable. | |
Variable value
Default value: None. | String/Expression | None. | Specify the value to assign to the variable. | |
Client settings | Additional settings for the GraphQL Client. | |||
Trust all certificates
Default Value: Not selected | Checkbox | None. | Select this checkbox to trust all certificates, such as self-signed certificates. | |
Follow redirects
Default Value: Selected | Checkbox | None. | Select this checkbox to accept the response and redirect the request. | |
Maximum number of redirects
Default Value: 10 | Integer/Expression | None. | Specify the maximum number of redirects to allow. | |
Read timeout (seconds)
Default Value: 900 | Integer | None. | Specify the number of seconds that the Snap must wait before terminating the request because of a failure to read from the target service. | |
Connection timeout (seconds)
Default Value: 30 | Integer | None. | Specify the number of seconds that the Snap must wait before terminating the request because of a failure to establish a connection to the target endpoint or service. | |
Enable pagination Default Value: Not selected | Checkbox | None. | Select this checkbox to return multiple pages of results through repeated requests with the GraphQL query.
| |
Pagination properties | Use this field set to define pagination settings related to query executions that make multiple requests for pages of data. | |||
Max page count
Default Value: 3 | Integer | Appears when you select the Enable pagination checkbox | Specify the maximum number of pages of data to retrieve, if enough data is available. This value is the number of times a request is made with the specified query. The Snap stops fetching the next page when the maximum number of pages is reached.
| |
Pagination type*
Default Value: Cursor | Dropdown list | Appears when you select the Enable pagination checkbox | Select the type of pagination to use for the GraphQL query. Currently, this Snap supports only cursor-type pagination.
| |
Has additional page path*
Default Value: N/A | String | Appears when you select the Enable pagination checkbox | Specify the path to the field in the GraphQL schema that indicates whether an additional page of data is available. You can define only one Has additional page path and one Next cursor path for the query. | |
Next cursor path*
Default Value: None | String | Appears when you select the Enable pagination checkbox | Specify the path to the field in the GraphQL schema that contains the cursor value for subsequent page requests. The path should start at the root field, not at the user-defined top-level query. This path represents the location in the specified query’s payload that contains the value to be used as the cursor in the next page request. You can define only one Has additional page path and one Next cursor path for the query. | |
Cursor variable name*
Default Value: None | String/Expression/Suggestion | Appears when you select the Enable pagination checkbox | Specify the name of the GraphQL variable that holds the cursor used for pagination. This variable is passed as the cursor value within the query. The cursor variable name is validated against the variable names parsed from the top-level query defined in the Query field. If the cursor variable name does not match one of these parsed variable names, the Snap fails with an error. NOTE: Ensure that the variable name you enter in this field matches the name of the variable that is mapped to the cursor parameter of the root field. If you use the wrong variable name in this field, then the cursor data for the next request could be sent to the wrong root field parameter instead of to the cursor parameter. This could result in multiple requests returning identical data (when Max page count is provided) or an infinite loop of requests (when Max page count is left blank). | |
Include extensions Default Value: Deselected | Checkbox/Expression | None | Select this checkbox to include
When you deselect this checkbox, the output document uses the original document structure (to maintain backward compatibility) and contains only the content of the
| |
Snap Execution Default Value: Execute only | Dropdown list | N/A | Select one of the following three modes in which the Snap executes:
|
Troubleshooting
Error | Reason | Resolution |
---|---|---|
This endpoint requires you to be authenticated | The account information is incorrect. | Verify the accuracy of the credentials to ensure that the account is properly configured. After updating, save the Snap to preserve the changes. |
Unexpected end of the document | The query is incorrect. | Review your query and make the necessary corrections. Check for missing closing braces '}', ensuring all specified fields exist in the schema. Use the Query Builder button if you need help to construct the query. |
Field | The query is incorrect. | Review your query and make the necessary corrections. Check for missing closing braces '}', ensuring all specified fields exist in the schema. Use the Query Builder button if you need help to construct the query. |
GraphQL server responded with a query error | The specified path for the Next cursor path was not found in the query response. | Ensure that the GraphQL query includes the targeted path and that the Next cursor path setting is correct. |
Selected pagination type is invalid | The selected pagination type is not supported. | Select a supported pagination type. |
Examples
Insert, Update, Delete, and Query a GraphQL Endpoint
Prerequisite: A valid account to access the resources from the endpoint.
The following example pipeline demonstrates how to use the GraphQL Client Snap to insert, update, delete, and query the schema provided by the server at the specified GraphQL endpoint.
Specify the GraphQL endpoint and then enter a query or a mutation in the Query text box.
Alternatively, click the Query builder button to open a GUI query builder that contains all the available objects and fields.In this example, the following mutation operation inserts an employee record for Jane into the server data.
mutation MyMutation {
insert_emp(objects: {id: 123, name: "Jane", salary: 1000}) {
affected_rows
returning {
id
name
salary
}
}
}
Configure another GraphQL Client Snap to update the employee record in the server data.
In this example, the following mutation operation updates the name from Jane to Janet.
mutation MyMutation {
update_emp(where: {id: {_eq: 123}}, _set: {name: "Janet"}) {
affected_rows
returning {
id
name
salary
}
}
}
Configure another GraphQL Client Snap to delete the employee record from the server data.
In this example, the following mutation operation deletes the employee record from the server data.
mutation MyMutation {
delete_emp(where: {name: {_eq: "Janet"}}) {
affected_rows
returning {
id
name
salary
}
}
}
Finally, configure a GraphQL Client Snap to query the data for all the employee records on the server.
In this example, the following query retrieves all the employee records from the server.
query MyQuery {
emp {
id
name
salary
}
}
Downloads
Snap Pack History