# General / Connections

# Connections
 - [ConnectionType](#ConnectionType)
 - [EdgeType](#EdgeType)  

## 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](https://graphql.org/learn/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](/documentation/Objects/Products#Product) object contains an `inventoryLog` field, typed as
[ProductInventoryLogConnection](/documentation/Objects/Products#ProductInventoryLogConnection), which can return data on one or more [InventoryLog](/documentation/Objects/Inventory%20Log#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](/documentation/Queries/Products#products) query, which returns a `ConnectionType`
of the [Product](/documentation/Objects/Products#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[]!](#edge-type)                              | A list of items on the connection                    |
| pageInfo   | [PageInfoType!](/documentation/Objects/Utils#PageInfo) | 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](#EdgeType), 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:

```graphql
{
    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](/documentation/General/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:
```json
{
    "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](/documentation/Objects/Products#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](/documentation/Types/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/Types/Cursor#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](/documentation/Objects/Sales#SaleRevisionConnection)
has the typing of the [Revision](/documentation/Objects/Revision#Revision) object.

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