feat(api): implement graphql merge query pattern to reduce api call volume #2478

setchy · 2025-12-26T22:33:13Z

Implement GraphQL query aliasing and merging to reduce network calls and better utilize GitHub API rate limits


Sample Dataset
Before - `v6.14.1` release build
After - #2468 + this PR

For Issues, Pull Requests or Discussions, full enrichment now occurs in a single API query with a maximum query cost of 4 units

setchy · 2025-12-26T22:39:26Z

Current state of this PR is functional, but needs some further polish / refactoring, and update tests before being ready

- Add query merging infrastructure to batch multiple GraphQL queries into one - Create BatchMergedDetailsQueryFragment for combined notification queries - Update handlers (Discussion, Issue, PullRequest) with mergeQueryConfig - Add INDEX suffix variable naming for merged query support - Create getNotificationAuthor helper to handle snake_case/camelCase formats - Guard against null URLs in notification enrichment - Update test mocks to use nodeINDEX response format Co-authored-by: Adam Setch <adam.setch@outlook.com>

- Remove commented-out debug code from notifications.ts - Fix FIXME by using isAnsweredDiscussionFeatureSupported with account - Remove unused extras field from GraphQLMergedQueryConfig type - Add mergeQueryConfig tests for issue, pullRequest, discussion, and default handlers - Document why integration test is skipped (complex mocking requirements)

setchy · 2025-12-30T03:38:00Z

@afonsojramos - this isn't ready yet, it's still very much a draft

afonsojramos · 2025-12-30T03:41:52Z

Just wanted another pair of eyes! I'll keep working on this tomorrow 🙈

Not ready yet, I have changed I'd like to make to it still...

setchy · 2025-12-30T03:47:51Z

Just wanted another pair of eyes! I'll keep working on this tomorrow 🙈

What happened to my previous work on this branch, it seems you've rewrote the history and made other changes without discussion... I have local changes that I now need to untangle...

Signed-off-by: Adam Setch <adam.setch@outlook.com>

…clash in merged query Signed-off-by: Adam Setch <adam.setch@outlook.com>

Signed-off-by: Adam Setch <adam.setch@outlook.com>

…on draft PR Signed-off-by: Adam Setch <adam.setch@outlook.com>

Signed-off-by: Adam Setch <adam.setch@outlook.com>

setchy · 2026-01-01T05:06:32Z

After many, many, many iterations I'm now pretty happy with how the implementation has landed. It leverages the templated graphql-codegen types/documents and a builder pattern to construct the dynamic merged query.

Latest metrics below.


Sample Dataset (98 notifications)
`v6.14.1` REST API enrichment orchestration
`new` GraphQL Merged Enrichment for Discussions, Issues and Pull Requests

Still some unit test coverage to be added to the builder and client.

Signed-off-by: Adam Setch <adam.setch@outlook.com>

setchy · 2026-01-01T06:18:55Z

Sometime tomorrow I'll verify if this merge query approach actually is more efficient for the API Quotas / Rate Limits. If similar, this complexity may not warrant the effort to maintain...

afonsojramos

In addition to inline comments, currently, all supported notifications are batched into a single query. For large notification lists, this could create extremely large queries.
Shall we consider:

Setting a maximum batch size
Have a way to track the complexity of the query
If merged queries repeatedly fail, fall back to individual queries

Based on this, this PR seems to add a lot of complexity. Do we really wan't it? 😬

src/renderer/utils/notifications/handlers/issue.ts

src/renderer/utils/api/graphql/utils.test.ts

afonsojramos · 2026-01-01T14:10:59Z

src/renderer/utils/api/client.ts

+  builder.setNonIndexedVars({
+    includeIsAnswered: isAnsweredDiscussionFeatureSupported(
+      notifications[0].account,
+    ),
+    firstClosingIssues: Constants.GRAPHQL_ARGS.FIRST_CLOSING_ISSUES,
+    firstLabels: Constants.GRAPHQL_ARGS.FIRST_LABELS,
+    lastComments: Constants.GRAPHQL_ARGS.LAST_COMMENTS,
+    lastThreadedComments: Constants.GRAPHQL_ARGS.LAST_THREADED_COMMENTS,
+    lastReplies: Constants.GRAPHQL_ARGS.LAST_REPLIES,
+    lastReviews: Constants.GRAPHQL_ARGS.LAST_REVIEWS,
+  });


Isn't this assuming that notifications all belong to the same account?

That's correct

The flow of notifications.ts is currently:

notifications/getNotifications fetches the notification list per Gitify account

notifications/getAllNotifications iterates over each Gitify account and base filters, enriches and detail filters

src/renderer/utils/api/client.ts

src/renderer/utils/api/graphql/MergeQueryBuilder.ts

setchy · 2026-01-01T18:33:14Z

Sometime tomorrow I'll verify if this merge query approach actually is more efficient for the API Quotas / Rate Limits. If similar, this complexity may not warrant the effort to maintain...

Updated analysis on quota consumption below...

Note: REST and GraphQL API Quotas as independent

Configuration

Inbox size: 78 notifications
Detailed notifications: enabled
Measurement: delta between X-Ratelimit-Used response header per inbox refresh event

Build Tested	REST API Quota Consumed	GraphQL API Quota Consumed
`v6.14.1`	150	4
`main` branch	15	60
`merged query` pr	15	3

afonsojramos

Testing looks awesome! Just some function naming proposals, but looks good overall!

src/renderer/utils/api/graphql/MergeQueryBuilder.ts

src/renderer/utils/api/graphql/utils.ts

src/renderer/utils/api/client.ts

… batching vs query merging Signed-off-by: Adam Setch <adam.setch@outlook.com>

Signed-off-by: Adam Setch <adam.setch@outlook.com>

sonarqubecloud · 2026-01-02T02:52:44Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
91.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

setchy requested review from afonsojramos and bmulholland as code owners December 26, 2025 22:33

github-actions bot added the enhancement New feature or enhancement to existing functionality label Dec 26, 2025

setchy marked this pull request as draft December 26, 2025 22:39

setchy changed the title ~~feat(api): implement merge query pattern~~ feat(api/graphql): implement merge query pattern Dec 26, 2025

github-actions bot removed the enhancement New feature or enhancement to existing functionality label Dec 26, 2025

setchy changed the title ~~feat(api/graphql): implement merge query pattern~~ feat(api): implement graphql merge query pattern Dec 29, 2025

github-actions bot added the enhancement New feature or enhancement to existing functionality label Dec 29, 2025

setchy changed the title ~~feat(api): implement graphql merge query pattern~~ feat(api): implement graphql merge query pattern to reduce api call volume Dec 29, 2025

afonsojramos force-pushed the feat/query-merging branch 2 times, most recently from d09207b to 02866a2 Compare December 30, 2025 02:29

afonsojramos and others added 2 commits December 30, 2025 04:05

afonsojramos force-pushed the feat/query-merging branch from c85feb4 to 27e5321 Compare December 30, 2025 03:06

test: add coverage for graphql utils and enrichNotifications

f00cb42

afonsojramos marked this pull request as ready for review December 30, 2025 03:28

test: remove skipped integration test for detailed notifications

ba8bb0a

afonsojramos previously approved these changes Dec 30, 2025

View reviewed changes

setchy marked this pull request as draft December 30, 2025 04:02

setchy added 6 commits December 29, 2025 22:13

refactor: discussion gql types and common types. user-mocks reuse

9c4227a

Signed-off-by: Adam Setch <adam.setch@outlook.com>

refactor: rename arg to lastComments to lastThreadedComment to avoid …

3c30d3d

…clash in merged query Signed-off-by: Adam Setch <adam.setch@outlook.com>

refactor: codegen args withing INDEX suffix. simplify handler types

858b208

Signed-off-by: Adam Setch <adam.setch@outlook.com>

refactor: graphql utils for fragment parsing

1ad9f63

Signed-off-by: Adam Setch <adam.setch@outlook.com>

refactor: restore batch fetching

d510677

Signed-off-by: Adam Setch <adam.setch@outlook.com>

refactor: rename query as template. add todos for future refactoring …

ce5f7fe

…on draft PR Signed-off-by: Adam Setch <adam.setch@outlook.com>

refactor: move builder logic into client method

d7aadd6

Signed-off-by: Adam Setch <adam.setch@outlook.com>

setchy marked this pull request as ready for review January 1, 2026 03:42

setchy added 3 commits December 31, 2025 18:07

add test coverage

9ccc964

Signed-off-by: Adam Setch <adam.setch@outlook.com>

add test coverage

2d1a5c9

Signed-off-by: Adam Setch <adam.setch@outlook.com>

index template vars

a159567

Signed-off-by: Adam Setch <adam.setch@outlook.com>

setchy requested a review from afonsojramos January 1, 2026 05:06

address sonarcloud feedback

9a60c1c

Signed-off-by: Adam Setch <adam.setch@outlook.com>

afonsojramos requested changes Jan 1, 2026

View reviewed changes

Update utils.test.ts

2d061f3

afonsojramos approved these changes Jan 1, 2026

View reviewed changes

setchy added 13 commits January 1, 2026 10:47

refactor: rename to align with industry terminology for graphql query…

73f753f

… batching vs query merging Signed-off-by: Adam Setch <adam.setch@outlook.com>

refactor: rename to align with industry terminology for graphql query…

a9b2d3b

… batching vs query merging Signed-off-by: Adam Setch <adam.setch@outlook.com>

refactor: internalize index. rename builder options

e84a14d

Signed-off-by: Adam Setch <adam.setch@outlook.com>

refactor: internalize index. rename builder options

07c9eb9

Signed-off-by: Adam Setch <adam.setch@outlook.com>

refactor: simplify add node builder method

bf13af8

Signed-off-by: Adam Setch <adam.setch@outlook.com>

test: add unit test

0554507

Signed-off-by: Adam Setch <adam.setch@outlook.com>

test: add unit test

e7f356a

Signed-off-by: Adam Setch <adam.setch@outlook.com>

remove unused builder fn

35baa2e

Signed-off-by: Adam Setch <adam.setch@outlook.com>

handle no supported notifications

8c41624

Signed-off-by: Adam Setch <adam.setch@outlook.com>

Merge branch 'main' into feat/query-merging

fbbdf1b

lint

20acf3d

Signed-off-by: Adam Setch <adam.setch@outlook.com>

test: add coverage for client

6ae4640

Signed-off-by: Adam Setch <adam.setch@outlook.com>

test: add coverage for client

3f9462a

Signed-off-by: Adam Setch <adam.setch@outlook.com>

setchy merged commit 5917b3c into main Jan 2, 2026
14 checks passed

setchy deleted the feat/query-merging branch January 2, 2026 02:56

github-actions bot added this to the Release 6.15.0 milestone Jan 2, 2026

feat(api): implement graphql merge query pattern to reduce api call volume #2478

feat(api): implement graphql merge query pattern to reduce api call volume #2478

Uh oh!

Conversation

setchy commented Dec 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

setchy commented Dec 26, 2025

Uh oh!

setchy commented Dec 30, 2025

Uh oh!

afonsojramos commented Dec 30, 2025

Uh oh!

setchy commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

setchy commented Jan 1, 2026

Uh oh!

setchy commented Jan 1, 2026

Uh oh!

afonsojramos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

afonsojramos Jan 1, 2026

Choose a reason for hiding this comment

Uh oh!

setchy Jan 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

setchy commented Jan 1, 2026

Uh oh!

afonsojramos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Jan 2, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

setchy commented Dec 26, 2025 •

edited

Loading

setchy commented Dec 30, 2025 •

edited

Loading