Configuration Reference

Properties

Known Caveats

Workspace-sensitive catalog path (DuckLake)

DuckLake stores DATA_PATH in catalog metadata. If you use a relative export-path (e.g., ./data/analytics), the Parquet file paths in the catalog are relative to the working directory where yaci-store was started.

When querying with DuckDB CLI or Python, you must start from the same working directory as the application. Otherwise, DuckLake will fail to locate the Parquet files.

Recommendation: Use absolute paths in production:

yaci.store.analytics.export-path=/var/lib/yaci-store/analytics

DuckDB memory usage in JVM

DuckDB defaults to using 80% of system physical RAM for its buffer manager. Since DuckDB runs inside the JVM process, this can cause memory contention — JVM heap + DuckDB buffer may together exceed available system RAM, leading to OOM kills (especially in containers/Kubernetes).

To limit DuckDB memory usage:

# Limit DuckDB buffer manager to 1GB per connection
yaci.store.analytics.duckdb.memory-limit=1GB

Note: With writer pool (1 connection) + reader pool (N connections), total potential DuckDB memory is memory_limit * (1 + N). Some DuckDB aggregate functions may also allocate memory outside the buffer manager, so actual usage can slightly exceed the configured limit.

DuckLake requires public schema in PostgreSQL

DuckLake stores its metadata tables in the public schema. The application automatically creates this schema if it doesn’t exist. If your PostgreSQL instance restricts schema creation, ensure public exists before enabling DuckLake.

Admin API

The admin API provides manual control over exports when enabled (yaci.store.analytics.admin.enabled=true).

Example: Export and query a specific date

# Trigger export for a specific date
curl -X POST http://localhost:8080/api/v1/analytics/admin/export/date/2024-01-15
 
# Query the exported data
duckdb -c "SELECT COUNT(*) FROM read_parquet('./data/analytics/transaction/date=2024-01-15/*.parquet');"