Designing Queries
Once you've sent your first few signing requests, you'll want to use more of the API. The GraphiQL Explorer is a great place to experiment, but GraphQL can encourage an I-want-it-all attitude. A few moments of thought will save you from common problems:
- Is the data likely to become stale?
- Am I crippling my application performance with an unnecessarily long startup time?
If you're using something like TanStack Query, you'll understand the benefit of breaking queries into cacheable chunks that can be optimistically updated or invalidated. Here are guidelines we came up with through painful experience.
Avoid Deep Nesting on Lists
Avoid list queries with a tree depth greater than 2. On single-item queries, deeper nesting is fine.
Sometimes it's worth using aggregate fields on the parent to avoid triggering extra resolvers. For example, if the important thing about a Batch is how many documents it contains (which can be thousands), use the documentCount field rather than fetching the full documentConnection.
Isolate Data Types
Keep object types in separate queries unless the data is slow-changing and global (like Group retention settings). This doesn't seem important until you need to invalidate a cache or optimistically update a record — then you'll be glad each type has its own query key.
Test Query Changes
A quick alteration to a query can come with an unexpected performance penalty. We found several cases of previously speedy queries that evolved into slugs through generations of changes. Set a conceptual time limit for queries depending on your integration, and check performance when you modify them.
See Also
- What Is Overfetching? — why asking for less data matters
- How Pagination Works — fetching large result sets efficiently