Operations¶

이 페이지는 AkasicDB text search의 쓰기 가시성(배치 커밋), 재색인, CDC 수집, 복제, 관측용 SQL interface와 런타임 설정(GUC)을 다룹니다.

Background Worker 활성화¶

배치 커밋·CDC 소비자·재색인·shipping puller는 background worker와 공유 메모리를 사용하므로, postmaster 시작 시점에 preload 되어야 합니다. AkasicDB 배포본은 shared_preload_libraries에 texton을 기본 포함하므로 별도 설정 없이 사용할 수 있습니다.

shared_preload_libraries = 'akasicdb, graphon, vectoron, texton'

직접 빌드하거나 preload 목록을 조정하는 환경에서는 texton이 포함되어 있는지 확인한 뒤 서버를 재시작합니다.

Note

preload 없이도 USING texton 인덱스와 검색 함수는 동작하지만, 자동 배치 커밋 등 background worker 기능은 preload를 요구합니다.

배치 커밋 & 강제 커밋¶

INSERT는 tantivy write lock을 잡지 않고 배치 버퍼에 적재되며, background worker가 배치로 커밋합니다. 이 방식은 쓰기 락 경합을 줄이는 대신, 방금 넣은 행이 검색에 바로 보이지 않을 수 있습니다. 즉시 가시성(read-your-writes)이 필요하면 akasicdb.text_flush()로 미커밋 배치를 즉시 커밋합니다.

INSERT INTO docs (title, body) VALUES ('도쿄 여행', '국제공항에서 출발');
SELECT akasicdb.text_flush('docs_texton_idx');   -- 미커밋 배치를 즉시 커밋

DELETE된 행은 VACUUM 시점에 인덱스에서 정리됩니다.

CDC 수집 (옵션)¶

논리 디코딩 기반 CDC 수집을 켜면 커밋된 행 변경이 background 소비자를 통해 색인에 반영됩니다. wal_level = logical과 복제 슬롯이 필요합니다.

# postgresql.conf
wal_level = logical                 # postmaster 컨텍스트 - 서버 재시작 필요
texton.enable_cdc_ingestion = on    # SIGHUP 컨텍스트 - reload 필요

texton.enable_cdc_ingestion은 SIGHUP 컨텍스트 파라미터라 세션 SET으로는 켤 수 없습니다. 세션에서 바꾸려 하면 ERROR: parameter "texton.enable_cdc_ingestion" cannot be changed now 오류가 발생합니다. postgresql.conf에 지정한 뒤 설정을 reload 하십시오.

SELECT pg_reload_conf();

wal_level을 함께 바꿨다면 reload로는 적용되지 않으므로 서버를 재시작해야 합니다.

CDC가 켜진 인덱스는 akasicdb.text_flush() catch-up으로 read-your-writes를 보장합니다.

재색인¶

인덱스를 재구축할 때는 표준 REINDEX를 사용합니다.

REINDEX INDEX docs_texton_idx;

Note

엔진은 CDC가 켜진 인덱스에 대해 무중단 온라인 재색인(background 재빌드 후 원자적 generation 스왑)도 지원하지만, 아직 akasicdb 전문검색 interface로는 노출되지 않았습니다. 지금은 REINDEX INDEX를 사용하십시오.

복제 & 노드 역할¶

generation 기반 원자적 인덱스 스왑과 primary→replica 세그먼트 shipping을 지원합니다. replica의 puller worker가 primary의 watermark를 폴링해 세그먼트를 재구성합니다. 현재 노드 역할은 akasicdb.text_node_role()로 확인합니다(pg_monitor 구성원만 호출 가능).

SELECT akasicdb.text_node_role();   -- 'primary' 또는 'standby'

관측성¶

읽기 전용 Set-Returning Function (SRF) 4종으로 슬롯 랙·색인 상태·세그먼트 통계를 노출합니다. pg_monitor 롤 구성원만 호출할 수 있습니다.

SELECT * FROM akasicdb.text_slot_status();                -- 복제 슬롯 LSN / 랙
SELECT * FROM akasicdb.text_index_lag();                  -- 인덱스별 반영 커서 랙 · 부트스트랩 진행
SELECT * FROM akasicdb.text_index_stats();                -- 인덱스별 세그먼트 / 문서 수
SELECT * FROM akasicdb.text_segments('docs_texton_idx');  -- 세그먼트별 문서 수

Function	반환 내용
`akasicdb.text_slot_status()`	복제 슬롯 LSN과 랙
`akasicdb.text_index_lag()`	인덱스별 반영 커서 랙과 부트스트랩 진행
`akasicdb.text_index_stats()`	인덱스별 세그먼트·문서 수
`akasicdb.text_segments(regclass)`	세그먼트별 문서 수

설정 (GUC)¶

런타임 동작은 아래 GUC로 조정합니다. 값의 적용 범위는 파라미터마다 다릅니다(세션 SET, postgresql.conf reload 등). 파라미터별 컨텍스트 구분은 Configuration에 정리되어 있습니다.

GUC	기본값	설명
`texton.dictionary_base_dir`	`''`	사전 경로 화이트리스트 디렉토리입니다. 설정 시 이 디렉토리 하위 경로만 사용자 사전으로 허용됩니다.
`texton.search_num_threads`	`0`	검색 스캔의 세그먼트 스레드 수입니다(`0`=auto, `1`=단일).
`texton.resolve_pk_to_ctid`	`off`	다중 노드에서 매치 문서의 PK를 현재 ctid로 재해석합니다.
`texton.enable_cdc_ingestion`	`off`	CDC(논리 디코딩) 수집을 활성화합니다(`wal_level=logical` 필요).
`texton.cdc_poll_interval_ms`	`200`	CDC 소비자의 폴 주기(ms)입니다.
`texton.cdc_flush_timeout_ms`	`5000`	CDC 활성 시 `flush()` catch-up 대기 타임아웃(ms)입니다.
`texton.recovery_max_rate`	`40`	복구·부트스트랩·재색인의 쓰기 처리율 상한(MB/s)입니다(`0`=무제한).
`texton.old_generation_retention`	`60`	스왑아웃된 인덱스 generation의 GC 유예(s)입니다(`0`=즉시).
`texton.shipping_poll_interval`	`1000`	replica puller worker의 watermark 폴 주기(ms)입니다.
`texton.shipping_max_rate`	`40`	세그먼트 shipping 처리율 상한(MB/s, primary 송신)입니다(`0`=무제한).
`texton.bgworker_database`	`postgres`	배치 커밋 background worker가 접속하는 DB입니다.
`texton.build_num_threads`	`1`	대량 빌드·배치 커밋·삭제 정리 writer 스레드 수입니다.
`texton.writer_heap_bytes`	`50000000`	tantivy writer heap 예산(bytes, 전체 스레드 합)입니다.
`texton.build_merge`	`auto`	대량 빌드 merge 정책입니다(`auto` / `deferred`).
`texton.commit_batch_size`	`8192`	쓰기 배치 버퍼의 소프트 커밋 임계(항목 수)입니다.
`texton.staleness_alert_seconds`	`60`	CDC 반영 지연 경보 임계(s)입니다. 지연이 이 값을 초과하면 관측 표면이 지연 상태로 표시합니다.
`texton.free_space_alert_mb`	`512`	색인 파일시스템 여유 공간 경보 임계(MiB)입니다. 여유가 이 값 미만이면 관측 표면이 공간 부족으로 표시합니다.

동작 메모¶

색인 저장 위치: 각 인덱스의 tantivy 데이터는 $PGDATA/texton/<index_oid>/에 저장됩니다(WAL 대상 아님). 크래시 등으로 손상되면 REINDEX로 재구축합니다.
크래시 복구: 크래시 후 resume bootstrap으로 색인을 이어서 복구하며, 처리율은 texton.recovery_max_rate로 제한합니다.
한국어 사전: 기본 ko-dic main dictionary는 확장 바이너리에 임베드되어 별도 배치가 필요 없습니다. 사용자 사전만 외부 경로로 추가합니다(Tokenization).