Global Configuration

zvec.init

init(
    *,
    log_type: Optional[LogType] = CONSOLE,
    log_level: Optional[LogLevel] = WARN,
    log_dir: Optional[str] = "./logs",
    log_basename: Optional[str] = "zvec.log",
    log_file_size: Optional[int] = 2048,
    log_overdue_days: Optional[int] = 7,
    query_threads: Optional[int] = None,
    optimize_threads: Optional[int] = None,
    invert_to_forward_scan_ratio: Optional[float] = None,
    brute_force_by_keys_ratio: Optional[float] = None,
    memory_limit_mb: Optional[int] = None
) -> None

Initialize Zvec with configuration options.

This function must be called before any other operation. It can only be called once — subsequent calls raise a RuntimeError.

Parameters set to None are omitted from the configuration and fall back to Zvec's internal defaults, which may be derived from the runtime environment (e.g., cgroup CPU/memory limits). Explicitly provided values always override defaults.

Parameters:

Name	Type	Description	Default
log_type	Optional[LogType]	Logger destination. - LogType.CONSOLE (default if omitted or set to this) - LogType.FILE - If None, uses internal default (currently CONSOLE).	CONSOLE
log_level	Optional[LogLevel]	Minimum log severity. Default: LogLevel.WARN. Accepted values: DEBUG, INFO, WARN, ERROR, FATAL. If None, uses internal default (WARN).	WARN
log_dir	Optional[str]	Directory for log files (only used when log_type=FILE). Parent directories are not created automatically. Default: "./logs". If None, internal default is used.	'./logs'
log_basename	Optional[str]	Base name for rotated log files (e.g., zvec.log.1, zvec.log.2). Default: "zvec.log".	'zvec.log'
log_file_size	Optional[int]	Max size per log file in MB before rotation. Default: 2048 MB (2 GB).	2048
log_overdue_days	Optional[int]	Days to retain rotated log files before deletion. Default: 7 days.	7
query_threads	Optional[int]	Number of threads for query execution. If None (default), inferred from available CPU cores (via cgroup). Must be ≥ 1 if provided.	None
optimize_threads	Optional[int]	Threads for background tasks (e.g., compaction, indexing). If None, defaults to same as query_threads or CPU count.	None
invert_to_forward_scan_ratio	Optional[float]	Threshold to switch from inverted index to full forward scan. Range: [0.0, 1.0]. Higher → more aggressive index skipping. Default: 0.9 (if omitted).	None
brute_force_by_keys_ratio	Optional[float]	Threshold to use brute-force key lookup over index. Lower → prefer index; higher → prefer brute-force. Range: [0.0, 1.0]. Default: 0.1.	None
memory_limit_mb	Optional[int]	Soft memory cap in MB. Zvec may throttle or fail operations approaching this limit. If None, inferred from cgroup memory limit * 0.8 (e.g., in Docker). Must be > 0 if provided.	None

Raises:

Type	Description
RuntimeError	If Zvec is already initialized.
ValueError	On invalid values (e.g., negative thread count, log level out of range).
TypeError	If a value has incorrect type (e.g., string for query_threads).

Note

• All None arguments are excluded from the configuration payload, allowing the core library to apply environment-aware defaults.
• This design ensures container-friendliness: in Kubernetes/Docker, omitting memory_limit_mb and thread counts lets Zvec auto-adapt.

Examples:

Initialize with defaults (log to console, auto-detect resources):

>>> import zvec
>>> zvec.init()

Customize logging to file with rotation:

>>> zvec.init(
...     log_type=LogType.FILE,
...     log_dir="/var/log/zvec",
...     log_file_size=1024,
...     log_overdue_days=30
... )

Limit resources explicitly:

>>> zvec.init(
...     memory_limit_mb=2048,
...     query_threads=4,
...     optimize_threads=2
... )

Fine-tune query heuristics:

>>> zvec.init(
...     invert_to_forward_scan_ratio=0.95,
...     brute_force_by_keys_ratio=0.05
... )