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:

  1. Notes::BuildService#find_discussion (app/services/notes/build_service.rb) - this MR
  2. and 3. Note#ensure_confidentiality_discussion_compliance via start_of_discussion?, once in note.valid? and again in note.save - fixed behind a flag by !263097 (merged)
  3. Notes::CreateService#update_discussions via note.discussion - a separate follow-up MR (it also feeds the memoized discussion to TodoService#handle_note and when_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 to first_note or 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 EXISTS queries 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? is potentially_resolvable? && !system?, and the resolvable scope is documented as kept in sync with it: type IN (DiffNote, DiscussionNote), noteable_type IN Noteable.resolvable_types, system = false. Noteable#supports_resolvable_notes? is resolvable_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? is resolvable? && resolved_at.nil?, which is exactly the unresolved scope.

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, actor project.
  • Rollout issue: #634690
  • Off: unchanged behaviour (find_discussion plus Ruby resolved?).
  • 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, so find_discussion and 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 Note row is instantiated, and no EXISTS query runs when the first note is open; flag off: Note.find_discussion loads 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 of index_notes_on_discussion_id with 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 by TodoService#handle_note and when_saved (separate MR).
  • NewNoteWorker participants walk (https://gitlab.com/gitlab-org/gitlab/-/work_items/634351, separate MR).
  • Note#does_not_exceed_notes_limit? still runs a COUNT(*) over the noteable's notes on each validation. It is an index count, not a row load.
Edited by Marc Shaw

Merge request reports

Loading
Loading