DiskANN¶

DiskANN은 그래프를 디스크에 저장하는 approximate nearest-neighbor (ANN) 인덱스입니다. AkasicDB Enterprise Edition에서만 제공하며 Community Edition에서는 지원하지 않습니다. vector 타입의 squared Euclidean distance (L2) 검색을 지원하며 DiskANN을 포함한 Linux 빌드가 필요합니다.

인덱스 구조¶

DiskANN index는 static index, primary index와 Consistency Overlay로 구성됩니다.

구성 요소	역할
Static index	`CREATE INDEX` 또는 `REINDEX` 시점의 visible row를 저장합니다. 검색할 때 graph를 disk에서 읽습니다.
Primary index	Static index를 만든 뒤 추가된 vector를 저장합니다. 기본값은 Vamana입니다.
Consistency Overlay	`VACUUM`으로 확인된 dead static entry를 검색 결과에서 제외합니다.

검색은 static index와 primary index에서 찾은 후보를 합친 뒤 PostgreSQL multiversion concurrency control (MVCC) visibility를 확인합니다. 커밋된 INSERT, UPDATE, DELETE는 REINDEX 없이 검색에 반영됩니다.

인덱스 생성¶

CREATE INDEX items_embedding_diskann_idx
  ON items
  USING vectoron (embedding vector_l2_ops)
  WITH (options = $$
    [indexing.diskann]
    max_degree = 32
    l_build = 100
    build_memory_mb = 4096
    search_pq_chunks = 3
    build_threads = 4
    cache_nodes = 0
    search_io_limit = 128
  $$);

SELECT fence_vector_index('items_embedding_diskann_idx'::regclass);

이 예제는 items.embedding이 vector(3)인 tutorial table이라고 가정합니다. search_pq_chunks는 vector dimension을 초과할 수 없으므로 3으로 지정합니다. 고차원 workload에서는 기본값 16을 사용할 수 있습니다.

Option	Default	설명
`indexing.diskann.max_degree`	`32`	Static graph node가 유지하는 edge 수의 상한입니다.
`indexing.diskann.l_build`	`100`	Static graph build의 후보 탐색 폭입니다. `max_degree` 이상이어야 합니다.
`indexing.diskann.build_memory_mb`	`4096`	Static index build에 사용하는 memory budget입니다.
`indexing.diskann.search_pq_chunks`	`16`	Static search에 사용하는 product quantization (PQ) chunk 수입니다. Vector dimensions를 초과할 수 없습니다.
`indexing.diskann.build_threads`	`4`	Static index build thread 수입니다.
`indexing.diskann.cache_nodes`	`0`	Process 내부에 유지할 static graph node 수입니다. `0`은 internal cache를 사용하지 않습니다.
`indexing.diskann.search_io_limit`	`128`	한 search에서 허용하는 storage I/O request 수의 상한입니다.

cache_nodes는 node 수이며 static index의 row 수를 초과할 수 없습니다. Dataset row 수에 대한 비율이 아닙니다.

Primary index 선택¶

Primary index는 Flat, HNSW 또는 Vamana를 사용할 수 있습니다. 기본값은 Vamana입니다.

CREATE INDEX items_embedding_diskann_hnsw_idx
  ON items
  USING vectoron (embedding vector_l2_ops)
  WITH (options = $$
    [indexing.diskann]

    [indexing.diskann.primary.hnsw]
    m = 12
    ef_construction = 300
  $$);

DiskANN primary index에는 quantization을 지정할 수 없습니다. search_pq_chunks는 static index에만 적용되며 primary index의 quantization option이 아닙니다.

검색 설정¶

GUC	Default	설명
`vectoron.diskann_result_size`	`100`	Static search가 요청하는 result count `K`입니다.
`vectoron.diskann_l_search`	`100`	Static graph search list size `L`입니다.
`vectoron.diskann_beam_width`	`16`	Storage I/O beam width입니다.
`vectoron.diskann_overlay_max_expansion`	`2`	Tombstone으로 제거된 후보를 보충하기 위해 static search를 다시 확장하는 최대 횟수입니다.

K, L과 beam width의 범위는 1–65,535입니다. K는 L을 초과할 수 없습니다. K는 query의 LIMIT 이상으로 설정합니다. vectoron.diskann_overlay_max_expansion의 범위는 0–2이며 0은 추가 확장을 실행하지 않습니다.

BEGIN;
SET LOCAL vectoron.diskann_result_size = 10;
SET LOCAL vectoron.diskann_l_search = 100;
SET LOCAL vectoron.diskann_beam_width = 16;

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

DML과 REINDEX¶

작업	동작
`INSERT`	새 vector를 primary index에 추가합니다.
`UPDATE`	새 row version을 primary index에 추가하고 이전 version은 MVCC visibility로 제외합니다.
`DELETE`	삭제한 row는 MVCC visibility로 제외됩니다.
`VACUUM`	Dead static entry를 tombstone으로 기록합니다.
`REINDEX INDEX`	Visible row로 새 static generation을 만들고 primary row와 tombstone을 통합합니다.

DiskANN 상태는 vectoron_index_stat에서 확인합니다.

SELECT
  indexname,
  idx_static_rows,
  idx_tombstones,
  idx_reindex_recommended
FROM vectoron_index_stat
WHERE indexname = 'items_embedding_diskann_idx';

idx_reindex_recommended는 다음 조건 중 하나를 만족하면 true입니다.

Primary row가 live indexed row의 75% 이상인 경우
Static tombstone이 static row의 50% 이상인 경우

Live indexed row는 primary row와 tombstone이 아닌 static row의 합입니다.

AkasicDB는 idx_reindex_recommended를 감시하거나 REINDEX를 자동으로 실행하지 않습니다. 사용자 UI 또는 monitoring system에서 vectoron_index_stat을 주기적으로 조회하고, idx_reindex_recommended가 true인 인덱스를 운영자에게 알려야 합니다.

SELECT
  indexname,
  idx_static_rows,
  idx_tombstones,
  idx_reindex_recommended
FROM vectoron_index_stat
WHERE idx_reindex_recommended IS TRUE;

권고를 확인한 운영자가 REINDEX INDEX를 실행합니다.

REINDEX INDEX items_embedding_diskann_idx;

REINDEX가 끝나면 해당 인덱스의 idx_reindex_recommended가 false인지 확인합니다.

제한¶

vector와 vector_l2_ops만 지원합니다.
Physical replication refresh, replay와 promotion은 지원하지 않습니다.