Connections

ConnectionType

ConnectionTypes are essential to efficiently handling the pagination of data returned from GraphQL queries. We would highly suggest reading the GraphQL learning information on pagination.

When an object has a field that returns information about another object, the two objects share a ConnectionType that is unique to them. For example, the Product object contains an inventoryLog field, typed as ProductInventoryLogConnection, which can return data on one or more InventoryLog objects. Because each Product can have an unknown amount of inventory logs, a ConnectionType is used to act as a means of efficiently filtering, paging and sorting the data.

ConnectionTypes can also be returned by certain queries that expect to retrieve large amounts of data. An example of this would be the Products query, which returns a ConnectionType of the Product object. These function identically to the ConnectionTypes described above.

Each returned ConnectionType will always contain the following queryable fields:

Name	Type	Description
totalCount	Int!	The total number of items for the connection
edges	EdgeType[]!	A list of items on the connection
pageInfo	PageInfoType!	Information about the current page of the connection

Note: Querying the totalCount field can result in a slower response time

The edges field will contain an array of EdgeTypes, the information contained in each edge is determined by the object the connection is made to.

As an example, say we wanted to use the Products query to retrieve the name and inventoryLogs of each in-stock Product, but we only want the changed value of only the logs created after a certain date, we can write a query that looks something like:

{
    products(stocked: true) {
        edges {
            node {
                name,
                inventoryLog(start: "2023-12-01") {
                    edges {
                        node {
                            changed,
                        }
                    },
                    pageInfo {
                        hasNextPage,
                        endCursor,
                    }
                }
            }
        }
        pageInfo {
            hasNextPage,
            endCursor,
        }
    }
}

In contrast to the example provided in the GraphQL Getting Started guide, this particular query has a unique structure. The requested variables are enclosed within a node object, which itself is enclosed in an edges object. As a rule, when we anticipate the response to be of a ConnectionType, we must include these wrapping layers in our queries.

The response to the above query is formatted as:

{
    "data": {
        "products": {
            "edges": [{
                "node": {
                    "name": "Product A",
                    "inventoryLog": {
                        "edges": [{
                            "node": {
                                "changed": 5
                            }
                        }, {
                            "node": {
                                "changed": 20
                            }
                        }],
                        "pageInfo": {
                            "hasNextPage": false,
                            "endCursor": "[endCursor]"
                        }
                    }
                }
            }],
            "pageInfo": {
                "hasNextPage": true,
                "endCursor": "[endCursor]"
            }
        }
    }
}

Because the ProductInventoryLogConnection accepts multiple arguments, one being a start date, and because we only request the changed quantity of each log, the response time of the query is cut dramatically and as a result, the complexity of the request is as small as possible. All together, this allows for the most efficient method of retrieving the desired data.

All ConnectionTypes accept the following arguments:

Name	Type	Description
after	Cursor	An identifier that is used to specify the start point for the next set of results
first	Int	The amount of items you wish to retrieve
ordering	Ordering	Used to sort the retrieved data

Note: Some ConnectionTypes accept custom arguments which will be listed alongside the definition

For more information on pagination, see our Cursor documentation

EdgeType

An EdgeType contains information on an item returned by the connection. Each edge contains a node. A node contains the requested information on a single item. The type of the item changes with each connection, alongside the queryable fields of that item.

For example, the node field in the SaleRevisionConnection has the typing of the Revision object.

Name	Type	Description
node	[TypeOfConnectedObject]!	The object containing the queried fields of the connection