> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ibex.ajna.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Ibex Analytics Service

> Python FastAPI service embedding DuckDB for federated SQL execution.

# Ibex Analytics Service

The `ibex-analytics-service` is the high-performance query engine that powers all analytics and reporting across the Ibex platform. It leverages an embedded **DuckDB** instance to perform federated queries across multiple heterogeneous data sources in a single SQL statement.

## Architectural Role

This Python/FastAPI service operates internally on port `8000` within the Docker `ajna` network. It is **not directly exposed to the internet**; all requests originate from either the `ibex-bi-backend` (for user-generated reports) or the `ibex-ai-service`/`ibex-agent-engine` (for AI-generated SQL execution).

## High-Level Working

### Federated Catalog Integration

Upon startup, the service automatically contacts the `ibex-data-platform` to fetch the registry of active data sources. It then dynamically attaches these sources as virtual DuckDB catalogs:

* **MySQL/PostgreSQL**: Attached natively via DuckDB scanner extensions.
* **Iceberg**: Connected via the Iceberg REST catalog, querying underlying Parquet files physically stored in MinIO.
* **S3 (Raw)**: Scans adhoc uploaded CSV and Parquet files.

### Cross-Source Queries

Because of the catalog architecture, users and AI agents can execute fully-qualified hybrid SQL queries:

```sql theme={null}
SELECT orders.total, users.email 
FROM mysql_business.orders AS orders 
JOIN postgres_metadata.public.users AS users 
ON orders.user_id = users.id
```

### Protection & Security

It relies entirely on network isolation and an internal API key (`ANALYTICS_SERVICE_API_KEY`) for protection, trusting the upstream `ibex-bi-backend` to handle user-level row security and authentication.