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.

When you select the Include extensions checkbox, the output document contains two fields (data and extensions), otherwise, it contains only the content of the data field (for backward compatibility).

Following is a sample output when you select the Include extensions checkbox:

Following is a sample output when you deselect the Include extensions checkbox:

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.

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.

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.
Example: limit

String/Expression/Suggestion

None.

Specify the name of the query variable.

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.

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

Include extensions

Default Value: Deselected

Checkbox/Expression

None

Select this checkbox to include extensions data in the output document of the GraphQL response.

[
{
data: {
queryField1: {
queryField2: {...}
},
...
},
extensions: {
extField1: {...},
...
}
}
]

When you deselect this checkbox, the output document uses the original document structure (to maintain backward compatibility) and contains only the content of the data field.

[
{
queryField1: {
queryField2: {...}
},
...
}
]

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.

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.