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

# Quickstart

> Set up your first connection, build a semantic model, and ask your first AI-powered question in minutes.

## Prerequisites

Before you begin, make sure you have:

* A Vigilos account at [app.vigilos.co](https://app.vigilos.co)
* A running database (PostgreSQL, ClickHouse, Snowflake, Amazon Redshift, or Google BigQuery) with data you want to analyze
* Network access from Vigilos to your database (the database must be reachable over the internet or via a private network)

## Step 1: Create a Connection

<Steps>
  <Step title="Navigate to Connections">
    Open the sidebar and click **Connections** under the Data section. Click the **New Connection** button.
  </Step>

  <Step title="Fill in connection details">
    Enter the following information:

    | Field        | Description                                                                                                                              |
    | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
    | **Name**     | A friendly name for this connection (e.g., "Production ClickHouse")                                                                      |
    | **Type**     | Select your database type (PostgreSQL, ClickHouse, Snowflake, Redshift, or BigQuery)                                                     |
    | **Host**     | Database hostname or IP address                                                                                                          |
    | **Port**     | Database port (e.g., 5432 for PostgreSQL, 8443 for ClickHouse). Snowflake, Redshift, and BigQuery use account-based connection patterns. |
    | **Database** | Name of the database to connect to                                                                                                       |
    | **Username** | Database user with read access                                                                                                           |
    | **Password** | Database password                                                                                                                        |
    | **SSL/TLS**  | Enable for encrypted connections (recommended)                                                                                           |
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify Vigilos can reach your database. You should see a green success indicator. If the test fails, check your network settings and credentials.
  </Step>

  <Step title="Save">
    Click **Save** to store the connection. Your credentials are encrypted with AES-256 before being stored.
  </Step>
</Steps>

## Step 2: Build a Semantic Model

A semantic model maps your raw database tables to business-friendly concepts that the AI agent can understand.

<Steps>
  <Step title="Create a new model">
    Navigate to **Semantic Models** in the sidebar and click **New Model**. Give it a name (e.g., "E-Commerce Analytics") and select the connection you just created.
  </Step>

  <Step title="Add entities">
    Click **Add Entity** and use the schema browser to select tables from your database. Each table becomes an entity - a business object like "Orders", "Customers", or "Products".

    <Tip>
      Vigilos can automatically explore your database and suggest relevant context, descriptions, and column configurations. Use the **Auto-Explore** feature to get started quickly.
    </Tip>
  </Step>

  <Step title="Configure columns">
    For each entity, configure the columns:

    * **Rename** columns to business-friendly names (e.g., `cust_nm` → "Customer Name")
    * **Set the role**: dimension (for grouping), measure (for aggregation), or key (for joining)
    * **Add descriptions** so the AI understands what each column represents
    * **Create computed columns** for derived values like JSON extraction or date formatting
    * **Set display formats** for currencies, percentages, and numbers
  </Step>

  <Step title="Define relationships">
    Connect entities by defining relationships between them:

    * Select the **from** entity and column (the foreign key side)
    * Select the **to** entity and column (the primary key side)
    * Choose the **cardinality** (one-to-one, one-to-many, many-to-one, many-to-many)
    * Click **Validate** to sample your data and verify the relationship integrity
  </Step>

  <Step title="Create measures">
    Define reusable calculations that the AI and visual builder can reference:

    * **Simple measures**: `SUM(amount)`, `COUNT(DISTINCT customer_id)`, `AVG(price)`
    * **Compound measures**: Reference other measures, e.g., `Total Revenue / Total Orders`
    * Set the **data type** (number, currency, percent) and display format
  </Step>
</Steps>

## Step 3: Ask Your First Question

<Steps>
  <Step title="Open Ask AI">
    Click **Ask AI** in the sidebar to open the AI chat interface.
  </Step>

  <Step title="Select your semantic model">
    Choose the semantic model you just created from the model selector dropdown.
  </Step>

  <Step title="Ask a question">
    Type a natural language question, for example:

    * "What were the top 10 products by revenue last month?"
    * "Show me daily active users over the past 30 days"
    * "What is the average order value by country?"

    The agent will:

    1. Explore your schema and understand the relevant tables and columns
    2. Map your question to business concepts in your semantic model
    3. Generate the right query configuration or advanced SQL
    4. Execute the query and return results with an interactive visualization and explanation
  </Step>

  <Step title="Save as an Insight">
    If you want to keep the result, click **Save as Insight**. Saved insights can be added to dashboards, included in reports, or shared with your team.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Semantic Models" icon="diagram-project" href="/concepts/semantic-models">
    Learn more about entities, relationships, and measures.
  </Card>

  <Card title="Dashboards" icon="objects-column" href="/features/dashboards">
    Build interactive dashboards from your saved insights.
  </Card>

  <Card title="Slack Bot" icon="slack" href="/integrations/slack-bot">
    Ask questions directly from Slack.
  </Card>

  <Card title="Automations" icon="clock" href="/integrations/automations">
    Schedule reports to be delivered automatically.
  </Card>
</CardGroup>