Draft: Load only the first note when building a discussion reply
Replying to a discussion made Notes::BuildService load every note in the thread, only to read the first note and the thread's resolved state. On the 4,500-note thread from INC-15305, that made every reply O(N).
This loads only the first note. A reply to an open thread needs no further query; when the first note is resolved, two EXISTS queries check the rest of the thread. It is behind the reply_build_service_loads_first_note flag, which is off by default.
Related to https://gitlab.com/gitlab-org/gitlab/-/work_items/634293
Detailed context for AI agents
Background
INC-15305 (S2, 2026-10-16): a project bot replied about 9.7 times per second into one MR discussion (about 4,529 notes) via POST /projects/:id/merge_requests/:noteable_id/discussions/:discussion_id/notes. Each reply cost O(N) in the thread length, so the thread cost O(N^2), and the main primary's PgBouncer pool filled.
The reply path loaded the whole thread several times per request. A probe (request spec that subscribes to sql.active_record and logs every notes query without LIMIT, with backtraces) on current master, which already includes the API route fix, showed 4 whole-thread loads per reply:
Notes::BuildService#find_discussion(app/services/notes/build_service.rb) - this MR- and 3.
Note#ensure_confidentiality_discussion_complianceviastart_of_discussion?, once innote.valid?and again innote.save- fixed behind a flag by !263097 (merged) Notes::CreateService#update_discussionsvianote.discussion- a separate follow-up MR (it also feeds the memoized discussion toTodoService#handle_noteandwhen_saved, so those must change together)
With this MR the probe shows 3 loads (load 1 is gone).
The API route itself was fixed by !262926 (merged) (it used to render every note just to read the first).
What BuildService needs from the discussion
discussion.noteable,can_reply_to_system_note?,can_convert_to_discussion?,convert_to_discussion!,reply_attributes,confidential?: all derive from the first note (delegated tofirst_noteor built from it).resolved?: the only one that needs the rest of the thread (resolvable? && notes.none?(&:to_be_resolved?)).
So the flag-on path builds the discussion from the first note only (with_discussion_ids(id).order_created_at_id_asc.first&.to_discussion, same query shape as the API route fix) and computes the resolved state without loading the rest of the thread:
- If the first note is
to_be_resolved?, the thread cannot be resolved (ResolvableDiscussion#resolved?needs every resolvable note resolved), so the answer is false with no query. This is the common case: replies into open threads. - Otherwise two
EXISTSqueries check the rest of the thread in SQL.
Why the SQL resolved check is equivalent
ResolvableDiscussion#resolved? is potentially_resolvable? && notes.any?(&:resolvable?) && notes.none?(&:to_be_resolved?).
potentially_resolvable?is delegated to the first note, which we still have.Note#resolvable?ispotentially_resolvable? && !system?, and theresolvablescope is documented as kept in sync with it:type IN (DiffNote, DiscussionNote),noteable_type IN Noteable.resolvable_types,system = false.Noteable#supports_resolvable_notes?isresolvable_types.include?(base_class_name), and all notes in a thread share the noteable, so the per-note instance check and the scope agree.to_be_resolved?isresolvable? && resolved_at.nil?, which is exactly theunresolvedscope.
So resolved? becomes potentially_resolvable? && thread.resolvable.exists? && !thread.unresolved.exists?. Both are SELECT 1 ... LIMIT 1 on index_notes_on_discussion_id, with no rows loaded into Ruby.
The thread scope is the same as before: project.notes when there is a project, otherwise Note (group-level noteables).
Converted individual notes: when replying to an individual Note, convert_to_discussion! returns a one-note discussion, so the old code computed resolved? from that single unsaved DiscussionNote (always false, since individual notes are never resolved). The SQL check sees the row still typed Note, so resolvable.exists? is false and the result is also false.
Feature flag
reply_build_service_loads_first_note,gitlab_com_derisk,group::code review, milestone 19.6, actorproject.- Rollout issue: #634690
- Off: unchanged behaviour (
find_discussionplus Rubyresolved?). - With no project (group-level noteables) the actor is nil, so those switch over only when the flag is fully on.
loads_first_note?is memoized per service call, sofind_discussionand the resolved check always agree, even under a percentage-of-time rollout.
Tests
spec/services/notes/build_service_spec.rb, new context "when the discussion has several notes" (MR thread with a first note and a resolved reply), run with the flag on and off through a shared example:
- every note resolved: the reply is resolved
- only some notes resolved (first note open): the reply is not resolved
- first note resolved but a later reply not (possible through the per-note resolve API): the reply is not resolved. Only the SQL check gets this right; a first-note-only check would not.
- the only other note is a system note and the first note is resolved: the reply is resolved (system notes are not resolvable)
- flag on: exactly one
Noterow is instantiated, and noEXISTSquery runs when the first note is open; flag off:Note.find_discussionloads the thread
New context "when replying to an individual note on a merge request", flag on and off: the reply is a DiscussionNote and is not resolved. The note is converted in memory only, so its row still has no resolvable type.
Whole file: 42 examples, 0 failures.
Mutation checks: replacing the SQL check with true fails "first note resolved but a later reply not"; removing the early return fails "no EXISTS query when the first note is open".
Queries
Plans from a gitlab-production-main thin clone (postgres.ai, 2026-10-21), with the SQL exactly as Rails sends it and literal values. Each query ran twice and the warm run is quoted. "Typical" is a 5-note thread on a gitlab-org/gitlab merge request. "Incident" is the 4,529-note thread from INC-15305, on a private project, so its IDs are only in the linked plans.
-- first note
SELECT "notes".* FROM "notes" WHERE "notes"."project_id" = 278964 AND "notes"."discussion_id" = '555af213e9cd9235edc487541e4ff5c74c5400e1' ORDER BY "notes"."created_at" ASC, "notes"."id" ASC LIMIT 1
-- resolvable.exists? (only when the first note is resolved)
SELECT 1 AS one FROM "notes" WHERE "notes"."project_id" = 278964 AND "notes"."discussion_id" = '555af213e9cd9235edc487541e4ff5c74c5400e1' AND "notes"."type" IN ('DiffNote', 'DiscussionNote', 'Epic') AND "notes"."noteable_type" IN ('Issue', 'MergeRequest', 'DesignManagement::Design', 'WikiPage::Meta', 'Epic', 'ComplianceManagement::Projects::ComplianceViolation', 'Epic', 'ComplianceManagement::Projects::ComplianceViolation') AND "notes"."system" = FALSE LIMIT 1
-- unresolved.exists? (only when the first note is resolved): the same, plus
AND "notes"."resolved_at" IS NULL| Query | Typical | Incident |
|---|---|---|
| first note | 0.14 ms, 16 buffers | 20.3 ms, 4,175 buffers |
resolvable.exists? |
0.07 ms, 6 buffers | 3.2 ms, 76 buffers |
unresolved.exists? |
0.10 ms, 10 buffers | 15.1 ms, 4,220 buffers |
master's find_discussion, the whole-thread load this replaces |
0.14 ms, 16 buffers | 21.2 ms, 4,175 buffers |
- Typical thread: an Index Scan on
index_notes_on_discussion_id. Incident thread: a BitmapAnd ofindex_notes_on_discussion_idwith the project's notes index, then a top-N sort. - On the incident thread the first-note query reads the same 4,175 buffers as master's whole-thread load, because Postgres still visits every row of the thread to sort them. What changes is that Rails gets 1 row instead of 4,529.
- The incident thread is fully resolved, so its
unresolved.exists?plan is the worst case: no row matches and the whole thread is filtered (4,529 rows removed). - An index on
(discussion_id, created_at, id)would make the first-note query a single index probe. It is not part of this MR.
Out of scope
- The validation loads (!263097 (merged)).
- The post-save load in
Notes::CreateService#update_discussions, and its memoized reuse byTodoService#handle_noteandwhen_saved(separate MR). NewNoteWorkerparticipants walk (https://gitlab.com/gitlab-org/gitlab/-/work_items/634351, separate MR).Note#does_not_exceed_notes_limit?still runs aCOUNT(*)over the noteable's notes on each validation. It is an index count, not a row load.