Configuration¶

This section describes the key configuration and administration tasks required to operate AkasicDB reliably.

GUC Parameters for the Graph Module¶

Use AkasicDB graph GUC parameters to control graph query planning.

Parameter	Description	Default
`enable_graphplan`	Enables or disables graph-specific operators in the query planner (`true`/`false`)	`false`
`enable_fast_graph_planner`	Enables or disables the fast graph planner, which reduces planning time for graph queries (`true`/`false`)	`false`
`fast_graph_planner_threshold`	Minimum number of relations in a query for the fast graph planner to take effect	`18`

-- Example: enable or disable graph-specific operators at the session level
SET enable_graphplan = on;

The efficiency of AkasicDB’s graph-specific operators may vary depending on the complexity of the graph query, the size of the data, and the characteristics of the dataset.

Fast Graph Planner¶

When a graph query includes many edges or property predicates, planning may take longer than executing the query. In such cases, consider using the fast graph planner. The fast graph planner only takes effect for queries whose number of relations is greater than or equal to fast_graph_planner_threshold.

-- Enable the fast graph planner at the session level
SET enable_fast_graph_planner = on;

To apply it to a single query, use SET LOCAL inside a transaction.

GUC Parameters for the Vector Module¶

AkasicDB vector GUC parameters affect query planning or query execution. Index build options are set in CREATE INDEX ... WITH (options = ...) and are not changed by these GUCs.

Parameter List¶

Parameter	Description	Default
`vectoron.enable_index`	Enables or disables vector index usage in the query planner (`true`/`false`)	`true`
`vectoron.custom_wal_enabled`	Enables vector index custom WAL recording. Requires a server restart after changes	`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`	Maximum number of DiskANN static search expansions used to replace tombstone candidates	`2`
`vectoron.diskann_result_size`	Result count `K` requested by DiskANN static search	`100`
`vectoron.flat_quantized_simd`	Enables SIMD for Flat quantized distance calculation	`off`
`vectoron.hnsw_ef_search`	Candidate exploration width during HNSW search	`100`
`vectoron.hnsw_early_filtering`	Enables current-result-bound early rejection in the HNSW bottom layer	`off`
`vectoron.hnsw_quantized_simd`	Enables SIMD for HNSW quantized distance calculation	`on`
`vectoron.hnsw_refine`	Recalculates original distances for quantized HNSW candidates	`on`
`vectoron.ivf_nprobe`	Number of IVF clusters to scan during search	`10`
`vectoron.ivf_quantized_simd`	Enables SIMD for IVF quantized distance calculation	`off`
`vectoron.pgvector_compatibility`	Enables pgvector compatibility mode (`true`/`false`)	`false`
`vectoron.search_mode`	Search mode (`"vbase"` or `"basic"`)	`"vbase"`
`vectoron.vamana_quantized_simd`	Enables SIMD for Vamana quantized distance calculation	`on`
`vectoron.vamana_refine`	Recalculates original distances for quantized Vamana candidates	`on`
`vectoron.vamana_l_search`	Candidate exploration width during Vamana search	`100`

-- Session-wide HNSW search width
SET vectoron.hnsw_ef_search = 100;

For a single query, use SET LOCAL inside a transaction.

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¶

Parameter	Applies to	Notes
`vectoron.hnsw_ef_search`	HNSW query execution	Candidate exploration width for HNSW searches. Higher values may improve recall and may increase latency and CPU cost.
`vectoron.vamana_l_search`	Vamana query execution	Candidate exploration width for Vamana searches. Higher values may improve recall and may increase latency and CPU cost. This is separate from build-time `indexing.vamana.l_search`.
`vectoron.ivf_nprobe`	IVF query execution	Number of IVF clusters scanned for a query. Higher values may improve recall and may increase I/O and latency. This is separate from build-time `indexing.ivf.nlist`.
`vectoron.diskann_result_size`	DiskANN query execution	Result count `K` requested by static search.
`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	Maximum number of static search expansions used to replace candidates removed by tombstones.

For quantized search and replication parameters, see Quantization and Vector Index Replication.

Before applying a value broadly, check recall and latency with queries that match the target filters and data distribution.

GUC Parameters for the Text Search Module¶

AkasicDB text search GUC parameters use the texton.* prefix. Index definition elements such as field mappings and analyzers are set in CREATE INDEX ... WITH (mapping = ...) and are not changed by these GUCs.

Contexts¶

Each parameter differs in when and by whom its value can be changed. A session SET on a parameter whose context does not allow it is rejected with ERROR: parameter "..." cannot be changed now.

Context	How to change it
Postmaster	Set in `postgresql.conf` and restart the server
SIGHUP	Set in `postgresql.conf` and reload the configuration (`SELECT pg_reload_conf();`)
Suset	A superuser changes it with a session `SET` (or in `postgresql.conf`)
Userset	Any user can change it with a session `SET`

Parameter List¶

Parameter	Default	Context	Description
`texton.bgworker_database`	`postgres`	Postmaster	Database the batch-commit background worker connects to.
`texton.enable_cdc_ingestion`	`off`	SIGHUP	Enables CDC (logical decoding) ingestion. Requires `wal_level=logical`.
`texton.cdc_poll_interval_ms`	`200`	SIGHUP	CDC consumer poll interval (ms).
`texton.shipping_poll_interval`	`1000`	SIGHUP	Watermark poll interval of the replica puller worker (ms).
`texton.dictionary_base_dir`	`''`	Suset	Allowlist directory for user dictionary paths. Empty means no restriction.
`texton.search_num_threads`	`0`	Suset	Number of segment threads for a search scan (`0`=auto, `1`=single).
`texton.build_num_threads`	`1`	Suset	Number of writer threads for bulk build, batch commit, and delete cleanup.
`texton.writer_heap_bytes`	`50000000`	Suset	tantivy writer heap budget (bytes, across all threads).
`texton.build_merge`	`auto`	Suset	Bulk build merge policy (`auto` / `deferred`).
`texton.commit_batch_size`	`8192`	Suset	Soft commit threshold of the write batch buffer (item count).
`texton.recovery_max_rate`	`40`	Suset	Write throughput cap for recovery, bootstrap, and reindex (MB/s, `0`=unlimited).
`texton.old_generation_retention`	`60`	Suset	GC grace for swapped-out index generations (s, `0`=immediate).
`texton.shipping_max_rate`	`40`	Suset	Segment shipping throughput cap (MB/s, primary send side, `0`=unlimited).
`texton.cdc_flush_timeout_ms`	`5000`	Userset	Timeout for `flush()` catch-up when CDC is enabled (ms).
`texton.resolve_pk_to_ctid`	`off`	Userset	Re-resolves a matched document's PK to its current ctid.
`texton.staleness_alert_seconds`	`60`	Userset	Alert threshold for CDC apply lag (s).
`texton.free_space_alert_mb`	`512`	Userset	Alert threshold for free space on the index filesystem (MiB).

Userset parameters can be changed per session by any user.

-- Raise the flush catch-up timeout for this session only, when CDC is enabled
SET texton.cdc_flush_timeout_ms = 10000;
SELECT akasicdb.text_flush('docs_texton_idx');

Suset parameters can be changed in a session only by a superuser.

-- Raise writer threads for the duration of a bulk load (superuser)
SET texton.build_num_threads = 4;

SIGHUP and Postmaster parameters cannot be changed with a session SET. Set them in postgresql.conf and reload (SIGHUP) or restart the server (Postmaster).

# postgresql.conf
wal_level = logical                 # Postmaster - requires a restart
texton.enable_cdc_ingestion = on    # SIGHUP - requires a reload

What each parameter means operationally is covered in Text Search Operations.