DocsConnect your first data source
Walk through creating a BigQuery connection, importing the schema, running a scan, and enabling the data source for AI queries.
This guide walks you through connecting a database to Kaelio, importing its schema, running an AI-powered scan, and asking your first question. The example uses BigQuery, but the steps are similar for other databases like PostgreSQL, Snowflake, MySQL, and more.
By the end you'll have a fully configured data source with AI-generated metadata, ready for natural language querying.
Before you start
Make sure you have the following:
- Admin access to your Kaelio instance
- Database credentials — for BigQuery, you need a Google Cloud service account JSON key file and at least one dataset ID
You can create a service account and download the key file from the Google Cloud Console under IAM & Admin > Service Accounts. The account needs BigQuery Data Viewer and BigQuery Job User roles at minimum.
Step 1: Create the connection
Navigate to Data Sources and click the Add button to open the connection gallery.
Browse or search for BigQuery and select it. Each platform has its own setup form with fields specific to that connection type.
Enter a Name for the connection (for example, "Production Analytics") and an optional Description.
Upload your service account JSON key file by dragging it onto the credentials area or clicking to browse.
Click Fetch next to the Datasets field. Kaelio reads available datasets from your project. Select the ones you want to connect.
Click Test Connection to verify that Kaelio can reach your database with the provided credentials. A success indicator confirms everything works.
Click Create to save the connection.
The required fields vary by platform. Here are a few common examples:
| Platform | Key fields |
|---|---|
| BigQuery | Credentials JSON file, Dataset IDs |
| PostgreSQL | Host, Port, Database, Username, Password |
| Snowflake | Account, Warehouse, Role, Database, Schema |
| MySQL | Host, Port, Database, Username, Password |
Step 2: Schema discovery
After you create a connection, Kaelio automatically runs a discovery scan. This imports your database structure — table names, column names, data types, primary keys, and foreign key relationships — without any AI processing.
A progress bar appears at the top of the Schema tab while the scan runs. Discovery typically completes in under a minute for most databases.
When it finishes, you'll see a message indicating the number of tables and columns discovered.
Step 3: Review the schema
Open the Schema tab to browse what was imported.
- Table view (default) — a searchable list of tables showing column counts, data types, and constraints
- Graph view — an interactive diagram where tables are nodes and foreign key relationships are edges. Drag to pan, scroll to zoom, and click nodes to inspect them.
You can enable or disable individual tables to control which ones the AI can access. Toggle a table off if it contains irrelevant data or if you want to reduce noise during queries.
Disabling tables you don't need makes scans faster and helps the AI focus on the data that matters. You can always re-enable a table later.
Step 4: Run the AI scan
Click Analyze in the toolbar to start a full AI-powered scan. This goes beyond discovery and adds intelligent metadata to your schema.
The scan runs through several phases, each shown in the progress bar:
- Structural sync — detects any changes since the last scan (new tables, modified columns)
- AI descriptions — generates human-readable descriptions for every table and column
- Semantic embeddings — computes vector embeddings so the AI understands your data's meaning, not just its names
- Relationship detection — discovers relationships between tables beyond what foreign keys define
- Insights generation — creates around 20 starter questions about your data with pre-computed answers
You'll receive an email when the scan completes.
The first scan takes the longest because it processes every table. Subsequent scans are incremental and only process changes.
Step 5: Enable for chat and start querying
Go to the Settings tab on your data source.
Toggle Enabled for Chat on. This lets the AI use this data source when answering questions.
Optionally set a Scan schedule (Daily, Weekly, or Monthly) to keep metadata up to date as your database evolves.
Navigate to Research in the sidebar and ask your first question in natural language — for example, "What were the top 10 products by revenue last month?"
Kaelio translates your question into SQL, executes it against your database, and returns the results as a table or chart.
Next steps
Schema Management
Browse tables, visualize relationships, and manage your schema
Connection Settings
Configure scan schedules, generate AI insights, and manage connections
SQL Security Policies
Control which tables, columns, and rows each user can access
Dashboards
Build interactive visualizations from your connected data