llm-wiki/raw/official-docs/read-preference-mongodb-official.md

---
title: official-doc / MongoDB — Read Preference (Replica Set Read Routing)
source_type: official-doc
url: https://www.mongodb.com/docs/manual/core/read-preference/
archive_url:
related_branches: [feature-mongo-runtime-baseline-contract]
related_projects: []
tags: [official-doc, ca-skeleton, persistence, mongodb, read-preference]
created: 2026-07-28
---

# official-doc / MongoDB — Read Preference (Replica Set Read Routing)

> Layer: `raw/` — 외부 자료(공식 문서 / 대기업 기술 블로그)의 **원문 발췌·출처 기록**.
> 본 템플릿은 `raw/official-docs/` 와 `raw/company-tech-blogs/` 두 폴더가 공유.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.

## source_type 허용값

`source_type: official-doc` — MongoDB 공식 매뉴얼(레퍼런스) 문서.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-mongo-runtime-baseline-contract]] | 조회의 replica 라우팅을 read preference mode로 명시하고, secondary 읽기는 stale read를 허용하는 경로에만 쓴다는 결정 — mode 5종 정의 + secondary 읽기 stale 경고 + maxStalenessSeconds 메커니즘 + 트랜잭션 내 read preference 제약의 근거 |

## 출처

- 원본 URL: https://www.mongodb.com/docs/manual/core/read-preference/
- 아카이브 URL: (미제공)
- 저자 / 조직: MongoDB, Inc. (공식 매뉴얼)
- 발행일: (문서 자체에 명시 없음 — 버전별 롤링 업데이트되는 레퍼런스 페이지)
- 마지막 확인일: 2026-07-28

## 왜 저장했는지

`feature-mongo-runtime-baseline-contract` branch가 "조회 replica 라우팅을 read preference로 명시하고, secondary 읽기는 stale read를 허용하는 경로에만 쓴다"를 결정하는 데 필요한 5종 mode 정의, stale 경고, maxStalenessSeconds 메커니즘, 트랜잭션 제약의 공식 근거로 보관.

## 핵심 인용

> [§Behavior] "All read preference modes except `primary` may return stale data because secondaries replicate operations from the primary in an asynchronous process. Ensure that your application can tolerate stale data if you choose to use a non-`primary` mode."

> [§Read Preference and Transactions] "Transactions that contain read operations must use read preference `primary`. All operations in a given transaction must route to the same member."

> [§Read Preference Modes (Detailed) — primary] "All read operations use only the current replica set primary. This is the default read mode. If the primary is unavailable, read operations produce an error or throw an exception."

> [§Read Preference Modes (Detailed) — secondary] "Operations read _only_ from the secondary members of the set. If no secondaries are available, then this read operation produces an error or exception."

> [§Read Preference Modes (Detailed) — secondary] "When the `secondary` read preference includes a maxStalenessSeconds value, the client estimates how stale each secondary is by comparing the secondary's last write to that of the primary. The client then directs the read operation to a secondary whose estimated lag is less than or equal to `maxStalenessSeconds`. If there is no primary, the client uses the secondary with the most recent write for the comparison."

## Claims Extracted

> 이 자료가 **직접 말하는 것만** claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.

| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| MONGO-READPREF-C1 | `primary` 모드가 기본값이며 primary에서만 읽는다. primary 사용 불가 시 에러/예외가 발생한다 | [§primary] "All read operations use only the current replica set primary. This is the default read mode. If the primary is unavailable, read operations produce an error or throw an exception." | `official-vendor-doc` | MongoDB 드라이버 전반의 기본 read routing 동작 | ca-skeleton이 실제로 이 기본값을 재정의하지 않았는지는 코드 확인 필요 |
| MONGO-READPREF-C2 | `secondary` 모드는 secondary에서만 읽으며, 가용한 secondary가 없으면 에러/예외가 발생한다 | [§secondary] "Operations read _only_ from the secondary members of the set. If no secondaries are available, then this read operation produces an error or exception." | `official-vendor-doc` | secondary 전용 조회 경로를 선택했을 때의 실패 모드 근거 | 특정 배포에서 이 실패가 얼마나 자주 발생하는지는 증명 안 함 |
| MONGO-READPREF-C3 | `primary`를 제외한 모든 read preference 모드는 secondary의 비동기 복제 지연 때문에 stale data를 반환할 수 있다. 애플리케이션이 stale data를 감내할 수 있어야 한다 | [§Behavior] "All read preference modes except `primary` may return stale data because secondaries replicate operations from the primary in an asynchronous process. Ensure that your application can tolerate stale data if you choose to use a non-`primary` mode." | `official-vendor-doc` | secondary/secondaryPreferred/nearest/primaryPreferred 조회 경로 전체에 stale read 가능성이 있다는 근거 | 구체적인 replication lag 수치(ms/sec)는 배포 환경에 따라 다르며 이 문서는 수치를 제시하지 않음 |
| MONGO-READPREF-C4 | `secondary` 모드에서 `maxStalenessSeconds`가 지정되면, 클라이언트는 secondary의 마지막 write와 primary의 마지막 write를 비교해 추정 지연이 임계값 이하인 secondary로만 라우팅한다 | [§secondary] "When the `secondary` read preference includes a maxStalenessSeconds value, the client estimates how stale each secondary is by comparing the secondary's last write to that of the primary. The client then directs the read operation to a secondary whose estimated lag is less than or equal to `maxStalenessSeconds`. If there is no primary, the client uses the secondary with the most recent write for the comparison." | `official-vendor-doc` | maxStalenessSeconds를 지정했을 때 secondary 선택 알고리즘의 근거 | `maxStalenessSeconds`의 허용 최소값(예: 90초 같은 하한)은 이 페이지에 없음 — `needs-confirmation`, 별도 페이지(`docs/manual/core/read-preference-staleness/`) 확인 필요 |
| MONGO-READPREF-C5 | read operation을 포함한 트랜잭션은 반드시 read preference `primary`를 사용해야 하고, 한 트랜잭션 내 모든 연산은 같은 멤버로 라우팅되어야 한다 | [§Read Preference and Transactions] "Transactions that contain read operations must use read preference `primary`. All operations in a given transaction must route to the same member." | `official-vendor-doc` | multi-document transaction 안에서는 read preference를 primary 이외로 설정할 수 없다는 제약의 근거 | 트랜잭션 밖의 단일 연산에는 이 제약이 적용되지 않음(5개 모드 모두 사용 가능) — 이 문서가 그 대비를 명시하지는 않음, 유추 |
| MONGO-READPREF-C6 | `primaryPreferred` 모드는 대부분 primary에서 읽되, failover 등으로 primary가 없으면 `maxStalenessSeconds`와 tag set을 만족하는 secondary에서 읽는다 | [§primaryPreferred] "In most situations, operations read from the primary member of the set. However, if the primary is unavailable, as is the case during failover situations, operations read from secondary members that satisfy the read preference's `maxStalenessSeconds` and tag set lists." | `official-vendor-doc` | failover 시 fallback 라우팅 동작 근거 | 여러 조건을 만족하는 secondary가 다수일 때 정확히 어느 secondary가 선택되는지 세부 알고리즘은 별도 문서(member selection) 확인 필요 |
| MONGO-READPREF-C7 | `secondaryPreferred` 모드는 보통 secondary에서 읽되, 유일한 멤버가 primary뿐이면 primary에서 읽는다 | [§secondaryPreferred] "Operations typically read data from secondary members of the replica set. If the replica set has only one single primary member and no other members, operations read data from the primary member." | `official-vendor-doc` | secondary 우선 + primary fallback 라우팅 동작 근거 | 조건을 만족하는 secondary가 없을 때(단일 primary 이외의 경우)의 세부 fallback 조건은 별도 상세 문단 확인 필요 |
| MONGO-READPREF-C8 | `nearest` 모드는 네트워크 지연이 낮은 멤버에서 읽으며, primary/secondary 역할을 구분하지 않는다 | [§nearest] "The driver reads from a member whose network latency falls within the acceptable latency window. Reads in the `nearest` mode do not consider whether a member is a primary or secondary when routing read operations: primaries and secondaries are treated equivalently." | `official-vendor-doc` | 지연 최소화 목적의 조회 라우팅 근거 | latency window의 정확한 계산식(`localThresholdMS` 등)은 이 인용 범위 밖 — 별도 문단 확인 필요 |

### Strength 허용값

- `official-standard` — RFC, 표준 사양, 언어/프로토콜 표준
- `official-vendor-doc` — Spring, Keycloak, AWS, Google, MongoDB 등 공식 벤더 문서
- `official-reference` — 공식 reference/API 문서
- `company-case-study` — 대기업/실무 기술 블로그의 특정 사례
- `engineering-blog` — 개인/팀 블로그의 엔지니어링 해설
- `tutorial` — 튜토리얼/가이드. 일반화 금지
- `needs-confirmation` — 원문만으로는 적용 판단 불가

## Usage Boundaries

- 이 자료가 직접 증명하는 것:
  - `MONGO-READPREF-C1`~`C3`, `C6`~`C8`: read preference 5종 모드의 공식 정의와 각 모드의 기본 라우팅/실패 동작
  - `MONGO-READPREF-C3`: `primary`를 제외한 모든 모드가 stale data를 반환할 수 있다는 것 (branch의 "secondary 읽기는 stale read 허용 경로에만" 결정의 핵심 근거)
  - `MONGO-READPREF-C4`: `maxStalenessSeconds`가 어떻게 secondary 선택에 반영되는지의 메커니즘
  - `MONGO-READPREF-C5`: multi-document transaction 안에서 read preference가 `primary`로 고정되어야 한다는 제약
- 이 자료가 증명하지 않는 것:
  - `maxStalenessSeconds`의 허용 **최소값**(예: 90초 같은 수치 하한) — 이 URL에는 해당 수치가 없음. 링크된 하위 페이지(`docs/manual/core/read-preference-staleness/`)에 있을 가능성이 있으나 별도 dispatch로 확인 필요 (1 dispatch = 1 URL 원칙에 따라 본 자료에 포함하지 않음)
  - 특정 드라이버(Java, Node.js 등)의 실제 구현 세부사항 — 이 페이지는 드라이버 무관 개념 문서
  - sharded cluster 전용 동작(`SystemOverloadedError`, `terminateSecondaryReadsOnOrphanCleanup`)이 ca-skeleton의 배포 토폴로지(단일 replica set 가정 여부)에 적용되는지 여부
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-skeleton의 실제 MongoDB 배포가 replica set인지, sharded cluster인지 (전자에만 이 문서의 기본 가정이 그대로 적용됨)
  - `maxStalenessSeconds`의 최소값 제약 — 별도 raw 자료(`read-preference-staleness`) dispatch 필요

## 메모

- `MONGO-READPREF-C4`의 "의미"는 확보했으나, 사용자가 명시적으로 요구한 "최소값 제약"(90초 등 구체적 하한)은 이 URL의 fetch 결과에 존재하지 않았다. 자체 grep으로도 확인되지 않음 — fabrication 방지를 위해 claim에 포함하지 않고 gap으로 남김.
- 추가로 봐야 할 동일 출처 페이지: `https://www.mongodb.com/docs/manual/core/read-preference-staleness/` (maxStalenessSeconds 최소값 제약 확인용), `https://www.mongodb.com/docs/manual/core/read-preference-tags/` (tag set 상세)

## 관련

- 같은 주제 다른 official-doc: (write concern 관련 자료가 taxonomy changelog에 `raw/official-docs/write-concern-mongodb-official.md`로 예고되어 있으나 2026-07-28 기준 아직 생성되지 않음 — 생성되면 상호 링크)
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/...]]` (생성 시)