Configuration¶

AkasicDB를 안정적으로 운영하기 위한 주요 설정과 관리 방법을 정리합니다.

그래프 모듈 관련 GUC 파라미터¶

AkasicDB graph GUC parameter로 graph query planning을 조정합니다.

파라미터	설명	기본값
`enable_graphplan`	질의 플래너의 그래프 특화 연산자 사용 여부 (`true`/`false`)	`false`
`enable_fast_graph_planner`	그래프 질의의 planning 시간을 줄이는 fast graph planner 사용 여부 (`true`/`false`)	`false`
`fast_graph_planner_threshold`	fast graph planner 적용 기준이 되는 최소 relation 수	`18`

-- 예시: 세션 단위로 그래프 특화 연산자 사용 여부 조정
SET enable_graphplan = on;

AkasicDB에서 제공하는 그래프 특화 연산자의 효율성은 그래프 질의의 복잡도와 데이터의 규모, 그리고 데이터의 특성에 따라 달라질 수 있습니다.

Fast Graph Planner¶

간선이 많거나 속성 조건(property predicate)이 많은 경우 질의 플래닝 시간이 실행 시간보다 오래 걸릴 수 있습니다. 이러한 경우 fast graph planner 사용을 고려할 수 있습니다. 이 planner는 relation 수가 fast_graph_planner_threshold 이상인 질의에만 적용됩니다.

-- 세션 단위로 fast graph planner 활성화
SET enable_fast_graph_planner = on;

한 질의에만 적용하려면 transaction 안에서 SET LOCAL을 사용합니다.

벡터 모듈 관련 GUC 파라미터¶

AkasicDB vector GUC 파라미터는 query planning이나 query execution에 적용됩니다. 인덱스 생성 옵션은 CREATE INDEX ... WITH (options = ...)에서 지정하며, GUC로 바뀌지 않습니다.

파라미터 일람¶

파라미터	설명	기본값
`vectoron.enable_index`	질의 플래너의 벡터 인덱스 사용 여부 (`true`/`false`)	`true`
`vectoron.custom_wal_enabled`	Vector index custom WAL 기록 여부. 변경 후 서버 재시작 필요	`on`
`vectoron.diskann_beam_width`	DiskANN storage I/O beam width	`16`
`vectoron.diskann_l_search`	DiskANN static graph search list size `L`	`100`
`vectoron.diskann_overlay_max_expansion`	Tombstone 후보 보충을 위한 DiskANN static search 확장 횟수 상한	`2`
`vectoron.diskann_result_size`	DiskANN static search의 요청 결과 수 `K`	`100`
`vectoron.flat_quantized_simd`	Flat quantized distance 계산에서 SIMD 사용 여부	`off`
`vectoron.hnsw_ef_search`	HNSW 검색 중 후보 탐색 폭	`100`
`vectoron.hnsw_early_filtering`	HNSW bottom layer에서 현재 result bound 기반 조기 제외 사용 여부	`off`
`vectoron.hnsw_quantized_simd`	HNSW quantized distance 계산에서 SIMD 사용 여부	`on`
`vectoron.hnsw_refine`	Quantized HNSW 후보의 원본 distance 재계산 여부	`on`
`vectoron.ivf_nprobe`	IVF 검색 시 스캔할 cluster 수	`10`
`vectoron.ivf_quantized_simd`	IVF quantized distance 계산에서 SIMD 사용 여부	`off`
`vectoron.pgvector_compatibility`	pgvector 호환 모드 활성화 (`true`/`false`)	`false`
`vectoron.search_mode`	검색 모드 (`"vbase"` 또는 `"basic"`)	`"vbase"`
`vectoron.vamana_quantized_simd`	Vamana quantized distance 계산에서 SIMD 사용 여부	`on`
`vectoron.vamana_refine`	Quantized Vamana 후보의 원본 distance 재계산 여부	`on`
`vectoron.vamana_l_search`	Vamana 검색 중 후보 탐색 폭	`100`

-- 세션 단위 HNSW 검색 폭
SET vectoron.hnsw_ef_search = 100;

한 질의에만 적용하려면 transaction 안에서 SET LOCAL을 사용합니다.

BEGIN;
SET LOCAL vectoron.vamana_l_search = 200;

SELECT id
  FROM items
 ORDER BY embedding <-> '[0.1,0.2,0.3]'::vector
 LIMIT 10;
COMMIT;

Search-time Parameters¶

파라미터	적용 대상	비고
`vectoron.hnsw_ef_search`	HNSW query execution	HNSW 검색 중 후보 탐색 폭입니다. 값을 키우면 recall이 좋아질 수 있지만 latency와 CPU 비용도 늘 수 있습니다.
`vectoron.vamana_l_search`	Vamana query execution	Vamana 검색 중 후보 탐색 폭입니다. 값을 키우면 recall이 좋아질 수 있지만 latency와 CPU 비용도 늘 수 있습니다. build-time `indexing.vamana.l_search`와 다릅니다.
`vectoron.ivf_nprobe`	IVF query execution	query에서 scan할 IVF cluster 수입니다. 값을 키우면 recall이 좋아질 수 있지만 I/O와 latency가 늘 수 있습니다. build-time `indexing.ivf.nlist`와 다릅니다.
`vectoron.diskann_result_size`	DiskANN query execution	Static search의 요청 결과 수 `K`입니다.
`vectoron.diskann_l_search`	DiskANN query execution	Static graph search list size `L`입니다.
`vectoron.diskann_beam_width`	DiskANN query execution	Storage I/O beam width입니다.
`vectoron.diskann_overlay_max_expansion`	DiskANN query execution	Tombstone으로 제거된 후보를 보충하기 위해 static search를 다시 확장하는 횟수의 상한입니다.

Quantized search와 replication parameter의 세부 동작은 Quantization과 Vector Index Replication을 참조하십시오.

운영 환경에 적용하기 전 실제 filter 조건과 데이터 분포에 가까운 query set으로 recall과 latency를 확인하시기 바랍니다.

텍스트 검색 모듈 관련 GUC 파라미터¶

AkasicDB text search GUC 파라미터는 texton.* 접두사를 씁니다. 필드 매핑·analyzer 같은 인덱스 정의 요소는 CREATE INDEX ... WITH (mapping = ...)에서 지정하며 GUC로 바뀌지 않습니다.

적용 컨텍스트¶

파라미터마다 값을 바꿀 수 있는 시점과 권한이 다릅니다. 컨텍스트를 확인하지 않고 세션 SET을 시도하면 ERROR: parameter "..." cannot be changed now로 거부됩니다.

컨텍스트	바꾸는 방법
Postmaster	`postgresql.conf`에 적고 서버 재시작
SIGHUP	`postgresql.conf`에 적고 설정 리로드(`SELECT pg_reload_conf();`)
Suset	슈퍼유저가 세션 `SET`으로 변경 (또는 `postgresql.conf`)
Userset	일반 사용자도 세션 `SET`으로 변경

파라미터 일람¶

파라미터	기본값	컨텍스트	설명
`texton.bgworker_database`	`postgres`	Postmaster	배치 커밋 background worker가 연결할 데이터베이스입니다.
`texton.enable_cdc_ingestion`	`off`	SIGHUP	CDC(논리 디코딩) 수집을 활성화합니다. `wal_level=logical`이 전제입니다.
`texton.cdc_poll_interval_ms`	`200`	SIGHUP	CDC consumer의 폴링 주기(ms)입니다.
`texton.shipping_poll_interval`	`1000`	SIGHUP	replica puller worker의 워터마크 폴링 주기(ms)입니다.
`texton.dictionary_base_dir`	`''`	Suset	사용자 사전 경로 화이트리스트 디렉토리입니다. 비어 있으면 제한하지 않습니다.
`texton.search_num_threads`	`0`	Suset	검색 스캔의 세그먼트 분배 스레드 수입니다 (`0`=자동, `1`=단일).
`texton.build_num_threads`	`1`	Suset	대량 색인·배치 커밋·삭제 정리 writer의 스레드 수입니다.
`texton.writer_heap_bytes`	`50000000`	Suset	tantivy writer 힙 예산(바이트, 전체 스레드 합산)입니다.
`texton.build_merge`	`auto`	Suset	대량 빌드의 세그먼트 머지 전략입니다 (`auto` / `deferred`).
`texton.commit_batch_size`	`8192`	Suset	쓰기 배치 버퍼의 소프트 커밋 임계(항목 수)입니다.
`texton.recovery_max_rate`	`40`	Suset	복구·부트스트랩·재색인의 쓰기 처리량 상한(MB/s, `0`=무제한)입니다.
`texton.old_generation_retention`	`60`	Suset	스왑으로 물러난 옛 인덱스 세대의 GC grace(초, `0`=즉시)입니다.
`texton.shipping_max_rate`	`40`	Suset	세그먼트 전송 처리량 상한(MB/s, primary 송신면, `0`=무제한)입니다.
`texton.cdc_flush_timeout_ms`	`5000`	Userset	CDC 활성 시 `flush()` catch-up 대기 타임아웃(ms)입니다.
`texton.resolve_pk_to_ctid`	`off`	Userset	매칭 문서의 PK로 현재 ctid를 재해소합니다.
`texton.staleness_alert_seconds`	`60`	Userset	CDC 반영 지연 경보 임계(초)입니다.
`texton.free_space_alert_mb`	`512`	Userset	색인 파일시스템 여유 공간 경보 임계(MiB)입니다.

Userset 파라미터는 일반 사용자도 세션 단위로 바꿀 수 있습니다.

-- CDC 활성 시 flush catch-up 대기 상한을 이 세션에서만 늘림
SET texton.cdc_flush_timeout_ms = 10000;
SELECT akasicdb.text_flush('docs_texton_idx');

Suset 파라미터는 슈퍼유저만 세션에서 바꿀 수 있습니다.

-- 대량 적재 동안만 writer 스레드를 늘림 (슈퍼유저)
SET texton.build_num_threads = 4;

SIGHUP·Postmaster 파라미터는 세션 SET으로 바뀌지 않습니다. postgresql.conf에 적고 리로드하거나(SIGHUP) 서버를 재시작해야 합니다(Postmaster).

# postgresql.conf
wal_level = logical                 # Postmaster - 재시작 필요
texton.enable_cdc_ingestion = on    # SIGHUP - 리로드 필요

각 파라미터의 운영상 의미와 사용 맥락은 Text Search Operations에서 다룹니다.