들어가며

이런 코드를 짰다가 당황한 적이 있을 겁니다.

client.index(product)              // 201 Created
val result = client.search("무선")  // 0건 💥

색인은 분명 성공했는데 검색하면 없습니다. 잠시 뒤 다시 검색하면 나오고요.

OpenSearch가 Near Real-Time(NRT) 검색 엔진이기 때문입니다. Real-Time이 아니라 Near Real-Time이에요. 이번 글에서는 이 “Near”가 정확히 뭘 의미하는지, 왜 그럴 수밖에 없는지 알아봅니다.

원인은 이미 배웠다

사실 답은 4편에서 이미 나왔습니다.

세그먼트는 불변이다. 그래서 새 문서는 새 세그먼트를 만들어야 보인다.

문서를 색인하면 일단 메모리 buffer에 들어갑니다. 그런데 검색은 세그먼트만 뒤집니다. buffer는 쳐다보지도 않아요.

왜 buffer를 안 볼까요? buffer는 그냥 문서 덩어리일 뿐, 역색인이 만들어지지 않았기 때문입니다. 2편에서 봤듯 검색이 빠른 건 역색인 덕분인데, buffer에는 그게 없어요. 여기서 검색하려면 100만 건을 하나씩 다 열어봐야 합니다.

그래서 역색인을 만들어 세그먼트로 굳히는 순간까지 기다려야 하고, 그 작업이 바로 refresh입니다.

Near Real-Time = “refresh 주기만큼 늦다”

직접 겪어보기

시뮬레이터로 확인해봅시다. 이번엔 refresh에만 집중합니다.

실습 — 색인과 가시성의 시차

1. 문서 색인 을 누릅니다 → 빨간 경고가 뜹니다: “색인했는데도 아직 검색되지 않습니다”
2. 몇 번 더 눌러도 마찬가지입니다. buffer만 쌓여요
3. refresh 를 누릅니다 → 그 순간 전부 검색 결과에 나타납니다

실제 OpenSearch에서는 3번을 자동으로 1초마다 해줍니다. 그래서 “넣고 1초쯤 뒤엔 보인다”가 되는 거죠.

왜 하필 1초인가

여기서 좋은 질문이 나옵니다. 어차피 자동으로 할 거면 0.01초마다 하면 안 되나요? 그럼 사실상 실시간일 텐데요.

안 됩니다. refresh는 공짜가 아니기 때문입니다.

refresh를 한 번 할 때마다 세그먼트가 하나씩 생깁니다. 그리고 세그먼트가 많아지면 두 가지 비용이 발생해요.

1초는 “사람이 실시간이라고 느끼는 최소 단위”와 “시스템이 감당할 수 있는 부담” 사이의 절충점입니다. 물리 법칙이 아니라 실용적 기본값이에요. 그래서 바꿀 수 있습니다.

헷갈리는 3형제: refresh, flush, commit

이 세 단어가 뒤섞이면 문서를 읽어도 이해가 안 됩니다. 정리하고 갑시다.

한 줄로 외우면 이렇습니다.

refresh는 “보이게 하는” 것, flush는 “안전하게 하는” 것.

튜닝: refresh 주기 조절하기

기본값 1초가 모든 상황에 맞지는 않습니다.

대량 색인 — 아예 꺼버리기

수백만 건을 밀어넣는 배치 작업이라면, 색인 중에 검색될 필요가 없습니다. 그럼 refresh를 끄는 게 압도적으로 빠릅니다.

PUT /products/_settings
{ "index.refresh_interval": "-1" }

색인이 끝나면 되돌리고, 한 번 수동으로 refresh합니다.

PUT /products/_settings
{ "index.refresh_interval": "1s" }

POST /products/_refresh

로그성 데이터 — 길게 늘리기

로그나 통계처럼 “1초 안에 보일 필요가 없는” 데이터는 주기를 늘리면 색인 처리량이 올라갑니다.

PUT /logs-2026.07/_settings
{ "index.refresh_interval": "30s" }

색인 직후 바로 읽어야 할 때

테스트 코드나 “저장하고 목록 새로고침” 같은 흐름에서는 시차가 곤란합니다. 세 가지 선택지가 있습니다.

① refresh=wait_for — 권장

다음 refresh가 돌 때까지 응답을 보류합니다. 최대 1초 정도 기다리지만 추가 세그먼트를 만들지 않습니다.

POST /products/_doc?refresh=wait_for
{ "name": "무선 노트북 마우스" }

② refresh=true — 주의

즉시 refresh를 강제합니다. 빠르지만 호출할 때마다 세그먼트가 하나씩 생깁니다.

POST /products/_doc?refresh=true
{ "name": "무선 노트북 마우스" }

③ ID로 직접 조회 — 검색이 아니라면

문서 ID를 아는 경우엔 아예 다른 길이 있습니다.

GET /products/_doc/1234

_search가 아니라 _doc으로 ID를 지정해 가져오는 조회는 refresh를 기다리지 않습니다. 세그먼트에 없으면 translog를 뒤져서라도 최신 내용을 돌려주거든요.

ID 조회는 실시간, 검색은 준실시간.

“저장하고 그 문서를 다시 보여주기” 정도라면 이 방법이 가장 깔끔합니다.

실무에서 이걸 모르면 생기는 일

정리

1. NRT의 원인은 불변성이다. 검색은 세그먼트만 보는데, 새 문서가 세그먼트가 되려면 refresh가 필요하다.
2. refresh 주기가 곧 “Near”의 크기다. 기본 1초.
3. 1초는 절충점이다. 짧으면 세그먼트가 폭증하고, 길면 안 보인다.
4. refresh는 “보이게”, flush는 “안전하게” — 완전히 다른 일이다.
5. 대량 색인은 refresh를 끄고, 즉시 읽어야 하면 wait_for 또는 ID 조회를 쓴다.

다음 글에서는 지금까지 본 세그먼트가 replica에도 그대로 복제되는지 알아봅니다. 답은 “기본적으로는 아니다”인데, 그게 꽤 재미있는 결과를 낳습니다.

참고자료

• OpenSearch — Refresh API
• OpenSearch — Index settings (refresh_interval)
• OpenSearch — Get document API