55

In Relay GraphQL, connections and lists are both array-like, but they have different features. When should I use each?

Greg Hurrell
  • 5,177
  • 23
  • 27

1 Answers1

65

Connections

  • More powerful and flexible than simple lists.
  • Support pagination (forward and back), with cursors.
  • Fine-grained mutation support (eg. RANGE_ADD, RANGE_DELETE, NODE_DELETE, as described in the guide).
  • Requires a first or last argument in order to limit the size of the result set.
  • Has an edges field that provides a place to locate per-edge, edge-specific data.
  • A heavier-weight concept, requiring more work to define in the schema.

Lists

  • Simple and lightweight.
  • No support for pagination (the entire list is always returned).
  • No special mutations features for prepending, appending etc (although it is a requested feature).

Which to use?

  • Whenever you need pagination, you should use a connection.
  • If you need fine-grained control over mutations, you may choose to use a connection, even if you don't need pagination.
  • If you want all the items in a connection, you can use first with some large number.
  • If you want to expose a short list with minimal effort, use a simple list.
Greg Hurrell
  • 5,177
  • 23
  • 27
  • 1
    Is connection-related functionality in Relay on the client side entirely declarative? I'm seeing that by using connections you gain "fine-grained mutation support" in the client. Are there any imperative APIs that use this functionality? I'm not seeing any—just want to confirm I'm not missing anything. – Dmitry Minkovsky Nov 09 '15 at 02:22
  • 2
    Also, why do lists provide no support for pagination? I mean, you could build your own pagination using a list-type field, right? – Dmitry Minkovsky Nov 09 '15 at 02:23
  • 2
    @dimadima You can absolutely support pagination with lists. At graph.cool we support both a relay compatible and a simple graphql endpoint using lists for your data model. list queries support pagination through a skip and take mechanism. For example {allUsers(skip: 20, take: 10)} would return the third page. The issue with this approach that relay addresses is that if data is added between the page requests the pages will be shifted and you risk missing a node or returning duplicates. This is why the cursor is required. – sorenbs Apr 29 '16 at 10:12
  • 1
    Where can I see an example of defining and storing edge specific data? – Gershon Papi Jun 23 '16 at 05:54