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

# Federated Query Layer

> Core architecture for credential-delegated, zero-ingestion analytics

<Info>
  **Coming Soon** — This page describes an architecture that is currently in development and not yet generally available. [Contact us](mailto:hello@astrobee.ai) to learn more.
</Info>

AstroBee operates as a **semantic translation and orchestration layer** that sits between users and their data warehouses.

## How It Works

<Steps>
  <Step title="User authenticates">
    User authenticates with AstroBee and delegates credentials for their data warehouses (via OAuth).
  </Step>

  <Step title="User builds ontology">
    User defines business entities (Customer, Order, Product) mapped to warehouse tables.
  </Step>

  <Step title="User asks questions">
    User asks questions in natural language — "Show me top customers by revenue last quarter."
  </Step>

  <Step title="AI agent translates">
    AstroBee's AI agent translates the question into SQL targeting the customer's warehouse dialect.
  </Step>

  <Step title="Query executes">
    Query executes on the customer's warehouse using their delegated credentials.
  </Step>

  <Step title="Results stream back">
    Results stream back to AstroBee UI (limited to reasonable sizes, e.g., 10,000 rows).
  </Step>

  <Step title="Results displayed">
    Results are displayed in tables, charts, and dashboards.
  </Step>

  <Step title="No data persisted">
    Results are cached briefly (5–10 minutes) for pagination, then discarded.
  </Step>
</Steps>

## Credential Delegation Model

The security foundation is **per-user credential delegation** — each individual user's warehouse access tokens are stored encrypted and used exclusively for that user's queries.

### Key Security Properties

* **User credentials never shared** — Alice's Snowflake token is never used for Bob's queries (even in same organization)
* **Native access control enforced** — If Alice can't see `sensitive_customers` table in Snowflake, her AstroBee queries also can't access it
* **Token encryption at rest** — AES-256 encryption in database, decrypted only in-memory during query execution
* **Automatic token refresh** — Background jobs refresh OAuth tokens before expiry (no manual re-authentication)
* **Audit trail** — Every query logged with user identity for compliance reviews

## Virtual Semantic Layer

Unlike traditional AstroBee (which ingests CSV files), the zero-ingestion model uses **virtual entities** — business objects mapped to external warehouse tables without data copying.

### Ontology Definition

* **Entities** map to external tables (e.g., Customer → `snowflake://prod_analytics.ecommerce.customers`)
* **Properties** define columns, data types, business meanings (e.g., `revenue` is a measure, `customer_name` is a dimension)
* **Relationships** define joins across tables (e.g., `Customer.id` → `Order.customer_id`)
* **Virtual derived entities** can be defined via SQL queries (computed on-the-fly)

Users build this semantic layer once, then ask natural language questions that get translated to efficient SQL against the external warehouses.

## Example: Snowflake-Only Deployment

**Customer Context:** Company has all data in Snowflake (sales, marketing, product analytics). They want natural language analytics without moving data to AstroBee.

### Query Execution Flow

<Steps>
  <Step title="User asks question">
    "Show me top 10 customers by revenue last quarter"
  </Step>

  <Step title="Agent analyzes intent">
    Identifies Customer entity, revenue measure, time filter
  </Step>

  <Step title="Agent generates Snowflake SQL">
    ```sql theme={null}
    SELECT customer_name, SUM(order_total) as total_revenue
    FROM prod_analytics.ecommerce.customers c
    JOIN prod_analytics.ecommerce.orders o
      ON c.customer_id = o.customer_id
    WHERE o.order_date >= DATEADD(MONTH, -3, CURRENT_DATE())
    GROUP BY customer_name
    ORDER BY total_revenue DESC
    LIMIT 10
    ```
  </Step>

  <Step title="Query executor retrieves token">
    User's encrypted Snowflake OAuth token is retrieved and decrypted in-memory
  </Step>

  <Step title="Query executes on Snowflake">
    Snowflake RBAC verifies user has access
  </Step>

  <Step title="Results stream back">
    10 rows displayed in AstroBee UI with chart recommendation
  </Step>

  <Step title="Results cached briefly">
    Cached for 10 minutes for pagination/chart rendering, then discarded
  </Step>
</Steps>

## Permission Enforcement Example

**Scenario:** Alice is a marketing analyst, Bob is a finance analyst. Snowflake has role-based table permissions:

* `prod_analytics.ecommerce.customers` — accessible to MARKETING\_ROLE (Alice) and FINANCE\_ROLE (Bob)
* `prod_analytics.finance.salaries` — accessible only to FINANCE\_ROLE (Bob)

### Alice asks "Show customer demographics"

* AstroBee generates SQL querying customers table
* Snowflake RBAC check: Alice's role has SELECT on customers
* Query succeeds, results displayed

### Alice asks "Show average employee salaries"

* AstroBee generates SQL querying salaries table
* Snowflake RBAC check: Alice's role lacks SELECT on salaries
* Query fails with Snowflake error: Insufficient privileges to operate on table
* AstroBee displays: "You don't have access to the required data. Contact your Snowflake administrator."

<Tip>
  AstroBee never needs to know about Snowflake permissions — the warehouse enforces them automatically because queries run with the user's token.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Data Sources" icon="plug" href="/architecture/api-data-sources">
    Extend beyond warehouses to SaaS APIs
  </Card>

  <Card title="Security & Access Control" icon="shield" href="/architecture/security">
    Deep dive into the multi-layer security model
  </Card>
</CardGroup>