In Relay GraphQL, connections and lists are both array-like, but they have different features. When should I use each?
1 Answer
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
orlast
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.
-
1Is 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
-
2Also, 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.– sorenbsCommented Apr 29, 2016 at 10:12
-
1Where can I see an example of defining and storing edge specific data? Commented Jun 23, 2016 at 5:54