Prerequisites
Before you begin, make sure you have:- A Vigilos account at 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
Navigate to Connections
Open the sidebar and click Connections under the Data section. Click the New Connection button.
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) |
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 2: Build a Semantic Model
A semantic model maps your raw database tables to business-friendly concepts that the AI agent can understand.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.
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”.
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
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
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 3: Ask Your First Question
Select your semantic model
Choose the semantic model you just created from the model selector dropdown.
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?”
- Explore your schema and understand the relevant tables and columns
- Map your question to business concepts in your semantic model
- Generate the right query configuration or advanced SQL
- Execute the query and return results with an interactive visualization and explanation
Next Steps
Semantic Models
Learn more about entities, relationships, and measures.
Dashboards
Build interactive dashboards from your saved insights.
Slack Bot
Ask questions directly from Slack.
Automations
Schedule reports to be delivered automatically.