55

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

1 Answer 1

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.
4
  • 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. Commented Nov 9, 2015 at 2: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? Commented Nov 9, 2015 at 2: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
    Commented Apr 29, 2016 at 10:12
  • 1
    Where can I see an example of defining and storing edge specific data? Commented Jun 23, 2016 at 5:54

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.