# API Data Sources
Source: https://docs.astrobee.ai/architecture/api-data-sources

Dynamic extraction from SaaS APIs with zero data ingestion

<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>

Phase 2 extends the zero-ingestion model beyond structured warehouse data to **semi-structured API sources**. Building on the credential delegation foundation from Phase 1, this phase applies the same security principles to SaaS applications like Gong, Google Calendar, and Zendesk — enabling natural language queries against data that doesn't exist in traditional tables.

## Beyond Tables: Dynamic API Extraction

Not all valuable business data lives in warehouses. Critical insights often reside in SaaS applications accessible only via APIs — sales call recordings in Gong, meeting schedules in Google Calendar, support tickets in Zendesk.

AstroBee can extract data from these sources **on-the-fly**, transform API responses into ephemeral tables, and include them in the semantic layer for unified analytics.

## How API Extraction Works

<Steps>
  <Step title="Schema Discovery">
    AstroBee's AI agent analyzes API documentation and sample responses to understand available data structures.
  </Step>

  <Step title="Extraction Logic Generation">
    For each user query, the agent generates appropriate API calls with filters, pagination, and field selection.
  </Step>

  <Step title="Response Transformation">
    JSON/XML responses are flattened into tabular format with inferred column types.
  </Step>

  <Step title="Semantic Mapping">
    Extracted tables are mapped to business entities (e.g., Gong calls → `SalesCall` entity with properties like `duration`, `sentiment_score`, `participants`).
  </Step>
</Steps>

## Example: Gong Integration

**Gong** provides conversation intelligence — recordings, transcripts, and AI analysis of sales calls. AstroBee can extract:

| Gong Data         | Semantic Entity | Use Cases                    |
| ----------------- | --------------- | ---------------------------- |
| Call recordings   | SalesCall       | Call volume, duration trends |
| Transcripts       | CallTranscript  | Keyword analysis, talk ratio |
| Sentiment scores  | CallSentiment   | Deal health indicators       |
| Deal intelligence | DealSignal      | Risk identification          |

### Sample Queries Enabled

* "Which reps have the highest talk-to-listen ratio?"
* "Show deals where competitor X was mentioned in calls"
* "Compare call sentiment trend vs. pipeline progression"

### Walkthrough: "Show calls where sentiment was negative"

<Steps>
  <Step title="Agent identifies data needs">
    Gong API: Call recordings with sentiment analysis
  </Step>

  <Step title="Extraction logic generated">
    ```
    GET /v2/calls?fromDateTime=2024-01-01&toDateTime=2024-03-31
    Fields extracted: call_id, duration, sentiment_score, participants, deal_id
    ```
  </Step>

  <Step title="Results transformed to table">
    | call\_id | duration | sentiment | deal\_id |
    | -------- | -------- | --------- | -------- |
    | c\_123   | 45min    | -0.3      | opp\_abc |
    | c\_456   | 30min    | -0.5      | opp\_def |
  </Step>

  <Step title="Final results displayed">
    Results displayed with call links and context
  </Step>
</Steps>

## Example: Google Calendar Integration

**Google Calendar** contains meeting data that reveals collaboration patterns and time allocation. AstroBee can extract:

| Calendar Data    | Semantic Entity    | Use Cases                |
| ---------------- | ------------------ | ------------------------ |
| Events           | Meeting            | Meeting load analysis    |
| Attendees        | MeetingParticipant | Collaboration patterns   |
| Response status  | MeetingResponse    | Engagement metrics       |
| Recurring events | MeetingSeries      | Time commitment analysis |

### Sample Queries Enabled

* "How many hours per week do sales reps spend in meetings?"
* "Which team members have the most external meetings?"
* "Show my meeting load trend over the past quarter"

## API Source Security Model

API sources follow the same credential delegation model as warehouses:

* **Per-user OAuth tokens** — Each user authenticates with Gong/Google using their own account
* **Native permissions enforced** — If a user can't access certain calls in Gong, AstroBee can't extract them
* **Scoped access** — OAuth scopes limit AstroBee to read-only data access
* **Token encryption** — API tokens stored with same AES-256 encryption as warehouse credentials
* **Audit trail** — All API extractions logged with user identity and data accessed

### Rate Limiting & Caching

* AstroBee respects API rate limits (e.g., Gong: 10 requests/second)
* Extracted data cached briefly (5–15 minutes) to avoid redundant API calls
* Cache invalidated on user request or data freshness requirements
* Large extractions paginated automatically to avoid timeouts

## Next Steps

<CardGroup>
  <Card title="Cross-System Federation" icon="git-merge" href="/architecture/cross-system-federation">
    Join API data with warehouse data across systems
  </Card>

  <Card title="Architecture Overview" icon="layers" href="/architecture/overview">
    Back to the high-level architecture overview
  </Card>
</CardGroup>


# Cross-System Federation
Source: https://docs.astrobee.ai/architecture/cross-system-federation

Ephemeral joins across warehouses, lakehouses, and SaaS APIs

<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>

Phase 3 represents the culmination of the architecture vision: **unified analytics across multiple data sources**. Building on credential delegation (Phase 1) and API extraction (Phase 2), this phase enables queries that span warehouses, lakehouses, and SaaS APIs — joining data that has never lived in the same system.

## The Power of Federation

The real value emerges when data from different systems can be joined. Consider questions like:

* "Show products with high sales (Snowflake) but low inventory (Databricks)"
* "For deals closing this quarter, correlate Gong call sentiment with win rate"
* "Which customers have the most touchpoints (Calendar meetings + Gong calls + Salesforce activities)?"

These insights are impossible with any single system — they require **federated queries**.

## Ephemeral Federation Architecture

Since Snowflake and Databricks can't directly query each other, AstroBee provides an **ephemeral workspace** — a temporary database that exists only for the duration of the query.

### Federated Query Execution Flow

<Steps>
  <Step title="User asks question">
    "Show products with high sales but low inventory"
  </Step>

  <Step title="Agent recognizes federation needed">
    Query spans two systems — Sales in Snowflake, Inventory in Databricks
  </Step>

  <Step title="Federation coordinator generates two SQL queries">
    **Snowflake:** Aggregate sales by product (last 30 days)

    **Databricks:** Current inventory levels by product
  </Step>

  <Step title="Queries execute in parallel">
    Each query uses the user's respective tokens
  </Step>

  <Step title="Partial results fetched into ephemeral workspace">
    Snowflake results: \~5,000 product-sales rows

    Databricks results: \~10,000 product-inventory rows
  </Step>

  <Step title="Join executes locally">
    ```sql theme={null}
    SELECT p.product_name, s.quantity_sold, i.current_stock
    FROM sales s
    JOIN inventory i ON s.product_id = i.product_id
    ```
  </Step>

  <Step title="Final results displayed">
    \~5,000 rows displayed in AstroBee UI
  </Step>

  <Step title="Workspace destroyed immediately">
    DuckDB instance terminated, no data persists
  </Step>
</Steps>

## Cross-Source Analytics: Warehouse + API Federation

Federation extends beyond warehouse-to-warehouse joins. Phase 3 enables joining **warehouse data with API-extracted data**.

**Example question:** "For deals closing this quarter, show the correlation between Gong call sentiment, number of meetings, and win rate"

This query draws from three sources simultaneously:

| Source                         | Data           | Fields                          |
| ------------------------------ | -------------- | ------------------------------- |
| **Gong** (API)                 | Call sentiment | `sentiment_score`               |
| **Google Calendar** (API)      | Meeting count  | `meeting_count`                 |
| **Salesforce** (Warehouse/API) | Opportunities  | `stage`, `amount`, `close_date` |

All three datasets are joined on `account_id` in the ephemeral workspace, producing a correlation analysis that no single system could provide:

* Salesforce knows deal stages but not conversation quality
* Gong knows call sentiment but not meeting frequency
* Calendar knows meeting load but not deal outcomes
* **Together**: Complete view of customer engagement → deal success correlation

## Federation Security Model

### Security Properties

* **Multi-credential validation** — Each source system independently verifies user permissions before returning data
* **No permission bypass** — If a user can't see `sensitive_products` in Databricks, the federated query also can't join it
* **Isolated workspaces** — Each user query gets a separate ephemeral database (no cross-contamination)
* **Automatic cleanup** — Workspace destroyed after 30–60 seconds (or on error), ensuring no data leakage
* **Audit logging** — All source queries and federation operations logged with user identity

## Performance Considerations

### Query Size Limits

* Practical limit: \~100,000 rows per source (prevents excessive data transfer)
* If a query exceeds the limit, AstroBee prompts: "Please add filters to reduce result size"
* Alternative: Push more computation to the source warehouse (aggregations before transfer)

### Network Latency

* Typical query time: 2–5 seconds (source execution + network transfer + local join)
* Parallel fetching reduces latency (Snowflake and Databricks queried simultaneously)
* For large joins: Consider materialized views in one warehouse (e.g., Databricks Delta Sharing or Snowflake data shares)

### Cost Management

* Warehouse query costs billed directly to the customer (not AstroBee)
* Customer maintains full visibility into query usage via Snowflake/Databricks billing dashboards
* AstroBee can surface cost estimates before query execution (using warehouse APIs)

## Data Source Support Matrix

| Source Type | Source          | OAuth Support    | Federation Support         | Notes                             |
| ----------- | --------------- | ---------------- | -------------------------- | --------------------------------- |
| Warehouse   | Snowflake       | Snowflake OAuth  | Via ephemeral workspace    | Key-pair auth also supported      |
| Lakehouse   | Databricks      | OAuth 2.0        | Via ephemeral workspace    | Unity Catalog integration         |
| CRM         | Salesforce      | Salesforce OAuth | Via ephemeral workspace    | Objects mapped to entities        |
| API         | Gong            | OAuth 2.0        | Via extraction + ephemeral | Call data, transcripts, sentiment |
| API         | Google Calendar | Google OAuth     | Via extraction + ephemeral | Events, attendees, scheduling     |

### Source Type Characteristics

* **Warehouse/Lakehouse** (Snowflake, Databricks): Direct SQL queries against existing tables
* **CRM** (Salesforce): SOQL queries against objects, mapped to semantic entities
* **API** (Gong, Calendar): Dynamic extraction with on-the-fly schema inference

## Next Steps

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

  <Card title="Architecture Overview" icon="layers" href="/architecture/overview">
    Back to the high-level architecture overview
  </Card>
</CardGroup>


# Federated Query Layer
Source: https://docs.astrobee.ai/architecture/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>
  <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>


# Federated Semantic Layer
Source: https://docs.astrobee.ai/architecture/overview

A credential-delegated, ephemeral-compute architecture for natural language analytics across distributed data systems

<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 is a **semantic orchestration layer**, not a data store. Users describe tasks in natural language; an AI agent translates them into queries executed **directly on the customer's own infrastructure**, using **the user's own credentials**. No customer data is ever ingested, copied, or permanently stored.

## How It Works

```
Task → AI Agent → Semantic Layer → Query Planning → Credential-Delegated Execution → Ephemeral Join (if needed) → Results → Cleanup
```

**Semantic Layer:** Admins define a virtual business model — entities, properties, relationships — mapped to external tables (Snowflake, Databricks, Salesforce) or API endpoints (Gong, Google Calendar). No data is moved; these are pointers.

**Credential Delegation:** Each user authenticates individually via OAuth to every connected source. Tokens are AES-256 encrypted at rest, decrypted only in-memory at query time, automatically refreshed, and never shared across users. AstroBee inherits each source's native access control (Snowflake RBAC, Databricks Unity Catalog, Salesforce profiles) without replicating it.

## Query Execution Paths

Query execution follows three paths depending on what the task touches:

| Path             | When             | What Happens                                                                                                               |
| ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **A — Direct**   | Single warehouse | Dialect-specific SQL executes on source compute; only the result set crosses the boundary.                                 |
| **B — Extract**  | Single API       | Call API with user's token, transform response into tabular format in an ephemeral workspace, query, destroy.              |
| **C — Federate** | Multiple sources | Push filtered queries to each source in parallel, load partial results into an ephemeral workspace, join locally, destroy. |

**Ephemeral Workspace:** For Paths B and C, an in-memory workspace is created per query, isolated per user, and destroyed after the query completes (seconds). Brief result caching supports pagination, then is discarded.

## Security Model

The architecture is **zero-trust by design** — AstroBee assumes no inherent rights to customer data.

* **No service accounts.** Every query runs as a specific user with their permissions. If a user can't access a table in Snowflake, they can't access it through AstroBee — the warehouse rejects the query.
* **No permission duplication.** No parallel ACL system to maintain or drift out of sync.
* **Blast radius is per-user.** A compromised token exposes only that user's scope.
* **Full audit trail.** Every query logged with user identity, source, SQL/API call, and timestamp.
* **Data residency preserved.** Customer data never leaves their cloud region.

**Compliance:** GDPR, HIPAA, and data residency requirements are satisfied structurally — not through policy — because AstroBee never holds the data.

## Federation

Tasks that span systems are unanswerable by any single source. *"Correlate Gong call sentiment with Salesforce win rates for deals closing this quarter"* — Salesforce knows deal stages, Gong knows conversation quality, neither can answer alone.

AstroBee extracts filtered subsets into an ephemeral workspace, joins on shared keys, computes the answer, and discards everything. Each source independently validates credentials — no permission bypass through federation.

*AstroBee acts as a translator and coordinator — never as a database. Customer data stays where it is, governed by the systems that already protect it.*

## The Vision: A Unified Data Layer

The ultimate goal is to create a **semantic data layer that spans multiple systems** — warehouses, lakehouses, CRMs, and SaaS APIs — enabling organizations to ask questions across their entire data ecosystem without moving or duplicating data.

This vision is achieved through a phased approach:

| Phase       | Capability                       | Value                                                                    |
| ----------- | -------------------------------- | ------------------------------------------------------------------------ |
| **Phase 1** | Single structured data source    | Foundation: Prove the credential delegation model with warehouse queries |
| **Phase 2** | API data sources                 | Expansion: Extend to semi-structured data from SaaS applications         |
| **Phase 3** | Federated queries across systems | Vision: Unified analytics across all data sources                        |

Each phase builds on the previous, progressively expanding the types of data sources and query complexity supported while maintaining the core principles of zero data ingestion and native permission enforcement.

## Deep Dives

<CardGroup>
  <Card title="Federated Query Layer" icon="database" href="/architecture/federated-query-layer">
    Core architecture, credential delegation, and the virtual semantic layer
  </Card>

  <Card title="API Data Sources" icon="plug" href="/architecture/api-data-sources">
    Dynamic extraction from Gong, Google Calendar, and other SaaS APIs
  </Card>

  <Card title="Cross-System Federation" icon="git-merge" href="/architecture/cross-system-federation">
    Ephemeral joins across warehouses, lakehouses, and APIs
  </Card>

  <Card title="Security & Access Control" icon="shield" href="/architecture/security">
    Multi-layer security model, zero-trust design, and compliance
  </Card>
</CardGroup>


# Security & Access Control
Source: https://docs.astrobee.ai/architecture/security

Multi-layer security model, zero-trust design, and compliance for the federated architecture

<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>

The federated semantic layer is built on a **multi-layer security model** that ensures customer data is never exposed beyond the user's existing permissions — without AstroBee needing to replicate or manage those permissions.

## Multi-Layer Security

### Layer 1: AstroBee Application Security

| Capability                     | Description               |
| ------------------------------ | ------------------------- |
| **User Authentication**        | Email/Password + MFA      |
| **Organization Multi-Tenancy** | Isolates org data         |
| **Role-Based Access Control**  | Admin/Editor/Viewer roles |

### Layer 2: Credential Management

| Capability                       | Description               |
| -------------------------------- | ------------------------- |
| **Encrypted Credential Storage** | AES-256 at rest           |
| **Per-User Token Scoping**       | Never shared across users |
| **Automatic Token Refresh**      | OAuth refresh flow        |

### Layer 3: Native Platform Security

Each connected data source enforces its own access control:

| Platform       | Security Model                         |
| -------------- | -------------------------------------- |
| **Snowflake**  | RBAC with role hierarchies             |
| **Databricks** | Unity Catalog with fine-grained access |
| **Salesforce** | Profiles with object/field permissions |

### Layer 4: Audit & Compliance

| Capability             | Description          |
| ---------------------- | -------------------- |
| **Query Logging**      | User, SQL, timestamp |
| **Access Audit Trail** | Who accessed what    |
| **Compliance Reports** | GDPR/HIPAA exports   |

## Zero-Trust Principle

AstroBee operates on a **zero-trust model** — it assumes it has no inherent rights to customer data and must prove authorization for every query.

### Comparison with Traditional Data Integration

| Aspect                     | Traditional (Service Account)                     | Zero-Ingestion (User Tokens)                              |
| -------------------------- | ------------------------------------------------- | --------------------------------------------------------- |
| **Credentials**            | Single service account with broad access          | Individual user OAuth tokens                              |
| **Permission Model**       | Replicate warehouse permissions in AstroBee       | Use warehouse permissions directly                        |
| **Access Escalation Risk** | High — service account is single point of failure | Low — compromising one user token exposes only their data |
| **Audit Granularity**      | All queries appear as service account             | Every query attributed to specific user                   |
| **Compliance**             | Must maintain parallel access control system      | Inherits compliance from warehouse (SOC2, ISO)            |

## Credential Lifecycle Management

Credentials go through a well-defined lifecycle:

<Steps>
  <Step title="Initial Connection">
    User redirects to data source OAuth, grants scopes (read data, list tables/objects), receives access + refresh tokens.
  </Step>

  <Step title="Active Usage">
    Tokens used for queries (validity varies by provider).
  </Step>

  <Step title="Background Refresh">
    Before expiry, AstroBee uses the refresh token to get a new access token (transparent to user).
  </Step>

  <Step title="Expiry/Revocation">
    If refresh fails, the connection is marked as expired and the user is prompted to re-authenticate.
  </Step>

  <Step title="Deletion">
    User can disconnect a data source anytime — tokens are securely deleted.
  </Step>
</Steps>

## Compliance & Data Residency

### Key Compliance Benefits

* **Data Residency** — Customer data never leaves their cloud region. If Snowflake is in EU, data stays in EU.
* **GDPR Compliance** — No data processing agreement needed (AstroBee doesn't process personal data, just query results)
* **HIPAA Compliance** — PHI remains in customer's BAA-covered warehouse. AstroBee only sees aggregated results.
* **SOC2 Inheritance** — Leverage data platform provider's SOC2 certification (Snowflake, Databricks, Salesforce audited annually)
* **Right to Deletion** — Deleting data in source system immediately reflects in AstroBee queries (no stale copies)

### Audit Capabilities

* **Query logs** — "Show all queries Bob ran against `sensitive_customers` table"
* **Access reports** — "Which users accessed finance data in last 30 days?"
* **Compliance dashboards** — Track failed permission attempts, unusual query patterns

## Deployment: Customer Onboarding Flow

<Steps>
  <Step title="Admin setup">
    Organization admin connects data sources, defines ontology (business model).
  </Step>

  <Step title="User onboarding">
    Each team member authenticates individually with data sources (their own credentials).
  </Step>

  <Step title="Permission inheritance">
    Users automatically inherit their source system permissions in AstroBee.
  </Step>

  <Step title="Usage">
    Users ask questions, get insights respecting their access levels.
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Federated Query Layer" icon="database" href="/architecture/federated-query-layer">
    Core architecture and credential delegation model
  </Card>

  <Card title="Architecture Overview" icon="layers" href="/architecture/overview">
    Back to the high-level architecture overview
  </Card>
</CardGroup>


# Changelog
Source: https://docs.astrobee.ai/changelog

Product updates and new features

<Update label="February 2026">
  **New Features**

  * Added **Klaviyo**, **Meta Ads**, and **Google Ads** connectors via Fivetran
  * **Team member invitations** with magic link authentication
  * **Live data source status** — data sources now update in real-time as syncs progress
  * Added **PostHog** product analytics integration
  * New generic **API integration system** with OAuth support

  **Improvements**

  * DuckDB warehouse now uses S3 storage with Fivetran integration
  * Simplified Fivetran S3 access configuration
  * Avatar display updated to show user initials instead of random images
  * Added favicon with AstroBee logo
  * Admin-only settings pages now enforce proper authorization

  **Fixes**

  * Fivetran destination constraint relaxed for shared warehouse setups
  * Organization members can now view API data source tokens
  * Dropdown menus close correctly when clicking outside
  * Settings page loads organization data for rename functionality
</Update>

<Update label="January 2026">
  **New Features**

  * **Answer reports** — see the full question, SQL query, logic explanation, and data preview in one view
  * **MCP server** with OAuth 2.0 authentication for connecting to Claude Desktop and VS Code
  * **LinkedIn Ads** and **Reddit Ads** connectors via Fivetran
  * **Inline editing** for data layer entities and properties
  * **Data preview** directly in analytics chat responses
  * **Human-in-the-loop interactions** during data layer generation
  * **Chat title auto-generation** from your first message
  * **Guided onboarding tour** for new users
  * Demo dataset bundles for exploring AstroBee without your own data

  **Improvements**

  * Redesigned landing page with video demo and trust indicators
  * Sidebar and typography refinements
  * Show affected relationships when deleting entities
  * Expandable table list in data source cards
  * Inline resource management in model editor header

  **Fixes**

  * Restored question widget on page refresh
  * Fixed namespace collision when uploading multiple CSV files
  * Normalized preview icons across the app
  * Mailto links now work in streaming content
</Update>

<Update label="December 2025">
  **New Features**

  * **Data layer graph visualization** — see your data model as an interactive graph
  * **Linkage discovery** — automatically find relationships between data sources with LLM-powered analysis
  * **Model renaming** with thematic auto-generated names
  * **CSV delimiter auto-detection** — upload CSVs with any common delimiter
  * **Magic link authentication** — passwordless sign-in with email
  * **Version history** with review and publish workflow for data layer changes
  * **Column pattern analysis** — automatic profiling of data columns after upload
  * Rich semantic card view for reviewing scratchpad changes (replaces JSON diff)

  **Improvements**

  * URL-based navigation for model editor tabs
  * Dynamic state indicators on the generate model button
  * Unified batch progress tracking for pipeline operations
  * Node visibility toggle in graph view
  * Organization account plans with feature gating
  * Settings page split into dedicated sections (organization, warehouse, integrations, profile)

  **Fixes**

  * Fixed entity count display on dashboard
  * Corrected total row count in data source cards
  * Analysis fields now appear immediately after upload
  * Empty state messages improved across the app
</Update>

<Update label="November 2025">
  **New Features**

  * **Svelte UI migration** — complete frontend rewrite using LiveSvelte for a faster, more responsive experience
  * **Batch CSV file upload** with parallel processing
  * **Model creation and editing UI** with empty model guidance flow
  * **Connection pool management** with lifecycle hooks and health monitoring
  * **Data source schema discovery** — automatic table and column detection from your warehouse
  * Model editor chat for conversational data modeling
  * Entity suggestion system with AI-powered recommendations
  * Data source linking modal for connecting sources to models

  **Improvements**

  * Standardized navigation sidebar across all pages
  * Breadcrumbs and consistent AstroBee branding
  * Linked data sources widget on model version page
  * Version status indicators in analytics chat
  * Async test execution for faster development cycles

  **Fixes**

  * Resolved race conditions in CSV upload and agent chat
  * Fixed scratchpad discard validation errors
  * Warehouse connection validation now shows user-friendly error messages
  * Fixed duplicate data source creation on upload
  * Corrected entity display using proper key formats
</Update>


# File Uploads
Source: https://docs.astrobee.ai/data/files

Upload CSV and Excel files to AstroBee

Upload spreadsheets directly to AstroBee for quick data exploration without configuring external connections.

## Supported Formats

| Format | Extensions  | Max Size |
| ------ | ----------- | -------- |
| CSV    | .csv        | 300 MB   |
| Excel  | .xlsx, .xls | 300 MB   |

## Uploading Files

1. Navigate to **Data Sources** in the sidebar
2. Click **Add New**
3. Drag and drop files into the upload zone, or click to browse

<Frame>
  <img alt="Upload files" />
</Frame>

### Multiple Files

Upload multiple files at once to create a data source with multiple tables. Each file becomes a separate table.

### Excel Workbooks

For Excel files with multiple sheets, each sheet becomes a separate table within the data source.

## After Upload

Once uploaded, AstroBee:

1. **Parses the file** — Reads rows and columns
2. **Detects types** — Identifies strings, numbers, dates, etc.
3. **Analyzes patterns** — Discovers ID formats, email patterns, etc.
4. **Finds linkages** — Identifies potential relationships between tables

## Data Type Detection

AstroBee automatically detects column types:

| Detected Type | Examples                          |
| ------------- | --------------------------------- |
| String        | "John Smith", "Active", "SKU-123" |
| Integer       | 42, 100, -5                       |
| Float         | 19.99, 3.14159                    |
| Date          | 2024-01-15, 01/15/2024            |
| Datetime      | 2024-01-15 14:30:00               |
| Boolean       | true, false, yes, no              |

<Tip>
  If types are detected incorrectly, ensure your source data is consistently formatted. For example, don't mix "N/A" text in a numeric column.
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion title="Use headers">
    Include column headers in the first row. AstroBee uses these as field names.
  </Accordion>

  <Accordion title="Consistent formatting">
    Keep data types consistent within columns. Don't mix numbers and text.
  </Accordion>

  <Accordion title="Meaningful names">
    Use descriptive column names like "customer\_id" instead of "id1".
  </Accordion>

  <Accordion title="Clean data">
    Remove empty rows and columns before uploading.
  </Accordion>

  <Accordion title="UTF-8 encoding">
    Save CSV files with UTF-8 encoding for special characters.
  </Accordion>
</AccordionGroup>

## Updating Data

File uploads are one-time imports. To update the data:

1. Prepare your updated file
2. Upload it with the same name
3. The existing data is replaced

<Note>
  For data that changes frequently, consider using an external connector with automatic sync instead.
</Note>

## Limitations

* Maximum file size: 300 MB
* Maximum rows: No hard limit, but very large files may take longer to process
* Password-protected Excel files are not supported

## Next Steps

<CardGroup>
  <Card title="Preview Your Data" icon="eye" href="/features/data-hub">
    Explore uploaded tables in the Data Hub
  </Card>

  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities from your uploaded data
  </Card>
</CardGroup>


# Google Ads
Source: https://docs.astrobee.ai/data/google-ads

Connect Google Ads to AstroBee

Sync data from Google Ads to AstroBee for analysis and data layer building.

## Overview

| Feature            | Details                |
| ------------------ | ---------------------- |
| **Sync Type**      | Automated via Fivetran |
| **Authentication** | OAuth                  |
| **Data Available** | See tables below       |

## Connecting

1. Navigate to **Data Sources** → **Add New**
2. Click **Google Ads**
3. Authorize AstroBee to access your Google Ads account
4. Configure sync settings

## Sync Frequency

Data syncs automatically based on your Fivetran configuration.

## Security

* OAuth credentials are encrypted and never stored by AstroBee
* Data is encrypted in transit (TLS 1.3) and at rest (AES-256)
* Fivetran is SOC 2 Type II certified

## Next Steps

<CardGroup>
  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities from your Google Ads data
  </Card>

  <Card title="Other Connectors" icon="plug" href="/data/overview">
    Explore more data source options
  </Card>
</CardGroup>


# Google Sheets
Source: https://docs.astrobee.ai/data/google-sheets

Connect Google Sheets to AstroBee

Sync data from Google Sheets to AstroBee for analysis and data layer building.

## Overview

| Feature            | Details                     |
| ------------------ | --------------------------- |
| **Sync Type**      | Live sync via Fivetran      |
| **Authentication** | Google OAuth                |
| **Data Available** | Specified sheets and ranges |

## Connecting

1. Navigate to **Data Sources** → **Add New**
2. Click **Google Sheets**
3. Authorize AstroBee to access your Google account
4. Select the spreadsheets to sync
5. Configure sync settings

## What Gets Synced

* Sheet data as tables
* Column headers as field names
* Automatic type detection

## Sync Frequency

Data syncs automatically based on your Fivetran configuration. Default is every 6 hours.

## Next Steps

<CardGroup>
  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities from your Google Sheets data
  </Card>

  <Card title="Other Connectors" icon="plug" href="/data/overview">
    Explore more data source options
  </Card>
</CardGroup>


# Hubspot
Source: https://docs.astrobee.ai/data/hubspot

Connect Hubspot to AstroBee

Sync data from Hubspot to AstroBee for analysis and data layer building.

## Overview

| Feature            | Details                |
| ------------------ | ---------------------- |
| **Sync Type**      | Automated via Fivetran |
| **Authentication** | OAuth                  |
| **Data Available** | See tables below       |

## Connecting

1. Navigate to **Data Sources** → **Add New**
2. Click **Hubspot**
3. Authorize AstroBee to access your Hubspot account
4. Configure sync settings

## Sync Frequency

Data syncs automatically based on your Fivetran configuration.

## Security

* OAuth credentials are encrypted and never stored by AstroBee
* Data is encrypted in transit (TLS 1.3) and at rest (AES-256)
* Fivetran is SOC 2 Type II certified

## Next Steps

<CardGroup>
  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities from your Hubspot data
  </Card>

  <Card title="Other Connectors" icon="plug" href="/data/overview">
    Explore more data source options
  </Card>
</CardGroup>


# Klaviyo
Source: https://docs.astrobee.ai/data/klaviyo

Connect Klaviyo to AstroBee

Sync data from Klaviyo to AstroBee for analysis and data layer building.

## Overview

| Feature            | Details                |
| ------------------ | ---------------------- |
| **Sync Type**      | Automated via Fivetran |
| **Authentication** | OAuth                  |
| **Data Available** | See tables below       |

## Connecting

1. Navigate to **Data Sources** → **Add New**
2. Click **Klaviyo**
3. Authorize AstroBee to access your Klaviyo account
4. Configure sync settings

## Sync Frequency

Data syncs automatically based on your Fivetran configuration.

## Security

* OAuth credentials are encrypted and never stored by AstroBee
* Data is encrypted in transit (TLS 1.3) and at rest (AES-256)
* Fivetran is SOC 2 Type II certified

## Next Steps

<CardGroup>
  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities from your Klaviyo data
  </Card>

  <Card title="Other Connectors" icon="plug" href="/data/overview">
    Explore more data source options
  </Card>
</CardGroup>


# Linkedin Ads
Source: https://docs.astrobee.ai/data/linkedin-ads

Connect Linkedin Ads to AstroBee

Sync data from Linkedin Ads to AstroBee for analysis and data layer building.

## Overview

| Feature            | Details                |
| ------------------ | ---------------------- |
| **Sync Type**      | Automated via Fivetran |
| **Authentication** | OAuth                  |
| **Data Available** | See tables below       |

## Connecting

1. Navigate to **Data Sources** → **Add New**
2. Click **Linkedin Ads**
3. Authorize AstroBee to access your Linkedin Ads account
4. Configure sync settings

## Sync Frequency

Data syncs automatically based on your Fivetran configuration.

## Security

* OAuth credentials are encrypted and never stored by AstroBee
* Data is encrypted in transit (TLS 1.3) and at rest (AES-256)
* Fivetran is SOC 2 Type II certified

## Next Steps

<CardGroup>
  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities from your Linkedin Ads data
  </Card>

  <Card title="Other Connectors" icon="plug" href="/data/overview">
    Explore more data source options
  </Card>
</CardGroup>


# Meta Ads
Source: https://docs.astrobee.ai/data/meta-ads

Connect Meta Ads to AstroBee

Sync data from Meta Ads to AstroBee for analysis and data layer building.

## Overview

| Feature            | Details                |
| ------------------ | ---------------------- |
| **Sync Type**      | Automated via Fivetran |
| **Authentication** | OAuth                  |
| **Data Available** | See tables below       |

## Connecting

1. Navigate to **Data Sources** → **Add New**
2. Click **Meta Ads**
3. Authorize AstroBee to access your Meta Ads account
4. Configure sync settings

## Sync Frequency

Data syncs automatically based on your Fivetran configuration.

## Security

* OAuth credentials are encrypted and never stored by AstroBee
* Data is encrypted in transit (TLS 1.3) and at rest (AES-256)
* Fivetran is SOC 2 Type II certified

## Next Steps

<CardGroup>
  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities from your Meta Ads data
  </Card>

  <Card title="Other Connectors" icon="plug" href="/data/overview">
    Explore more data source options
  </Card>
</CardGroup>


# Data Sources Overview
Source: https://docs.astrobee.ai/data/overview

Connect your data to AstroBee

AstroBee connects to your data through file uploads and external connectors. Once connected, you can explore your data and build semantic data layers for natural language querying.

## Connection Methods

### File Uploads

Upload spreadsheets directly to AstroBee:

| Format              | Max Size |
| ------------------- | -------- |
| CSV (.csv)          | 300 MB   |
| Excel (.xlsx, .xls) | 300 MB   |

[Learn more about file uploads →](/data/files)

### External Connectors

Connect business tools via secure [Fivetran](https://www.fivetran.com/) integration:

<CardGroup>
  <Card title="Google Sheets" icon="table" href="/data/google-sheets">
    Live sync with specific Google Sheets
  </Card>

  <Card title="Salesforce" icon="cloud" href="/data/salesforce">
    Leads, Opportunities, Accounts
  </Card>

  <Card title="HubSpot" icon="hubspot" href="/data/hubspot">
    Contacts, Deals, Marketing data
  </Card>

  <Card title="LinkedIn Ads" icon="linkedin" href="/data/linkedin-ads">
    Campaign analytics, Ad performance
  </Card>

  <Card title="Reddit Ads" icon="reddit" href="/data/reddit-ads">
    Campaigns, Posts, Engagement
  </Card>

  <Card title="Klaviyo" icon="envelope" href="/data/klaviyo">
    Email campaigns, Flows, Subscribers
  </Card>

  <Card title="Meta Ads" icon="meta" href="/data/meta-ads">
    Campaigns, Audiences, Performance
  </Card>

  <Card title="Google Ads" icon="google" href="/data/google-ads">
    Campaigns, Ad groups, Conversions
  </Card>
</CardGroup>

## How Connectors Work

External data sources use Fivetran for secure, reliable data synchronization:

```mermaid theme={null}
graph LR
    A[Your Data Source] --> B[Fivetran]
    B --> C[AstroBee Warehouse]
    C --> D[Data Layer]
```

1. **Authentication** — You authorize AstroBee to access your data via OAuth
2. **Sync** — Fivetran securely transfers data to your AstroBee warehouse
3. **Analysis** — AstroBee analyzes patterns and discovers relationships
4. **Exploration** — Preview tables and build your data layer

### Security

* **OAuth 2.0** — Industry-standard authorization (credentials never stored)
* **Encryption** — All data encrypted in transit (TLS 1.3) and at rest (AES-256)
* **SOC 2 Certified** — Both Fivetran and AstroBee maintain SOC 2 compliance

[Learn more about security →](/security/overview)

## Adding a Data Source

1. Navigate to **Data Sources** in the sidebar
2. Click **Add New**
3. Select your data source type
4. Complete the authentication flow
5. Wait for initial sync to complete

<Frame>
  <img alt="Add data source" />
</Frame>

## After Connecting

Once your data syncs, AstroBee automatically:

* **Detects schemas** — Identifies tables, columns, and data types
* **Analyzes patterns** — Discovers ID formats, email patterns, date formats
* **Finds linkages** — Identifies relationships between tables

You can then:

* Preview table data
* View discovered patterns
* Connect the source to a data layer
* Build entities and relationships

## Data Source Limits

| Plan       | Data Sources | Storage               |
| ---------- | ------------ | --------------------- |
| Free       | 2            | Shared warehouse      |
| Pro        | Unlimited    | Shared warehouse      |
| Enterprise | Unlimited    | Bring Your Own Bucket |

## Next Steps

<CardGroup>
  <Card title="Upload Files" icon="upload" href="/data/files">
    Upload CSV or Excel files
  </Card>

  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities from your data
  </Card>
</CardGroup>


# Reddit Ads
Source: https://docs.astrobee.ai/data/reddit-ads

Connect Reddit Ads to AstroBee

Sync data from Reddit Ads to AstroBee for analysis and data layer building.

## Overview

| Feature            | Details                |
| ------------------ | ---------------------- |
| **Sync Type**      | Automated via Fivetran |
| **Authentication** | OAuth                  |
| **Data Available** | See tables below       |

## Connecting

1. Navigate to **Data Sources** → **Add New**
2. Click **Reddit Ads**
3. Authorize AstroBee to access your Reddit Ads account
4. Configure sync settings

## Sync Frequency

Data syncs automatically based on your Fivetran configuration.

## Security

* OAuth credentials are encrypted and never stored by AstroBee
* Data is encrypted in transit (TLS 1.3) and at rest (AES-256)
* Fivetran is SOC 2 Type II certified

## Next Steps

<CardGroup>
  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities from your Reddit Ads data
  </Card>

  <Card title="Other Connectors" icon="plug" href="/data/overview">
    Explore more data source options
  </Card>
</CardGroup>


# Salesforce
Source: https://docs.astrobee.ai/data/salesforce

Connect Salesforce to AstroBee

Sync data from Salesforce to AstroBee for analysis and data layer building.

## Overview

| Feature            | Details                |
| ------------------ | ---------------------- |
| **Sync Type**      | Automated via Fivetran |
| **Authentication** | OAuth                  |
| **Data Available** | See tables below       |

## Connecting

1. Navigate to **Data Sources** → **Add New**
2. Click **Salesforce**
3. Authorize AstroBee to access your Salesforce account
4. Configure sync settings

## Sync Frequency

Data syncs automatically based on your Fivetran configuration.

## Security

* OAuth credentials are encrypted and never stored by AstroBee
* Data is encrypted in transit (TLS 1.3) and at rest (AES-256)
* Fivetran is SOC 2 Type II certified

## Next Steps

<CardGroup>
  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities from your Salesforce data
  </Card>

  <Card title="Other Connectors" icon="plug" href="/data/overview">
    Explore more data source options
  </Card>
</CardGroup>


# Analytics Chat
Source: https://docs.astrobee.ai/features/analytics

Ask questions about your data in plain English

Analytics Chat is AstroBee's natural language interface for querying your data. Ask questions in plain English and get answers with full transparency into the SQL and logic used.

<Frame>
  <img alt="Analytics chat" />
</Frame>

## Starting a Chat

Click **New Chat** in the sidebar to start a conversation. Each chat is saved and accessible from the sidebar.

## Asking Questions

Type your question in plain English:

```
How many customers do we have?
```

```
What are the top 5 products by revenue?
```

```
Show me customers who placed more than 2 orders last month
```

AstroBee interprets your question, generates SQL against your data layer, executes it, and returns the answer.

## Understanding Responses

Each response includes multiple views:

### Answer

The direct answer to your question in natural language:

> You have 20 customers in your database.

### SQL View

Click **SQL** to see the exact query AstroBee generated:

<Frame>
  <img alt="SQL view" />
</Frame>

The SQL shows:

* Which tables and entities were queried
* Join conditions used
* Aggregations and filters applied

<Tip>
  You can copy the SQL and run it directly in your warehouse for verification or further analysis.
</Tip>

### Logic View

Click **Logic** to understand AstroBee's reasoning:

<Frame>
  <img alt="Logic view" />
</Frame>

The Logic view explains:

* How AstroBee interpreted your question
* Which entities and relationships it used
* Why it chose that particular approach

### Full Report

Click **Full Report** for a complete breakdown:

<Frame>
  <img alt="Full report" />
</Frame>

The report includes:

* Original question
* Answer
* SQL query
* Full logic explanation
* Timestamp

## Browsing the Data Layer

While chatting, click **Data Layer** to browse available entities:

<Frame>
  <img alt="Browse data layer" />
</Frame>

The browser shows:

* All entities in your data layer
* Entity descriptions
* Option to preview data or show fields

This helps you understand what data is available when forming questions.

## Chat History

### Saved Conversations

All chats are automatically saved and appear in the sidebar under **CHATS**. Click any chat to continue the conversation.

### Renaming Chats

Click the chat title to rename it. Descriptive names help you find conversations later.

### Deleting Chats

Click the delete button next to a chat title to remove it.

## Question Tips

<AccordionGroup>
  <Accordion title="Be specific">
    "Show revenue by product category" is better than "Show me revenue"
  </Accordion>

  <Accordion title="Use time ranges">
    "Orders from last month" or "Customers who signed up in 2024"
  </Accordion>

  <Accordion title="Ask for comparisons">
    "Compare revenue between Q1 and Q2" or "Top 10 vs bottom 10 customers"
  </Accordion>

  <Accordion title="Request visualizations">
    "Show a bar chart of..." or "Visualize..." (coming soon)
  </Accordion>

  <Accordion title="Follow up">
    Build on previous answers: "Now break that down by region"
  </Accordion>
</AccordionGroup>

## Reporting Issues

If an answer seems incorrect, click **Report Issue** to flag it for review. Include details about:

* What you expected
* What was returned
* Why you think it's wrong

Your feedback helps improve AstroBee's accuracy.

## Limitations

* Questions must relate to data in your connected data layer
* Complex multi-step calculations may require refining your data layer
* Very large result sets are automatically limited

## Next Steps

<CardGroup>
  <Card title="Build Your Data Layer" icon="sitemap" href="/features/data-layer">
    Define entities and relationships for better answers
  </Card>

  <Card title="MCP Integration" icon="terminal" href="/features/mcp">
    Query from Claude Desktop or VS Code
  </Card>
</CardGroup>


# Data Hub
Source: https://docs.astrobee.ai/features/data-hub

Connect, preview, and analyze your data sources

The Data Hub is your central location for managing all data connections in AstroBee. Upload files, connect external tools, and explore your data before building a data layer.

<Frame>
  <img alt="Data Hub" />
</Frame>

## Accessing the Data Hub

Click **Data Sources** in the sidebar to open the Data Hub.

## Adding Data Sources

Click **Add New** to see all available connection options:

<Frame>
  <img alt="Add data source" />
</Frame>

### File Uploads

Upload spreadsheets directly:

| Format              | Max Size | Features                  |
| ------------------- | -------- | ------------------------- |
| CSV                 | 300 MB   | Automatic type detection  |
| Excel (.xlsx, .xls) | 300 MB   | Multiple sheets supported |

Drag and drop files or click to browse.

### External Connectors

Connect business tools via secure Fivetran integration:

| Connector         | Data Types                           |
| ----------------- | ------------------------------------ |
| **Google Sheets** | Live sync with specific sheets       |
| **Salesforce**    | Leads, Opportunities, Accounts       |
| **HubSpot**       | Contacts, Deals, Marketing data      |
| **LinkedIn Ads**  | Campaign analytics, Ad performance   |
| **Reddit Ads**    | Campaigns, Posts, Engagement metrics |
| **Klaviyo**       | Email campaigns, Flows, Subscribers  |
| **Meta Ads**      | Campaigns, Audiences, Performance    |
| **Google Ads**    | Campaigns, Ad groups, Conversions    |

<Info>
  External connections use [Fivetran](https://www.fivetran.com/), a SOC 2 certified data integration platform. Your credentials are encrypted and never stored by AstroBee.
</Info>

## Data Source Cards

Each connected source shows a card with key information:

| Field                | Description                        |
| -------------------- | ---------------------------------- |
| **Name**             | Editable display name              |
| **Type**             | CSV Upload or connector name       |
| **Pattern Analysis** | Status of column pattern discovery |
| **Intra Linkage**    | Status of relationship discovery   |
| **Last Sync**        | When data was last updated         |
| **Rows Synced**      | Total row count                    |
| **Tables**           | Available tables in this source    |

## Exploring Tables

Click a table name to preview its data:

<Frame>
  <img alt="Table preview" />
</Frame>

The preview shows:

* Column names with data types
* Sample data (up to 20 rows)
* Pattern analysis buttons for each column

### Pattern Analysis

AstroBee automatically analyzes columns to discover patterns:

<Frame>
  <img alt="Pattern analysis" />
</Frame>

Pattern details include:

* **Description** — Human-readable pattern explanation
* **Coverage** — Percentage of values matching the pattern
* **Regex** — Technical pattern definition
* **Examples** — Sample values matching the pattern

Patterns help AstroBee:

* Understand data semantics (IDs, emails, dates)
* Suggest appropriate entity mappings
* Discover relationships between tables

## Linkage Discovery

AstroBee automatically discovers relationships between tables within a data source:

* **Key references** — Foreign key relationships (e.g., `orders.customer_id` → `customers.customer_id`)
* **Pattern matches** — Columns with matching patterns across tables

View discovered linkages in the Data Layer → Linkages tab.

## Managing Data Sources

### Renaming

Click the data source name to rename it. Names help identify sources when connecting to data layers.

### Syncing

External connectors sync automatically based on your Fivetran configuration. File uploads are one-time imports.

To update file data:

1. Upload a new version of the file
2. The existing source is replaced

### Deleting

Click the menu button (⋮) on a data source card to delete it.

<Warning>
  Deleting a data source removes its data from AstroBee. Data layers using this source will lose access to its tables.
</Warning>

## Demo Data

New accounts can load demo datasets to explore AstroBee:

| Demo                    | Contents                                        |
| ----------------------- | ----------------------------------------------- |
| **Basic E-Commerce**    | Customers, Products, Orders (1 source)          |
| **Complete E-Commerce** | Full e-commerce with marketing data (2 sources) |

Demo data is great for learning the platform before connecting your own data.

## Next Steps

<CardGroup>
  <Card title="Build a Data Layer" icon="sitemap" href="/features/data-layer">
    Create entities and relationships from your data
  </Card>

  <Card title="Connector Guides" icon="plug" href="/data/overview">
    Step-by-step guides for each connector
  </Card>
</CardGroup>


# Data Layer
Source: https://docs.astrobee.ai/features/data-layer

Define how your business concepts map to your raw data

The Data Layer is AstroBee's semantic modeling feature. It creates a business-friendly abstraction over your raw data, allowing you to ask questions in plain English without knowing where the data lives or how tables connect.

## Overview

A data layer consists of:

* **Entities** — Business concepts like Customer, Product, or Order
* **Properties** — Attributes of entities (e.g., Customer.email, Product.price)
* **Relationships** — How entities connect (e.g., Customer → Order)

<Frame>
  <img alt="Data layer graph" />
</Frame>

## Accessing the Data Layer

Click **Data Layer** in the sidebar to open the editor. The editor has three main tabs:

| Tab            | Purpose                                      |
| -------------- | -------------------------------------------- |
| **Data Layer** | View and edit entities in Graph or List view |
| **Sources**    | Connect data sources to your data layer      |
| **Linkages**   | View discovered relationships between tables |

## Generating a Data Layer

### Connect Sources First

Before generating, connect at least one data source:

1. Click the **Sources** tab
2. Find available data sources
3. Click **Connect** to link them to this data layer

<Frame>
  <img alt="Sources tab" />
</Frame>

### AI-Assisted Generation

Click **Generate Data Layer from selected Sources** to start the AI-assisted workflow:

1. **Business Questions** — AstroBee asks what you want to analyze (customer behavior, sales performance, etc.)
2. **Terminology** — Define your business language (orders vs. sales vs. transactions)
3. **Generation** — AI analyzes your data and creates entities with proper bindings

<Frame>
  <img alt="Generation questionnaire" />
</Frame>

The AI will:

* Discover tables and columns in your data sources
* Match entities to tables by name similarity
* Map properties to columns based on data types and meanings
* Create relationships based on discovered linkages

<Frame>
  <img alt="Generation summary" />
</Frame>

## Viewing Your Data Layer

### Graph View

The default view shows entities as nodes and relationships as edges:

<Frame>
  <img alt="Graph view" />
</Frame>

* **Nodes** represent entities (dimension, fact, or bridge types)
* **Edges** show relationships with cardinality (1:N, N:N)
* Click **Expand to fullscreen** for a larger view

### List View

Click **List View** for a detailed breakdown:

<Frame>
  <img alt="List view" />
</Frame>

The list view shows:

* Entity names and descriptions
* All properties with types (Dimension/Measure) and data types
* Field descriptions
* Relationships with join conditions

## Editing Your Data Layer

### Chat-Based Editing

Use the chat input at the bottom to make changes in natural language:

```
Add a property called "lifetime_value" to Customer that calculates
total spend across all orders
```

```
Create a relationship between Product and OrderItem
```

AstroBee interprets your request, makes the changes, and shows them in the Review panel.

### Direct Editing

In List View, click on any element to edit directly:

* Click entity names to rename
* Click descriptions to update
* Click properties to modify types or descriptions

## Reviewing Changes

All changes go to a **scratchpad** before being published. Click the **Review** button to see pending changes:

<Frame>
  <img alt="Review panel" />
</Frame>

The review panel shows:

* **Created** items (new entities, properties, relationships)
* **Modified** items (updated definitions)
* **Deleted** items (removed elements)

Actions:

* **Publish all pending changes** — Apply changes and create a new version
* **Discard all pending changes** — Revert the scratchpad

## Version History

Every time you publish, AstroBee creates a new version. View history by clicking the version buttons:

<Frame>
  <img alt="Version history" />
</Frame>

Version history includes:

* Timestamp of each version
* Conversation history (what was discussed to create that version)
* Ability to view any previous version

<Note>
  Versions are immutable. To make changes, edit the current version and publish a new one.
</Note>

## Linkage Discovery

The **Linkages** tab shows relationships AstroBee discovered between your source tables:

<Frame>
  <img alt="Linkages tab" />
</Frame>

Click a linkage to see details:

<Frame>
  <img alt="Linkage details" />
</Frame>

Each linkage shows:

* **SQL join logic** — The actual join condition
* **Validation status** — Whether the join was tested
* **Statistics** — Confidence, coverage, row counts
* **Sample matches** — Example values that match

## Entity Types

AstroBee uses three entity types:

| Type          | Purpose                                        | Example                   |
| ------------- | ---------------------------------------------- | ------------------------- |
| **Dimension** | Descriptive attributes for grouping/filtering  | Customer, Product, Region |
| **Fact**      | Measurable events or transactions              | Order, PageView, Payment  |
| **Bridge**    | Junction tables for many-to-many relationships | OrderItem, UserRole       |

## Property Types

Properties are classified as:

| Type          | Purpose                              | Example                        |
| ------------- | ------------------------------------ | ------------------------------ |
| **Dimension** | Attributes for grouping or filtering | customer\_id, category, status |
| **Measure**   | Numeric values for aggregation       | price, quantity, total\_amount |

## Best Practices

<AccordionGroup>
  <Accordion title="Start with AI generation">
    Let AstroBee create the initial structure, then refine. It's faster than building from scratch.
  </Accordion>

  <Accordion title="Use descriptive names">
    Entity and property names should match how your team talks about the business.
  </Accordion>

  <Accordion title="Add descriptions">
    Good descriptions help AstroBee understand context when answering questions.
  </Accordion>

  <Accordion title="Review linkages">
    Check the Linkages tab to ensure discovered relationships are correct before building on them.
  </Accordion>

  <Accordion title="Version frequently">
    Publish often to maintain a clear history of changes.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Analytics Chat" icon="message-circle" href="/features/analytics">
    Ask questions about your data layer
  </Card>

  <Card title="Connect Data Sources" icon="plug" href="/data/overview">
    Add more data to your data layer
  </Card>
</CardGroup>


# MCP Integration
Source: https://docs.astrobee.ai/features/mcp

Connect your AI assistant to query your data layers directly

With MCP (Model Context Protocol), your AI assistant connects directly to your AstroBee data layers. Explore schemas, run SQL, and get insights without leaving Claude Code, Claude Desktop, or VS Code.

[MCP](https://modelcontextprotocol.io/) is an open standard that lets AI assistants securely connect to external tools and data sources. AstroBee's MCP server gives your assistant read access to your data layers and the ability to execute queries on your behalf.

## Managing Connections

Access MCP settings via **Settings** → **MCP** tab:

<Frame>
  <img alt="MCP settings" />
</Frame>

The MCP page shows:

* **Authorized Applications** — Apps currently connected to your account
* **Setup Instructions** — Configuration for different AI clients
* **Security Information** — How your data is protected

## Quick Setup

<Tabs>
  <Tab title="Claude Code">
    1. Run this command in your terminal:

    ```bash theme={null}
    claude mcp add astrobee --transport http https://app.astrobee.ai/api/mcp
    ```

    2. In Claude Code, type `/mcp` and select "Authenticate"
    3. Sign in with your AstroBee account in the browser

    Learn more about [MCP in Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp).
  </Tab>

  <Tab title="Claude Desktop">
    1. Open **Settings** → **Connectors** → **Add custom connector**
    2. Enter this URL:

    ```
    https://app.astrobee.ai/api/mcp
    ```

    3. Click **Connect** and sign in with your AstroBee account
  </Tab>

  <Tab title="Other MCP Clients">
    Use this JSON configuration for any MCP-compatible client:

    ```json theme={null}
    {
        "astrobee": {
            "type": "http",
            "url": "https://app.astrobee.ai/api/mcp"
        }
    }
    ```
  </Tab>
</Tabs>

## Available Tools

Once connected, your AI assistant has access to 12 tools:

### Server & Model Discovery

| Tool                 | Description                                   |
| -------------------- | --------------------------------------------- |
| `server-status`      | Check server health and connection statistics |
| `list-ontologies`    | List all data layers you have access to       |
| `list-source-models` | Get raw data schemas linked to a data layer   |

### Entity & Property Exploration

| Tool                 | Description                                                  |
| -------------------- | ------------------------------------------------------------ |
| `list-entities`      | List all entities with metadata (optionally with row counts) |
| `list-properties`    | Get all properties for a specific entity                     |
| `describe-property`  | Get detailed info about a property (type, dimension/measure) |
| `list-relationships` | View how entities are connected                              |

### Statistics & Data Quality

| Tool                  | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| `list-entity-stats`   | Get entity metrics (row count, property counts, quality scores) |
| `list-property-stats` | Get property statistics (uniqueness, null %, distinct counts)   |

### SQL Execution

| Tool                  | Description                                       |
| --------------------- | ------------------------------------------------- |
| `get-datasource-type` | Get the database engine for correct SQL syntax    |
| `validate-sql`        | Check if a SQL query is valid without executing   |
| `execute-sql`         | Run a SQL query and get results (up to 1000 rows) |

<Tip>
  For editing data layers, use the AstroBee web interface. MCP tools are read-only to maintain data layer consistency.
</Tip>

## Security

* **OAuth 2.0** — Secure authorization flow
* **Scoped Access** — Tools only access data you've authorized
* **Revocable** — Remove access anytime from Settings → MCP
* **Audit Logged** — All queries are logged for security

## Revoking Access

To disconnect an authorized application:

1. Go to **Settings** → **MCP**
2. Find the application in the Authorized Applications list
3. Click **Revoke**

The application immediately loses access to your data.

## Next Steps

<CardGroup>
  <Card title="Claude Desktop Tutorial" href="/tutorials/connect-claude-desktop" icon="message-circle">
    Detailed setup guide for Claude Desktop
  </Card>

  <Card title="VS Code Tutorial" href="/tutorials/connect-vscode" icon="code">
    Query data layers from VS Code
  </Card>
</CardGroup>


# Glossary
Source: https://docs.astrobee.ai/glossary

Key terms and concepts in AstroBee

## A

### Analytics Chat

The natural language interface for querying your data. Ask questions in plain English and get answers with full SQL transparency.

## D

### Data Hub

The central location for managing all data connections. Upload files, connect external tools, and explore your data.

### Data Layer

A semantic model that maps business concepts to raw data. Consists of entities, properties, and relationships. Previously called "Ontology" in some contexts.

### Data Source

A connection to external data—either an uploaded file or a connected service like Salesforce or Google Sheets.

### Dimension

A property used for grouping or filtering data. Examples: customer\_id, category, status.

## E

### Entity

A business concept in your data layer. Examples: Customer, Product, Order. Entities have properties and relationships.

### Entity Resolution

The process of matching records that refer to the same real-world entity across different data sources, even when identifiers differ.

## F

### Fact

An entity type representing measurable events or transactions. Examples: Order, PageView, Payment.

### Fivetran

AstroBee's partner for external data connections. A SOC 2 certified data integration platform.

## L

### Linkage

A discovered relationship between tables, typically a foreign key reference like `orders.customer_id` → `customers.customer_id`.

## M

### MCP (Model Context Protocol)

An open standard that lets AI assistants connect to external tools. AstroBee's MCP server enables querying data layers from Claude Code, Claude Desktop, or VS Code.

### Measure

A property that contains numeric values for aggregation. Examples: price, quantity, total\_amount.

## N

### Normalization

The process of standardizing data formats (like email case normalization) to enable accurate matching across sources.

## O

### OAuth

The authorization standard used for connecting external data sources. Credentials are never stored by AstroBee.

## P

### Pattern Analysis

Automatic discovery of data patterns in columns, such as ID formats, email structures, or date formats.

### Property

An attribute of an entity. Examples: Customer.email, Product.price. Properties are classified as Dimensions or Measures.

## R

### Relationship

A connection between entities in your data layer. Defined by cardinality (one-to-many, many-to-many) and join conditions.

## S

### Scratchpad

A working area for data layer changes before they're published. Review and publish changes to create a new version.

### SQL Transparency

AstroBee shows the exact SQL query generated for every answer, so you can verify and understand the logic.

## V

### Version History

The record of all published versions of a data layer, including conversation history and changes made.


# AstroBee
Source: https://docs.astrobee.ai/index

Your AI Data Integrator

[AstroBee](https://astrobee.ai/) is an AI agent that helps business teams explore data and get answers without adding to the data team's backlog. It connects directly to your existing data (even if it's messy) and builds a [data layer](/glossary#data-layer) that captures business logic as it evolves.

Unlike most tools that require clean, well-structured data, AstroBee generates an integrated source of truth for you. This data layer (a map of how your business concepts connect to your data and to each other) translates messy, fragmented data into something usable, so teams can get precise, context-aware answers without waiting for a custom report from the data team.

There's no need to refactor pipelines or touch your existing semantic layer. AstroBee fits alongside your current stack, shows its work behind every answer, and gives business users the confidence to explore independently—freeing up data scientists to focus on deeper, strategic work.

## How It Works

<Steps>
  <Step title="Connect your data">
    Upload CSV/Excel files or connect external tools like [Google Sheets, HubSpot, Salesforce](/data/overview), and more via secure Fivetran integration
  </Step>

  <Step title="Build your data layer">
    AstroBee's AI analyzes your data, asks clarifying questions about your business, and auto-generates entities and relationships—no manual modeling required
  </Step>

  <Step title="Ask questions & evolve">
    [Ask AstroBee](/features/analytics) business questions in plain language. View the SQL and logic behind every answer. Refine your [data layer](/features/data-layer) as your business grows
  </Step>
</Steps>

## Key Features

<CardGroup>
  <Card title="Data Hub" icon="database" href="/features/data-hub">
    Connect data sources, preview tables, and discover patterns automatically
  </Card>

  <Card title="Data Layer" icon="sitemap" href="/features/data-layer">
    AI-assisted semantic modeling with graph visualization and version history
  </Card>

  <Card title="Analytics Chat" icon="message-circle" href="/features/analytics">
    Ask questions in plain English, get answers with full SQL transparency
  </Card>

  <Card title="MCP Integration" icon="plug" href="/features/mcp">
    Query your data layers from Claude Desktop, VS Code, or any MCP client
  </Card>
</CardGroup>

## Get Started

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build a data layer and ask questions in minutes using demo data
  </Card>

  <Card title="Connect Data Sources" icon="plug" href="/data/overview">
    Connect your own data from files, warehouses, or business tools
  </Card>
</CardGroup>

## Security & Compliance

AstroBee is built with enterprise security in mind. Visit our [Trust Center](https://trust.astrobee.ai/) for SOC 2 reports, security policies, and compliance documentation.

<Card title="Security Overview" icon="shield-check" href="/security/overview">
  Learn about our security practices, data handling, and compliance
</Card>


# Quickstart
Source: https://docs.astrobee.ai/quickstart

Build a data layer and ask questions about your data in minutes

In this quickstart, you'll load demo e-commerce data, watch AstroBee build a semantic data layer, and ask business questions in plain English—all in under 10 minutes.

<Info>
  **Prerequisites**: [Create an account](https://app.astrobee.ai) and sign in before you begin.
</Info>

## Load Demo Data

After signing in, you'll land on the **Data Hub**. For new accounts, AstroBee offers demo datasets to help you explore the platform.

<Frame>
  <img alt="Data Hub with demo data options" />
</Frame>

Click **Basic E-Commerce** to load a pre-configured dataset with:

* **Customers** — Customer information and purchase history
* **Products** — Product catalog with categories and pricing
* **Orders** — Transaction records linking customers to products

<Frame>
  <img alt="Loading demo data" />
</Frame>

Once loaded, AstroBee automatically:

1. **Analyzes patterns** in your data columns (e.g., ID formats, email patterns)
2. **Discovers linkages** between tables (e.g., `orders.customer_id` → `customers.customer_id`)

## Explore Your Data

Click on any table to preview its data and see discovered patterns:

<Frame>
  <img alt="Table detail view" />
</Frame>

### Pattern Analysis

AstroBee automatically identifies patterns in your columns. Click the pattern icon next to a column to see details:

<Frame>
  <img alt="Column patterns" />
</Frame>

Pattern analysis helps AstroBee understand your data semantics and suggest appropriate entity mappings.

## Build Your Data Layer

Navigate to **Data Layer** in the sidebar. This is where you define how your business concepts map to your raw data.

### Connect Data Sources

1. Click the **Sources** tab
2. Click **Connect** next to your E-Commerce data source

<Frame>
  <img alt="Sources tab" />
</Frame>

### Generate with AI

Click **Generate Data Layer from selected Sources**. AstroBee's AI will ask a few questions to understand your business:

<Frame>
  <img alt="Generation questionnaire" />
</Frame>

Select your answers and AstroBee will:

1. Analyze your connected data sources
2. Identify entities (Customer, Product, Order, OrderItem)
3. Map relationships between them
4. Bind entities to source tables

<Frame>
  <img alt="Generation complete" />
</Frame>

### Review the Graph

Switch to the **Data Layer** tab to see your entities visualized:

<Frame>
  <img alt="Data layer graph" />
</Frame>

The graph shows:

* **Customer** (dimension) — Individual customers
* **Product** (dimension) — Products in your catalog
* **Order** (fact) — Customer transactions
* **OrderItem** (bridge) — Line items linking orders to products

### Review and Publish

Click **Review** to see all pending changes before publishing:

<Frame>
  <img alt="Review panel" />
</Frame>

Click **Publish all pending changes** to make your data layer active.

## Ask Questions

With your data layer published, you're ready to ask questions! Click **New Chat** in the sidebar.

<Frame>
  <img alt="New chat" />
</Frame>

Type a question in plain English:

```
How many customers do we have?
```

<Frame>
  <img alt="Chat response" />
</Frame>

### View the SQL

Click **SQL** to see the exact query AstroBee generated:

<Frame>
  <img alt="SQL view" />
</Frame>

### Understand the Logic

Click **Logic** to see how AstroBee reasoned through your question:

<Frame>
  <img alt="Logic view" />
</Frame>

### Full Report

Click **Full Report** for a complete breakdown:

<Frame>
  <img alt="Full report" />
</Frame>

## Try More Questions

Now explore your data with more questions:

```
What are our top 5 products by total revenue?
```

```
Show me customers who have placed more than 2 orders
```

```
What's the average order value by product category?
```

Each answer shows the SQL and logic, so you always understand how AstroBee arrived at the result.

## Next Steps

<CardGroup>
  <Card title="Connect Your Data" icon="plug" href="/data/overview">
    Connect your own data sources—files, databases, or business tools
  </Card>

  <Card title="Data Layer Deep Dive" icon="sitemap" href="/features/data-layer">
    Learn more about editing and versioning your data layer
  </Card>

  <Card title="Analytics Features" icon="chart-bar" href="/features/analytics">
    Explore charts, exports, and advanced query features
  </Card>

  <Card title="MCP Integration" icon="terminal" href="/features/mcp">
    Query your data from Claude Desktop or VS Code
  </Card>
</CardGroup>

**Need help?** Contact us at [hello@astrobee.ai](mailto:hello@astrobee.ai).


# Security & Compliance
Source: https://docs.astrobee.ai/security/overview

How AstroBee protects your data and maintains compliance

AstroBee is built with security at its core. We implement industry-standard security practices and maintain compliance certifications to protect your data.

## Trust Center

For detailed information about our security practices, compliance certifications, and policies, visit our Trust Center:

<Card title="AstroBee Trust Center" icon="shield" href="https://trust.astrobee.ai/">
  View our security documentation, compliance reports, and policies
</Card>

Our Trust Center includes:

* **SOC 2 Type II** compliance status and reports
* Security policies and procedures
* Subprocessor list
* Data Processing Agreement (DPA)
* Penetration test summaries

## Security Overview

### Data Encryption

| Layer           | Protection                                          |
| --------------- | --------------------------------------------------- |
| **In Transit**  | TLS 1.3 encryption for all data transfers           |
| **At Rest**     | AES-256 encryption for stored data                  |
| **Credentials** | AES-256-GCM encryption for OAuth tokens and secrets |

### Infrastructure

AstroBee runs on secure, SOC 2 compliant cloud infrastructure with:

* Isolated compute environments
* Regular security patches and updates
* Network segmentation and firewalls
* DDoS protection

### Access Control

* **Authentication**: Secure passwordless authentication and OAuth providers (Google)
* **Authorization**: Role-based access control (Admin, Member)
* **Sessions**: Secure session management with automatic timeouts
* **API Access**: OAuth 2.0 client credentials for programmatic access

## Data Handling

### Your Data Stays Yours

* AstroBee queries your data sources but does not permanently store your raw data
* Query results are cached temporarily for performance, then purged
* Conversation history is retained for your convenience and can be deleted anytime
* Enterprise customers can use Bring Your Own Bucket (BYOB) for complete data control

### Data Processing

* All data processing occurs in secure, isolated environments
* AI features use API-only integrations with no data retention by AI providers
* Your data is never used to train AI models

### Data Retention

| Data Type              | Retention        | Deletion            |
| ---------------------- | ---------------- | ------------------- |
| Chat conversations     | Until you delete | Self-service in app |
| Data layer definitions | Until you delete | Self-service in app |
| Uploaded files         | Until you delete | Self-service in app |
| Audit logs             | 90 days          | Automatic           |

## Third-Party Integrations

AstroBee uses trusted partners for specific functionality:

### Fivetran (Data Connectors)

External data source connections (Google Sheets, Salesforce, HubSpot, etc.) are powered by [Fivetran](https://www.fivetran.com/), a SOC 2 Type II certified data integration platform.

* Data flows: Source → Fivetran → AstroBee Warehouse
* All transfers encrypted in transit
* Fivetran does not retain your data after sync
* View [Fivetran's security practices](https://www.fivetran.com/legal/security-practices)

### AI Providers

AstroBee uses leading AI providers for natural language processing:

* API-only integration (no data retention)
* Your data is not used for model training
* Conversations are not stored by AI providers

## Reporting Security Issues

If you discover a security vulnerability, please report it responsibly:

* **Email**: [security@astrobee.ai](mailto:security@astrobee.ai)
* **Response time**: We acknowledge reports within 24 hours

## Compliance Questions

For compliance documentation, audit requests, or security questionnaires:

* Visit our [Trust Center](https://trust.astrobee.ai/)
* Contact [compliance@astrobee.ai](mailto:compliance@astrobee.ai)

## Next Steps

<CardGroup>
  <Card title="Trust Center" icon="shield" href="https://trust.astrobee.ai/">
    Access compliance reports and security documentation
  </Card>

  <Card title="Organization Settings" icon="building" href="/settings/organization">
    Manage team access and permissions
  </Card>
</CardGroup>


# Integrations
Source: https://docs.astrobee.ai/settings/integrations

Configure OAuth credentials for third-party API integrations

The Integrations page lets you configure OAuth app credentials for third-party API data sources. Once configured, users in your organization can connect their external accounts from the Data Hub.

Access it via **Settings** → **Integrations** tab.

<Frame>
  <img alt="Integrations settings" />
</Frame>

## How It Works

Integration providers store OAuth app credentials (Client ID and Client Secret) that allow users in your organization to connect their external accounts:

1. **Admin configures** OAuth credentials in Settings → Integrations
2. **Users connect** their accounts from Data Hub → Add New
3. **Data syncs** through the configured OAuth app

<Note>
  Most data source connections use [Fivetran](https://www.fivetran.com/) and don't require manual OAuth configuration. Custom integrations are for advanced use cases.
</Note>

## Configured Providers

View all configured integration providers in the table:

| Column       | Description                                        |
| ------------ | -------------------------------------------------- |
| **Provider** | The third-party service (e.g., Google, Salesforce) |
| **Status**   | Enabled or Disabled                                |
| **Created**  | When the integration was configured                |

## Adding a Provider

1. Click **Add Provider** or **Configure Your First Integration**
2. Select the provider type
3. Enter your OAuth credentials:
   * **Client ID** — From the provider's developer console
   * **Client Secret** — From the provider's developer console
4. Save the configuration

### Getting OAuth Credentials

OAuth credentials come from each provider's developer console:

| Provider   | Developer Console                                                 |
| ---------- | ----------------------------------------------------------------- |
| Google     | [Google Cloud Console](https://console.cloud.google.com/)         |
| Salesforce | [Salesforce Developer Console](https://developer.salesforce.com/) |
| HubSpot    | [HubSpot Developer Portal](https://developers.hubspot.com/)       |

<Tip>
  Refer to each provider's documentation for specific setup instructions.
</Tip>

## Security

* **Encryption** — Credentials are encrypted at rest using AES-256-GCM
* **Access Control** — Only Admins can view or modify integrations
* **Audit** — All configuration changes are logged

## Managing Providers

### Disabling a Provider

Disabling a provider:

* Prevents new connections using these credentials
* Keeps existing connections active
* Can be re-enabled at any time

### Deleting a Provider

Deleting a provider:

* Permanently removes the credentials
* Existing connections continue to work (using cached tokens)
* New connections cannot be created

## Next Steps

<CardGroup>
  <Card title="Data Sources" icon="database" href="/data/overview">
    Connect data sources using configured integrations
  </Card>

  <Card title="MCP Settings" icon="terminal" href="/features/mcp">
    Configure MCP for AI assistant access
  </Card>
</CardGroup>


# Organization Settings
Source: https://docs.astrobee.ai/settings/organization

Manage your workspace, team members, and API access

Organization settings let you manage your workspace identity, team access, and programmatic API access via OAuth clients.

Access settings by clicking **Settings** in the sidebar.

<Frame>
  <img alt="Organization settings" />
</Frame>

## Organization Overview

The overview section shows key metrics:

| Metric           | Description                          |
| ---------------- | ------------------------------------ |
| **Team Members** | Number of users in your organization |
| **Data Layers**  | Number of data layers created        |
| **Data Sources** | Number of connected data sources     |

## Organization Identity

Update your organization's display name:

1. Edit the **Organization Name** field
2. Click **Save Changes**

The **Organization ID** is a unique identifier used for API integrations and cannot be changed.

## OAuth API Clients

Create OAuth clients for programmatic access to AstroBee APIs. This is useful for:

* Internal integrations
* Custom tools
* Third-party applications that need API access

### Creating a Client

1. Click **Create Client** in the OAuth API Clients section
2. Enter a name for your client
3. Save the generated **Client ID** and **Client Secret**

<Warning>
  The Client Secret is only shown once. Store it securely—you cannot retrieve it later.
</Warning>

### Client Credentials

| Credential        | Purpose                                      |
| ----------------- | -------------------------------------------- |
| **Client ID**     | Public identifier for your application       |
| **Client Secret** | Private key for authentication (keep secure) |

### Managing Clients

* View all clients in the OAuth API Clients table
* Disable clients to temporarily revoke access
* Delete clients to permanently remove access

## Team Members

Manage who has access to your organization:

<Frame>
  <img alt="Team members" />
</Frame>

### Roles

| Role       | Permissions                                                   |
| ---------- | ------------------------------------------------------------- |
| **Admin**  | Full access: manage settings, team, data sources, data layers |
| **Member** | Standard access: view and edit data layers, ask questions     |

### Inviting Members

1. Click **Invite Member**
2. Enter the email address
3. Select a role (Admin or Member)
4. Send the invitation

Invited users receive an email to join your organization.

### Managing Members

* Change roles by clicking the role dropdown next to a member
* Remove members by clicking the remove button
* The last Admin cannot be removed or demoted

<Note>
  At least one Admin must remain in the organization at all times.
</Note>

## Next Steps

<CardGroup>
  <Card title="Warehouse Configuration" icon="database" href="/settings/warehouse">
    Configure your data warehouse settings
  </Card>

  <Card title="Security Overview" icon="shield-check" href="/security/overview">
    Learn about security and compliance
  </Card>
</CardGroup>


# User Profile
Source: https://docs.astrobee.ai/settings/profile

Manage your personal account settings

The Profile page lets you manage your personal information and account settings.

Access it by clicking **Profile** in the sidebar (below your avatar).

<Frame>
  <img alt="User profile" />
</Frame>

## Personal Details

View and update your profile information:

| Field             | Description                   | Editable          |
| ----------------- | ----------------------------- | ----------------- |
| **Display Name**  | Your name shown in the app    | Yes               |
| **Email Address** | Your sign-in email            | No                |
| **Role**          | Your role in the organization | No (set by Admin) |

### Updating Your Name

1. Edit the **Display Name** field
2. Click **Save Changes**

Your new name appears throughout the app and in team member lists.

## Password Management

AstroBee uses secure passwordless authentication. To change your password:

1. Click **Request password reset →**
2. Check your email for a reset link
3. Follow the link to set a new password

<Note>
  Password reset links expire after 24 hours for security.
</Note>

## Signing Out

To sign out of AstroBee:

1. Click **Logout** in the sidebar (below your profile)

You'll be returned to the sign-in page.

## Account Security

Your account is protected by:

* **Secure authentication** — Passwordless or OAuth sign-in
* **Session management** — Automatic timeout after inactivity
* **Encrypted storage** — All personal data encrypted at rest

For organization-level security settings, contact your Admin.

## Next Steps

<CardGroup>
  <Card title="Organization Settings" icon="building" href="/settings/organization">
    Manage team and workspace settings (Admin only)
  </Card>

  <Card title="Security Overview" icon="shield-check" href="/security/overview">
    Learn about AstroBee's security practices
  </Card>
</CardGroup>


# Warehouse Configuration
Source: https://docs.astrobee.ai/settings/warehouse

Configure your data warehouse and storage options

The Warehouse settings page lets you view and configure how AstroBee stores and processes your data.

Access it via **Settings** → **Warehouse** tab.

<Frame>
  <img alt="Warehouse settings" />
</Frame>

## Default Configuration

By default, your organization uses a **shared DuckDB warehouse** with platform-managed storage. This provides:

* Zero configuration required
* Fast query performance
* Automatic scaling
* No additional costs

## Bring Your Own Bucket (BYOB)

<Note>
  BYOB is available on **Enterprise plans** only. Contact us to upgrade.
</Note>

Enterprise customers can connect their own S3-compatible storage for complete data control:

### Benefits

* **Data Ownership** — Your data stays in your infrastructure
* **Cost Control** — Pay storage costs directly to your provider
* **Compliance** — Meet data residency requirements
* **Flexibility** — Use AWS S3, MinIO, Cloudflare R2, or other S3-compatible services

### Supported Storage

| Provider            | Compatibility |
| ------------------- | ------------- |
| AWS S3              | Full support  |
| MinIO               | Full support  |
| Cloudflare R2       | Full support  |
| Other S3-compatible | Contact us    |

### Configuration

To enable BYOB:

1. Contact your administrator to upgrade to Enterprise
2. Provide your S3 bucket credentials
3. AstroBee configures the connection
4. All new data syncs to your bucket

<Warning>
  BYOB configuration requires coordination with the AstroBee team. Contact [support@astrobee.ai](mailto:support@astrobee.ai) to get started.
</Warning>

## Data Processing

Regardless of warehouse configuration:

* All queries run in secure, isolated environments
* Data is encrypted in transit (TLS 1.3) and at rest (AES-256)
* Query results are cached temporarily for performance

## Next Steps

<CardGroup>
  <Card title="Integrations" icon="plug" href="/settings/integrations">
    Configure third-party API integrations
  </Card>

  <Card title="Security Overview" icon="shield-check" href="/security/overview">
    Learn about data security and compliance
  </Card>
</CardGroup>


# Support
Source: https://docs.astrobee.ai/support

Get help with AstroBee

Need help? We're here for you.

## Contact Us

<CardGroup>
  <Card title="General Support" icon="envelope" href="mailto:hello@astrobee.ai">
    [hello@astrobee.ai](mailto:hello@astrobee.ai)
  </Card>

  <Card title="Security Issues" icon="shield" href="mailto:security@astrobee.ai">
    [security@astrobee.ai](mailto:security@astrobee.ai)
  </Card>
</CardGroup>

## In-App Support

Click **Contact Us** in the sidebar to send us a message directly from AstroBee.

## Resources

<CardGroup>
  <Card title="Documentation" icon="book" href="/">
    Browse the full documentation
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get started in minutes
  </Card>

  <Card title="Trust Center" icon="shield-check" href="https://trust.astrobee.ai/">
    Security and compliance information
  </Card>

  <Card title="Blog" icon="newspaper" href="https://blog.astrobee.ai/">
    Latest news and tutorials
  </Card>
</CardGroup>

## Report an Issue

If you encounter a problem:

1. Click **Report Issue** on any chat response to flag incorrect answers
2. Email [support@astrobee.ai](mailto:support@astrobee.ai) for technical issues
3. Check the [Troubleshooting](/troubleshooting) guide for common solutions

## Feature Requests

Have an idea for AstroBee? We'd love to hear it:

* Email [hello@astrobee.ai](mailto:hello@astrobee.ai) with your suggestion
* Include your use case and how the feature would help

## Enterprise Support

Enterprise customers receive:

* Dedicated support channel
* Priority response times
* Technical account management

Contact [sales@astrobee.ai](mailto:sales@astrobee.ai) to learn more.


# Troubleshooting
Source: https://docs.astrobee.ai/troubleshooting

Solutions to common issues

## Data Sources

### Connection Failed

**Symptom**: Data source shows "Connection Failed" status.

**Solutions**:

1. **OAuth expired**: Re-authenticate by clicking the data source and selecting "Reconnect"
2. **Permissions changed**: Verify your account still has access to the data
3. **Service outage**: Check if the external service (Google Sheets, Salesforce, etc.) is operational

### Sync Not Updating

**Symptom**: Data appears stale or sync timestamp hasn't changed.

**Solutions**:

1. **Check sync schedule**: Syncs run automatically based on Fivetran configuration
2. **Manual refresh**: Click the refresh icon on the data source card
3. **Large dataset**: Initial syncs may take longer for large datasets

### File Upload Errors

**Symptom**: CSV or Excel file fails to upload.

**Solutions**:

1. **File size**: Maximum file size is 100MB
2. **Format issues**: Ensure CSV uses UTF-8 encoding
3. **Column headers**: First row must contain column names
4. **Special characters**: Remove or escape special characters in headers

## Data Layer

### AI Generation Stuck

**Symptom**: Data layer generation appears to hang.

**Solutions**:

1. **Wait**: Complex schemas may take 1-2 minutes to analyze
2. **Refresh**: Reload the page and check if generation completed
3. **Simplify**: Try with fewer tables selected initially

### Relationships Not Detected

**Symptom**: Expected linkages between tables don't appear.

**Solutions**:

1. **Column naming**: Ensure foreign key columns follow patterns like `customer_id`
2. **Data types**: Matching columns should have compatible types
3. **Manual creation**: Add relationships manually in the Linkages tab

### Publish Failed

**Symptom**: Unable to publish data layer changes.

**Solutions**:

1. **Validation errors**: Check the Review panel for specific issues
2. **Empty entities**: Entities must have at least one property
3. **Circular references**: Check for relationship loops

## Analytics Chat

### Query Returns No Results

**Symptom**: Question returns empty results unexpectedly.

**Solutions**:

1. **Check filters**: Review the SQL in the Logic view for unexpected WHERE clauses
2. **Date ranges**: Ensure your data includes the time period you're asking about
3. **Entity names**: Use terms that match your data layer definitions

### SQL Error

**Symptom**: Query fails with a SQL error message.

**Solutions**:

1. **Data type mismatch**: Check if you're comparing incompatible types
2. **Null values**: Some aggregations fail with null data
3. **Rephrase question**: Try asking the question differently

### Slow Queries

**Symptom**: Queries take a long time to return.

**Solutions**:

1. **Large datasets**: Consider adding date filters to your questions
2. **Complex aggregations**: Break down complex questions into simpler parts
3. **Data layer optimization**: Review entity definitions for unnecessary joins

## MCP Integration

### Server Not Connecting

**Symptom**: Claude Desktop or VS Code can't connect to AstroBee MCP.

**Solutions**:

1. **API Key**: Verify your API key is correct in Settings > Integrations
2. **URL format**: Ensure you're using the correct server URL from the MCP tab
3. **Firewall**: Check if your network allows outbound connections to AstroBee

### Tools Not Available

**Symptom**: AstroBee tools don't appear in your AI assistant.

**Solutions**:

1. **Restart**: Restart Claude Desktop or VS Code after configuration changes
2. **Config syntax**: Verify your `claude_desktop_config.json` or `settings.json` syntax
3. **Server status**: Check that the MCP server URL is accessible

## Account & Settings

### Can't Invite Team Members

**Symptom**: Invite button doesn't work or invites aren't received.

**Solutions**:

1. **Email delivery**: Check spam/junk folders
2. **Permissions**: Verify you have admin access to the organization
3. **Domain restrictions**: Some organizations restrict external invites

### OAuth Provider Not Working

**Symptom**: Custom OAuth integration fails.

**Solutions**:

1. **Redirect URI**: Ensure the callback URL is correctly configured
2. **Credentials**: Verify client ID and secret are correct
3. **Scopes**: Check that required scopes are enabled

## Still Need Help?

<CardGroup>
  <Card title="Contact Support" icon="envelope" href="mailto:support@astrobee.ai">
    Email our support team
  </Card>

  <Card title="In-App Support" icon="message" href="/support">
    Send a message from within AstroBee
  </Card>
</CardGroup>


# Connect Claude Desktop
Source: https://docs.astrobee.ai/tutorials/connect-claude-desktop

Use AstroBee data layers from Claude Desktop

Query your data layers directly from Claude Desktop using AstroBee's MCP server.

## Prerequisites

* [Claude Desktop](https://claude.ai/download) installed
* An AstroBee account with at least one published data layer
* An API key from Settings > Integrations

## Step 1: Get Your MCP Configuration

1. Navigate to **Settings** > **MCP** in AstroBee
2. Copy the server configuration JSON

## Step 2: Configure Claude Desktop

1. Open Claude Desktop settings
2. Navigate to the MCP servers configuration
3. Add the AstroBee server configuration:

```json theme={null}
{
  "mcpServers": {
    "astrobee": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote", "https://app.astrobee.ai/api/mcp"],
      "env": {
        "ASTROBEE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

4. Replace `your-api-key-here` with your actual API key
5. Restart Claude Desktop

## Step 3: Verify Connection

1. Start a new conversation in Claude Desktop
2. Ask Claude to list available data layers
3. Claude should show your published AstroBee data layers

## Using AstroBee Tools

Once connected, you can:

* **Query data**: "How many customers placed orders last month?"
* **Explore schema**: "What entities are in my data layer?"
* **Generate insights**: "Analyze trends in my sales data"

## Troubleshooting

<Accordion title="Tools not appearing">
  1. Restart Claude Desktop after configuration changes
  2. Verify your API key is valid
  3. Check that you have at least one published data layer
</Accordion>

<Accordion title="Connection errors">
  1. Ensure your network can reach app.astrobee.ai
  2. Check that your API key has the correct permissions
  3. Try regenerating your API key
</Accordion>

## Next Steps

<CardGroup>
  <Card title="VS Code Setup" icon="code" href="/tutorials/connect-vscode">
    Connect AstroBee to VS Code
  </Card>

  <Card title="MCP Reference" icon="plug" href="/features/mcp">
    Learn more about MCP integration
  </Card>
</CardGroup>


# Connect VS Code
Source: https://docs.astrobee.ai/tutorials/connect-vscode

Use AstroBee data layers from VS Code

Query your data layers directly from VS Code using AstroBee's MCP server with Claude Code or other MCP-compatible extensions.

## Prerequisites

* [VS Code](https://code.visualstudio.com/) installed
* [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) or another MCP-compatible extension
* An AstroBee account with at least one published data layer
* An API key from Settings > Integrations

## Step 1: Get Your MCP Configuration

1. Navigate to **Settings** > **MCP** in AstroBee
2. Copy the server configuration

## Step 2: Configure VS Code

### For Claude Code Extension

1. Open VS Code settings (Cmd/Ctrl + ,)
2. Search for "Claude Code MCP"
3. Add the AstroBee server to your MCP servers configuration:

```json theme={null}
{
  "claude-code.mcpServers": {
    "astrobee": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote", "https://app.astrobee.ai/api/mcp"],
      "env": {
        "ASTROBEE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

4. Replace `your-api-key-here` with your actual API key
5. Reload VS Code

## Step 3: Verify Connection

1. Open the Claude Code panel in VS Code
2. Ask Claude to list available data layers
3. Claude should show your published AstroBee data layers

## Using AstroBee in VS Code

With AstroBee connected, you can:

* **Query data while coding**: "What's the schema for the customers table?"
* **Generate code from data**: "Write a function to calculate customer lifetime value based on my orders data"
* **Validate assumptions**: "How many products have null prices in my dataset?"

## Example Workflow

```
You: What are the top 5 customers by total order value?

Claude: [Uses AstroBee MCP to query your data layer]

Based on your data, the top 5 customers by total order value are:
1. Acme Corp - $125,000
2. GlobalTech - $98,500
...
```

## Troubleshooting

<Accordion title="Extension not detecting MCP server">
  1. Verify your settings.json syntax is correct
  2. Reload VS Code window (Cmd/Ctrl + Shift + P > "Reload Window")
  3. Check the extension output panel for errors
</Accordion>

<Accordion title="Authentication errors">
  1. Regenerate your API key in AstroBee Settings > Integrations
  2. Update the key in your VS Code settings
  3. Reload VS Code
</Accordion>

## Next Steps

<CardGroup>
  <Card title="Claude Desktop Setup" icon="desktop" href="/tutorials/connect-claude-desktop">
    Connect AstroBee to Claude Desktop
  </Card>

  <Card title="MCP Reference" icon="plug" href="/features/mcp">
    Learn more about MCP integration
  </Card>
</CardGroup>