In this article

1 Overview
- 1.1 Snap Type
- 1.2 Prerequisites
- 1.3 Support for Ultra Pipelines
- 1.4 Limitations
2 Snap Views
3 Snap Settings
4 Troubleshooting
5 Examples
- 5.1 Insert, Update, Delete, and Query a GraphQL Endpoint
6 Downloads
7 Snap Pack History

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 (" ").

Snap Views

Type	Format	Number of Views	Examples of Upstream and Downstream Snaps	Description

Type

Format

Number of Views

Examples of Upstream and Downstream Snaps

Description

Input

Document

Min: 0
Max: 1

Mapper
Copy
JSON Parser

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

Min: 0
Max: 1

Mapper
Copy
Filter

Each output document contains data retrieved from the GraphQL server.

If the Snap fails to retrieve the data, an error is written to the output document error view containing the fields error, reason, resolution, and stacktrace. To view the error document, you must enable the Error view.

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:

Stop Pipeline Execution: Stops the current pipeline execution if the Snap encounters an error.
Discard Error Data and Continue: Ignores the error, discards that record, and continues with the remaining records.
Route Error Data to Error View: Routes the error data to an error view without stopping the Snap execution.

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

Field Name		Field Type	Field Dependency	Description
Label* Default Value: GraphQL Client Example: myGraphQL (SWAPI)		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. Example: https://api.github.com/graphql		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. Example: `query MyQuery {` `rateLimit {` `cost` `}` `}`		String	None.	Enter the query in this text box. If you need help to form the query, click on the Query builder button to open the query builder. A GraphQL query follows a hierarchical structure that matches the schema of the GraphQL API. It starts with a root query object and includes nested fields and relationships as needed. The query is sent to the GraphQL server, which processes the request and returns a response containing the requested data in the exact format specified by the client.
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. Click the plus icon () to add a new variable.
	Variable name Default value: None. Example: limit	String/Expression/Suggestion	None.	Specify the name of the query variable. String values must be enclosed in double quotes (`" "`).
	Variable value Default value: None. Example: 1 ”this is a string”	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 Example: 5	Integer/Expression	None.	Specify the maximum number of redirects to allow.
	Read timeout (seconds) Default Value: 900 Example: 60	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 Example: 60	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. If this checkbox is selected, multiple requests to the query are made as defined in the pagination properties. If this checkbox is not selected, only a single request to the query is made.
Pagination properties	Use this field set to define pagination settings related to query executions that make multiple requests for pages of data. Best practices: We recommend that you limit your GraphQL query to only one root field when pagination is enabled. If you define multiple root fields in the query when pagination is enabled, it could cause duplicated data or produce unexpected results. Use clear, descriptive names when defining GraphQL variables to ensure that you use the correct variables for the correct purposes, especially when defining the Cursor variable name.
	Max page count Default Value: 3 Example: 7	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. This value must be greater than 0. If you do not enter any value in this field, pages are requested until end of the data is reached. Requests with the query continue to be made until the value query response at the location defined by Has additional page path is false (no additional data can be returned by an additional request).
	Pagination type* Default Value: Cursor Example: 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 Example: allEmployees.pageInfo.hasNextPage	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. The path should start at the root field, not at the user-defined top-level query. You can define only one Has additional page path and one Next cursor path for the query. For this reason, we recommend that you include only one root field in the GraphQL query.
	Next cursor path* Default Value: None Example: allEmployees.pageInfo.endCursor	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. For this reason, we recommend that you include only one root field in the GraphQL query.
	Cursor variable name* Default Value: None Example: afterCursor	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).
Snap Execution Default Value: Execute only Example: Validate & Execute		Dropdown list	N/A	Select one of the following three modes in which the Snap executes: Validate & Execute: Performs limited execution of the Snap, and generates a data preview during pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during pipeline runtime. Execute only: Performs full execution of the Snap during pipeline execution without generating preview data. Disabled: Disables the Snap and all Snaps that are downstream from it.

Troubleshooting

Error	Reason	Resolution

Error	Reason	Resolution
This endpoint requires you to be authenticated	The account information is incorrect.	Ensure that the account is properly configured by verifying the accuracy of the credentials. After updating, save the Snap to preserve the changes.
Unexpected end of document	The query is incorrect.	Review your query and make 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 <name of field> doesn't exist on type <name of type>	The query is incorrect.	Review your query and make 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
}
}

Download this pipeline.

Downloads

Important steps to successfully reuse Pipelines

Download and import the Pipeline into SnapLogic.
Configure Snap accounts as applicable.
Provide Pipeline parameters as applicable.

	File	Modified
Labels No labels Preview View	File GraphQL Client - Query and Mutations.slp	May 15, 2023 by Cindy Hall