Skip to main content

​
Function signature

zvec.init(
    *,
    log_type: Optional[LogType] = LogType.CONSOLE,
    log_level: Optional[LogLevel] = 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

​
Logging configuration

​
log_type
LogType
default:"LogType.CONSOLE"
Logger destination.
  • LogType.CONSOLE (default if omitted or set to this)
  • LogType.FILE
If None, uses internal default (currently CONSOLE).
​
log_level
LogLevel
default:"LogLevel.WARN"
Minimum log severity. Accepted values: DEBUG, INFO, WARN, ERROR, FATAL.If None, uses internal default (WARN).
​
log_dir
string
default:"./logs"
Directory for log files (only used when log_type=FILE).Parent directories are not created automatically. If None, internal default is used.
​
log_basename
string
default:"zvec.log"
Base name for rotated log files (e.g., zvec.log.1, zvec.log.2).
​
log_file_size
number
default:"2048"
Max size per log file in MB before rotation. Default: 2048 MB (2 GB).
​
log_overdue_days
number
default:"7"
Days to retain rotated log files before deletion.

​
Thread configuration

​
query_threads
number
Number of threads for query execution.If None (default), inferred from available CPU cores (via cgroup). Must be ≥ 1 if provided.
​
optimize_threads
number
Threads for background tasks (e.g., compaction, indexing).If None, defaults to same as query_threads or CPU count.

​
Query optimization

​
invert_to_forward_scan_ratio
number
default:"0.9"
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).
​
brute_force_by_keys_ratio
number
default:"0.1"
Threshold to use brute-force key lookup over index.Lower → prefer index; higher → prefer brute-force. Range: [0.0, 1.0]. Default: 0.1.

​
Memory configuration

​
memory_limit_mb
number
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.

​
Return value

Returns None.

​
Exceptions

  • 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).

​
Examples

​
Initialize with defaults

Log to console and auto-detect resources: 
import zvec

zvec.init()

​
Customize logging to file

With rotation settings: 
import zvec
from zvec import LogType

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

​
Limit resources explicitly

Set memory and thread limits: 
import zvec

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

​
Fine-tune query heuristics

Customize query optimization thresholds: 
import zvec

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

​
Notes

  • 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.
  • In containerized environments, Zvec automatically detects cgroup limits for optimal resource utilization.

Build docs developers (and LLMs) love

Get started for freeTalk to us