Entity API and connections API

This is the documentation of the GraphQL Library version 7. For the long-term support (LTS) version 5, refer to GraphQL Library version 5 LTS.

The entity and connections APIs are distinct APIs you can explore with the Apollo Server. Examples drawn from the auto-generated fields of the two APIs are used throughout the GraphQL Library documentation, but the differences and separations between them are implicit. This page aims to clarify these points, when to use which API, and how they can be combined in practice.

For more information on auto-generated fields and how the GraphQL Library generates them based on the type definition schema that you provide, see the Introduction and the Getting started pages.

Distinction

The entity API allows simple traversal, while the connections API provides access to relationship properties and more complex features such as aggregations, and it is relay-compatible. Knowing the difference allows you to make a more deliberate choice of when to use which API.

Consider the following type definitions:

type Movie @node {
    title: String!
    released: Int
    actors: [Person!]! @relationship(type: "ACTED_IN", direction: IN, properties: "ActedInProps")
}

type Person @node {
    name: String!
    movies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT, properties: "ActedInProps")
}

type ActedInProps @relationshipProperties {
    roles: [String!]!
}

The following sections outline the entity and connections APIs that are generated based on the definitions.

You can explore the different fields outlined on this page by putting the type definitions in a JavaScript file and firing up an Apollo server, as explained in the Self-hosting GraphQL guide.

Entity API

The entity API provides the following fields for the Movie and Person @node types:

movies(...): [Movie!]!

people(...): [Person!]!

Each entity can take four arguments:

  • where

  • limit

  • offset

  • sort

While the where and sort arguments can be used for filtering and sorting query results, limit and offset allow for offset-based pagination.

Also, note that:

  • The Movie and Person entities are connected via the ACTED_IN relationship.

  • The Movie types have an actors field that is a list of Person entities, while the Person entities have a movies field that is a list of Movie entities. This means you can access other entities directly from an entity that is connected to them.

  • Alongside the actors field (for Movie entities) and the movies field (for Person entities), you can access the actorsConnection and moviesConnection fields, respectively. These fields are provided by the connections API, not the entity API, and you can combine both APIs at certain levels in the same query.

A Movie entity also allows you to access the title and released fields, while a Person entity allows you to access its name field. For example:

query EntityApi {
  movies(limit: 10, offset: 5) {
    title
    released
    actors(limit: 2) {
      name
    }
  }
}

Connections API

The connections API follows a different approach. For each entity identified in the schema, it creates a connection field:

moviesConnection(...): MoviesConnection!

peopleConnection(...): PeopleConnection!

Each connection can take four arguments:

  • first

  • after

  • where

  • sort

While where and sort are used to filter and sort query results similarly to the entity API, first and after describe a pagination cursor that you can use in subsequent queries (see cursor-based pagination).

Connections fields can access the following:

  • aggregate

  • edges

  • pageInfo

  • totalCount

For examples on how to use the aggregate field, refer to queries-aggregations/aggregations.adoc#_querying_aggregations.

edges represent a set of relationship connections. They let you access the fields cursor, which is the pagination cursor, and node, which makes the corresponding field provided by the entity API accessible. This means that you can, at this level, combine the entity API with the connections API.

Nested connections

Nested connections also let you access the relationship properties via the field properties. This does not work with top-level connections.

For example:

query ConnectionApi {
  moviesConnection(first: 10) {
    edges {
      node {
        title
        actorsConnection {
          edges {
            node {
              name
            }
            properties {
              roles
            }
          }
        }
      }aggregation.a
      cursor
    }
    aggregate {
      node {
        title {
          longest
        }
      }
    }
  }
}

Note how actorsConnection is available under moviesConnection.edges.node, which is different from the top-level peopleConnection. It’s a nested connection, and it lets you access the relationship property roles.

pageInfo has the fields startCursor, endCursor, hasPreviousPage and hasNextPage which are used for pagination.

Finally, totalCount is the number of connection items.

Keep learning