Installation & Setup

Get AnoFox Forecast running in minutes. Choose the installation method that works for you.

System Requirements

Requirement	Version	Notes
DuckDB	1.4.2 or later	Required
OS	Linux, macOS, Windows	Most platforms supported
Architecture	x86_64, ARM64	WASM also supported
Memory	2GB minimum	Depends on data size and model complexity

Installation Methods

Option 1: From DuckDB Community Registry (Recommended)

The easiest way to install AnoFox Forecast.

INSTALL anofox_forecast FROM community;
LOAD anofox_forecast;

Advantages:

• ✅ Automatic updates
• ✅ No build required
• ✅ Works on all platforms
• ✅ Recommended for most users

Next step: Verify your installation

---

Option 2: From GitHub (Bleeding Edge)

Build the latest development version from source.

Prerequisites

• C++ compiler: GCC 7+ or Clang 5+
• CMake: 3.21 or later
• Vcpkg: For dependency management
• Git: To clone the repository

Build Steps

# 1. Clone the repository with submodules
git clone --recurse-submodules \
  https://github.com/DataZooDE/anofox-forecast.git
cd anofox-forecast

# 2. Set up vcpkg (if not already installed)
export VCPKG_ROOT=~/vcpkg
git clone https://github.com/Microsoft/vcpkg.git $VCPKG_ROOT
$VCPKG_ROOT/./bootstrap-vcpkg.sh

# 3. Build the extension
make release

# 4. Build output location
# build/release/extension/anofox_forecast/anofox_forecast.duckdb_extension

Configure DuckDB to Use Your Build

# Set the custom extension directory
export CUSTOM_USER_AGENT="anofox-forecast"

Then in DuckDB:

SET custom_user_agent = 'your-app/1.0';
LOAD 'build/release/extension/anofox_forecast/anofox_forecast.duckdb_extension';

Advantages:

• ✅ Access to latest features
• ✅ Can modify source code
• ✅ Reproducible builds

Disadvantages:

• ❌ Requires build tools
• ❌ Slower installation
• ❌ Manual updates needed

---

Verify Installation

Quick Test

Run this SQL query to confirm the extension loaded:

-- Load extension
LOAD anofox_forecast;

-- Test with a simple forecast
SELECT
    forecast_step,
    point_forecast
FROM TS_FORECAST(
    'SELECT DATE \'2023-01-01\' + INTERVAL (d) DAY AS date,
            100 + SIN(CAST(d AS DOUBLE) / 10) * 20 + RANDOM() * 5 AS value
     FROM generate_series(0, 99) t(d)',
    'date',
    'value',
    'Naive',
    7,
    {}
)
LIMIT 5;

Expected output:

forecast_step | point_forecast
--------------+----------------
            1 | 110.45
            2 | 110.23
            3 | 109.87
            4 | 110.12
            5 | 109.95

Diagnostic Queries

Check extension details:

-- List loaded extensions
PRAGMA database_list;

-- Get extension version and build info
SELECT * FROM pragma_version();

-- List all TS_* functions (AnoFox functions)
SELECT function_name
FROM information_schema.functions
WHERE function_name LIKE 'TS_%'
ORDER BY function_name;

---

Troubleshooting

Issue: "Extension not found" or "Unknown function"

Cause: Extension not loaded

Solution:

-- Load the extension explicitly
LOAD anofox_forecast;

-- Verify it's loaded
PRAGMA database_list;

Issue: "Incompatible DuckDB version"

Cause: Using DuckDB < 1.4.2

Solution:

# Upgrade DuckDB
duckdb --version

# Update to latest
# Follow instructions at https://duckdb.org/docs/installation

Issue: "Cannot find extension" when building from source

Cause: Build directory not in DuckDB's extension search path

Solution:

-- Explicitly specify full path to extension
SET extension_directory = '/absolute/path/to/build/release/extension';
LOAD 'anofox_forecast';

Issue: "Segmentation fault" or crashes

Cause: Incompatible C++ standard or SIMD flags

Solution:

# Rebuild with compatibility flags
make clean
cmake -B build -S . \
  -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
  -DENABLE_AVX2=OFF
make -C build -j

Issue: Slow performance or memory errors

Cause: Not enough memory for large datasets

Solution:

-- Check available memory
PRAGMA memory_limit;

-- Increase memory limit
SET memory_limit='4GB';

---

Multi-Language Setup

Python

Use DuckDB's Python API with AnoFox Forecast:

import duckdb

conn = duckdb.connect(':memory:')
conn.execute("LOAD anofox_forecast")

result = conn.execute("""
    SELECT forecast_step, point_forecast
    FROM TS_FORECAST(
        'SELECT DATE \'2023-01-01\' + INTERVAL (d) DAY AS date,
                100 + RANDOM() * 10 AS value
         FROM generate_series(0, 99) t(d)',
        'date',
        'value',
        'Naive',
        7,
        {}
    )
""").fetchall()

print(result)

Install DuckDB:

pip install duckdb

R

Use DuckDB with R:

library(duckdb)

con <- duckdb::dbConnect(duckdb::duckdb())
DBI::dbExecute(con, "LOAD anofox_forecast")

result <- DBI::dbGetQuery(con, "
    SELECT forecast_step, point_forecast
    FROM TS_FORECAST(
        'SELECT DATE \"2023-01-01\" + INTERVAL (d) DAY AS date,
                100 + RANDOM() * 10 AS value
         FROM generate_series(0, 99) t(d)',
        'date',
        'value',
        'Naive',
        7,
        MAP{}
    )
")

print(result)

Install DuckDB:

install.packages("duckdb")

Julia

Use DuckDB with Julia:

using DBInterface, DuckDB

conn = DBInterface.connect(DuckDB.DB, ":memory:")
DBInterface.execute(conn, "LOAD anofox_forecast")

result = DBInterface.execute(conn, """
    SELECT forecast_step, point_forecast
    FROM TS_FORECAST(
        'SELECT DATE \"2023-01-01\" + INTERVAL (d) DAY AS date,
                100 + RANDOM() * 10 AS value
         FROM generate_series(0, 99) t(d)',
        'date',
        'value',
        'Naive',
        7,
        {}
    )
""") |> DBInterface.columntable

println(result)

Install DuckDB:

using Pkg
Pkg.add("DuckDB")

JavaScript/Node.js

Use DuckDB with JavaScript:

const duckdb = require('@duckdb/node-api');

const db = new duckdb.Database(':memory:');
const conn = db.connect();

conn.query("LOAD anofox_forecast");

const result = conn.query(`
    SELECT forecast_step, point_forecast
    FROM TS_FORECAST(
        'SELECT DATE \"2023-01-01\" + INTERVAL (d) DAY AS date,
                100 + RANDOM() * 10 AS value
         FROM generate_series(0, 99) t(d)',
        'date',
        'value',
        'Naive',
        7,
        {}
    )
`);

console.log(result);

Install DuckDB:

npm install @duckdb/node-api

---

Environment Variables

Configure AnoFox Forecast behavior:

-- Enable detailed logging
SET enable_debug_logging = true;

-- Set memory limits for large datasets
SET memory_limit = '8GB';

-- Control parallelization
SET threads = 8;

-- Set working directory
SET working_directory = '/tmp';

---

Persistent Configuration

To automatically load the extension each time you start DuckDB:

Create .duckdbrc File

Create a file ~/.duckdbrc (Unix/macOS) or %APPDATA%\.duckdbrc (Windows):

-- Auto-load AnoFox Forecast on startup
LOAD anofox_forecast;

-- Optional: Set default memory limit
SET memory_limit='4GB';

-- Optional: Enable logging
SET enable_debug_logging=false;

Verify Automatic Loading

# Start DuckDB
duckdb

# This command should work immediately (no explicit LOAD needed)
SELECT COUNT(*) FROM information_schema.functions WHERE function_name LIKE 'TS_%';

---

Build from Source: Detailed Guide

For advanced users who want to customize the build.

Step 1: Clone and Setup

git clone --recurse-submodules \
  https://github.com/DataZooDE/anofox-forecast.git
cd anofox-forecast

# Create build directory
mkdir -p build
cd build

Step 2: Configure with CMake

cmake -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
  -DBUILD_EXAMPLES=ON \
  -DBUILD_TESTING=ON \
  -DCMAKE_BUILD_TYPE=Release \
  ..

Step 3: Build

# Multi-core build
cmake --build . -j $(nproc)

# Or single-core if you run into issues
cmake --build .

Step 4: Test (Optional)

# Run unit tests
ctest --output-on-failure

# Run specific test
ctest -R "ARIMA" --output-on-failure

Step 5: Install for DuckDB

# DuckDB will auto-discover extensions in standard locations
# Or set custom path
export DUCKDB_CUSTOM_EXTENSION_DIRECTORY="$(pwd)/build/release/extension"

---

Performance Tips

For Large Datasets

-- Use parallel evaluation
SET threads = 8;  -- Adjust based on your CPU cores

-- Enable memory-efficient modes
SET work_mem = '256MB';

-- For very large time series, batch process:
-- Instead of forecasting all series at once,
-- process in chunks of 1000 series

For Production Use

-- Disable debug output (faster)
SET enable_debug_logging = false;

-- Pre-compile frequently used queries
PREPARE forecast_plan AS
SELECT * FROM TS_FORECAST(?, ?, ?, ?, ?, ?);

-- Use prepared statements
EXECUTE forecast_plan('sales', 'date', 'amount', 'AutoETS', 28, {});

---

Next Steps

1. 5-Minute Quickstart — Run your first forecast
2. Basic Workflow Guide — Complete end-to-end example
3. API Reference — Explore all available functions

---

Getting Help

• Installation issues: GitHub Issues
• Build problems: Check CONTRIBUTING.md
• Version compatibility: Check Releases