12 KiB
title, source_type, url, archive_url, related_branches, related_projects, tags, created
| title | source_type | url | archive_url | related_branches | related_projects | tags | created | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| official-doc / Spring Data MongoDB — Index Creation (Automatic vs Programmatic) | official-doc | https://docs.spring.io/spring-data/mongodb/reference/mongodb/mapping/mapping-index-management.html |
|
|
|
2026-07-28 |
Spring Data MongoDB — Index Creation (Automatic vs Programmatic)
Layer:
raw/— 외부 자료(공식 문서)의 원문 발췌·출처 기록. Spring Data MongoDB Reference — Mapping › Index Creation
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-mongo-runtime-baseline-contract | "index 는 애플리케이션 automatic index creation 에 맡기지 않고 선언적 manifest + migration runner 로 관리하며 drift 를 감지한다" 결정의 근거 후보 — automatic index creation 기본값이 버전 3.0부터 OFF 라는 것과, 명시적(programmatic) index 생성이 "Recommended" 로 표기되어 있음을 공식 문서로 확인. 단 "manifest"/"migration runner"/"drift 감지" 라는 구체 메커니즘 자체는 이 문서가 규정하지 않음 (아래 Usage Boundaries 참조) — branch-note 작성 시 UNSUPPORTED_IMPL_DECISION 라벨 필요 여부 검토 대상 |
출처 / Source
- 원본 URL: https://docs.spring.io/spring-data/mongodb/reference/mongodb/mapping/mapping-index-management.html
- 아카이브 URL: (미확보)
- 저자 / 조직: Spring Data Team (Broadcom / VMware)
- 발행일: Spring Data MongoDB Reference (페이지 자체에 버전 배지 없음 — "since version 3.0" 문구로 최소 3.0 이상 대상 문서임만 확인됨)
- 마지막 확인일: 2026-07-28
왜 저장했는지 / Why archived
feature-mongo-runtime-baseline-contract branch 의 index 관리 결정("automatic index creation 에 맡기지 않고 선언적 manifest + migration runner + drift 감지")이 아직 외부 근거 없이 스캐폴딩된 상태였음. Spring Data MongoDB 공식 문서에서 (1) automatic index creation 기본값이 버전 3.0부터 OFF 라는 것, (2) 이를 켰을 때의 위험 고지("undesired effects on collection lifecycle and performance") 및 "Production consideration" 경고, (3) @Indexed/@CompoundIndex 선언 방식과 IndexResolver/IndexOperations 프로그래매틱 방식이 모두 존재한다는 것을 확인하기 위해 아카이브.
핵심 인용 / Key quotes (verbatim, 6개)
셀프그렙 검증 원본:
/tmp/claude-1000/-home-donghyeon-workspace-ai-tool-llm-wiki/1f67282d-364b-47cb-ba22-616233fae6ea/scratchpad/source-fetch-20260728-165953.txt(WebFetch 결과 저장, self-grep 통과)
[§Overview / Default Behavior, self-grep L8] "Automatic index creation is turned OFF by default as of version 3.0"
[§Overview, self-grep L5] "Spring Data MongoDB can automatically create indexes for entity types annotated with
@Document. However, index creation must be explicitly enabled since version 3.0 to prevent undesired effects on collection lifecycle and performance."
[§Programmatic Index Creation (Recommended), self-grep L29] "Spring Data recommends explicit index creation for application-based control. Use
IndexResolverwithIndexOperationson application startup, triggered byContextRefreshedEvent:"
[§Index Annotations / Compound Indexes (code), self-grep L90] "@CompoundIndex(name = "age_idx", def = "{'lastName': 1, 'age': -1}")"
[§Important Notes, self-grep L182] "Production consideration: Explicit index creation provides better control than automatic creation"
[§Important Notes, self-grep L183] "Index creation via
IndexOperationsoffers more control than annotations"
Claims Extracted / 추출된 주장
이 자료가 직접 말하는 것만 claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SD-MONGO-INDEX-C1 | Spring Data MongoDB 는 버전 3.0부터 automatic index creation 이 기본적으로 꺼져 있다(OFF by default) | [§Default Behavior, l.8] "Automatic index creation is turned OFF by default as of version 3.0" | official-vendor-doc |
Spring Data MongoDB 3.0 이상의 @Document 엔티티 |
3.0 이전 버전의 정확한 기본값(암묵적으로 ON 이었음을 시사하나 이 문서가 3.0 이전 동작을 직접 재확인하지는 않음), 그리고 우리 프로젝트가 실제 3.0+ 를 쓰는지 여부 |
| SD-MONGO-INDEX-C2 | automatic index creation 은 "collection lifecycle 과 performance 에 대한 원치 않는 영향(undesired effects)"을 막기 위해 명시적으로 활성화되어야 한다 | [§Overview, l.5] "However, index creation must be explicitly enabled since version 3.0 to prevent undesired effects on collection lifecycle and performance." | official-vendor-doc |
automatic index creation 활성화 여부를 결정할 때의 공식 위험 고지 | "프로덕션에서 금지" 또는 "권장하지 않음" 이라는 명시적 문구는 없음 — "undesired effects" 라는 일반적 경고만 있고, 구체적으로 무엇이 위험한지(예: 대용량 컬렉션에서 인덱스 빌드가 쓰기를 블록하는지 등)는 이 페이지에 설명되지 않음 |
| SD-MONGO-INDEX-C3 | "Programmatic Index Creation" 섹션은 "(Recommended)" 로 표기되어 있으며, 애플리케이션 기반 제어를 위한 명시적 index 생성을 권장한다. 구체적으로 IndexResolver 와 IndexOperations 를 ContextRefreshedEvent 시점에 사용하는 패턴을 제시한다 |
[§Programmatic Index Creation (Recommended), l.29] "Spring Data recommends explicit index creation for application-based control. Use IndexResolver with IndexOperations on application startup, triggered by ContextRefreshedEvent:" |
official-vendor-doc |
애플리케이션 시작 시점에 index 를 프로그래매틱하게 생성/보장하려는 설계 | "manifest 파일"이나 "migration runner"라는 개념·도구를 이 문서가 규정하지 않는다 — ContextRefreshedEvent 리스너에서 resolver.resolveIndexFor(...).forEach(indexOps::ensureIndex) 를 호출하는 것이 문서가 보여주는 유일한 패턴이며, 별도 migration 이력 관리나 drift 감지는 이 문서 범위 밖 |
| SD-MONGO-INDEX-C4 | Spring Data MongoDB 는 @Indexed, @CompoundIndex/@CompoundIndexes, @HashIndexed, @WildcardIndexed, @TextIndexed 같은 매핑 애노테이션을 통한 선언적 index 정의 방식을 제공한다 |
[§Index Annotations / Compound Indexes, l.90] @CompoundIndex(name = "age_idx", def = "{'lastName': 1, 'age': -1}") |
official-vendor-doc |
@Document 엔티티 클래스/필드에 선언하는 index 정의 |
애노테이션 방식이 deprecated 되었거나 사용을 피해야 한다는 것 — 오히려 IndexResolver 가 이 애노테이션들을 읽어 인덱스를 계산하는 상호보완 관계 (C5 참조) |
| SD-MONGO-INDEX-C5 | "Important Notes" 섹션은 explicit index creation 이 automatic creation 보다 더 나은 제어를 제공한다는 production 관련 권고와, IndexOperations(프로그래매틱)가 annotation(선언적) 보다 더 많은 제어력을 제공한다는 비교를 명시한다 |
[§Important Notes, l.182–183] "Production consideration: Explicit index creation provides better control than automatic creation" / "Index creation via IndexOperations offers more control than annotations" |
official-vendor-doc |
explicit(programmatic) index 생성 전략을 선택하는 결정의 공식 근거 | "annotation 기반 선언 방식을 쓰지 말라"는 것은 아님 — 프로그래매틱 방식이 "더 많은 제어력"을 준다는 상대적 비교일 뿐, annotation 방식이 프로덕션에 부적합하다고 말하지 않음 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
SD-MONGO-INDEX-C1: automatic index creation 기본값은 버전 3.0부터 OFF (auto-index-creation 에 맡기지 않는다는 결정의 "이미 기본이 꺼져 있다"는 전제 근거)SD-MONGO-INDEX-C2: 자동 생성을 켤 경우 collection lifecycle/performance 에 원치 않는 영향이 있을 수 있다는 공식 위험 고지SD-MONGO-INDEX-C3: 명시적/프로그래매틱 index 생성이 "Recommended" 섹션 표제로 제시됨 (IndexResolver+IndexOperations+ContextRefreshedEvent패턴)SD-MONGO-INDEX-C4:@Indexed/@CompoundIndex등 선언적 index 애노테이션의 존재와 문법SD-MONGO-INDEX-C5: explicit(programmatic) 방식이 automatic 방식 및 annotation-only 방식보다 "더 많은 제어력"을 제공한다는 공식 비교
- 이 자료가 증명하지 않는 것:
- "manifest" 라는 개념 — 이 문서는 index 정의를 코드(애노테이션) 또는
IndexResolver/IndexOperations호출로 표현하는 두 가지만 보여줄 뿐, 별도의 선언적 "manifest 파일"(YAML/JSON 등 외부 스펙 문서)이라는 아키텍처 패턴을 언급하거나 권장하지 않는다. manifest 도입은 branch 의 설계 결정이며 이 문서로 정당화되지 않는다 - "migration runner" — Flyway/Liquibase 류의 버전 관리형 migration 도구·이력 테이블 개념은 이 문서에 없다. 문서가 보여주는 것은
ContextRefreshedEvent시점에ensureIndex를 매번 재실행하는 idempotent-보장 패턴뿐이며, "migration" 이력 추적은 범위 밖 - "drift 감지" — 실제 컬렉션 인덱스와 코드/manifest 상 정의된 인덱스 간의 불일치를 탐지하는 메커니즘은 이 문서에 없다.
IndexOperations/IndexResolver는 인덱스를 "생성/보장(ensure)"하는 API 이지 "비교/보고(diff)"하는 API 라고 문서가 명시하지 않는다 - "자동 인덱스 생성이 프로덕션에서 금지된다" 또는 "권장되지 않는다"는 명시적 문구 — C2/C5 는 "위험 고지"와 "더 나은 제어"라는 상대적 표현만 있을 뿐, 절대적 금지 표현은 없다
- replica-set 트랜잭션이나 change stream 과 index 관리의 상호작용 — 이 페이지는 index 생성 메커니즘만 다루며, 이 branch 의 다른 범위(트랜잭션·change stream replica-set 요건)는 별도 근거 필요
- "manifest" 라는 개념 — 이 문서는 index 정의를 코드(애노테이션) 또는
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- "선언적 manifest" 를 실제로 어떤 형식(코드 상 애노테이션 집합을 manifest 로 간주할지, 별도 YAML 스펙을 만들지)으로 정의할지는 branch 의 별도 결정이며, 이 문서만으로는 근거가 부족함 —
UNSUPPORTED_IMPL_DECISION라벨 + trade-off 명시 필요 - "migration runner" 의 구체 구현(예: 자체
IndexOperations래퍼가 있는 컬렉션에 인덱스 적용 이력을 별도 컬렉션에 기록할지)도 이 문서 범위 밖이므로 별도 설계·근거 필요 - drift 감지를 위한 실제 비교 로직(
listIndexes()커맨드 등 MongoDB 드라이버 API 조사 필요)은 별도 raw 자료로 보강해야 함
- "선언적 manifest" 를 실제로 어떤 형식(코드 상 애노테이션 집합을 manifest 로 간주할지, 별도 YAML 스펙을 만들지)으로 정의할지는 branch 의 별도 결정이며, 이 문서만으로는 근거가 부족함 —
메모 / Notes
- 이 문서는 "automatic index creation 을 쓰지 말라"는 근거로는 충분하지만(C1+C2), branch 가 결정하려는 "manifest + migration runner + drift 감지"라는 구체 아키텍처는 이 문서의 범위를 넘어선다.
/branch-spec단계에서 D-row 를 작성할 때, 이 raw 자료는 "자동 생성 대신 명시적 생성" 부분만 뒷받침하고 나머지(manifest 형식·migration 이력·drift 비교)는UNSUPPORTED_IMPL_DECISION으로 라벨링하거나 별도 근거(MongoDB 드라이버listIndexes공식 문서, Flyway-Mongo 유사 도구 사례 등)를 추가 수집해야 한다. IndexResolver/IndexOperations조합이 애노테이션 메타데이터를 읽어 인덱스를 계산하는 구조이므로, "manifest" 를 이 애노테이션 집합 자체로 간주하는 설계도 가능해 보이지만 이는 내 해석이며 문서가 그렇게 명명하지는 않는다 (검증 안 된 추론 — wiki 단계에서 별도 확인 필요).- 추가로 봐야 할 동일 출처 페이지: Spring Data MongoDB Reference 의 read preference / read concern / write concern 페이지, replica-set 트랜잭션 요건 페이지, change stream resume token 페이지 (같은 branch 의 다른 결정 근거).
Related / 관련
- 같은 주제 다른 official-doc: (아직 없음 — MongoDB read/write concern, change streams 공식 문서는 이 branch 를 위해 별도 수집 필요)
- 이 자료를 인용한 wiki 요약: (생성 시 추가)