Data Connections
Data connections let you securely link external data sources to your Roundtable workspaces. Once a connection is configured, the AI can query your data directly using the built-in data tools (query_bigquery, query_snowflake, query_databricks).
What Are Connections?
A connection is a set of credentials for an external data source, stored at the organization level. Connections are created once and can then be attached to one or more workspaces. This means you manage credentials in a single place rather than copying secrets into every workspace.
Roundtable supports four connection types:
| Type | Description | Used By |
|---|---|---|
| BigQuery | Google Cloud data warehouse | query_bigquery tool |
| Snowflake | Cloud data platform | query_snowflake tool |
| Databricks | Unified analytics / lakehouse | query_databricks tool |
| API Key | Generic key-value secret | Custom tools and integrations |
How Connections Work
Credential Storage
All connection credentials are stored in GCP Secret Manager, Google Cloud's managed secrets service. Credentials are encrypted at rest and in transit, and access is controlled through IAM policies. Roundtable never stores raw credentials in its application database.
Injection into Workspaces
When a workspace pod starts (or when a connection is attached to a running workspace), Roundtable injects the connection's credentials as environment variables inside the workspace's isolated container. The AI tools read these environment variables to authenticate with the external data source.
This architecture means:
- Credentials never appear in chat messages or conversation history.
- Workspace members cannot view raw credentials through the UI (only admins can manage connections).
- Each workspace pod gets only the credentials for its attached connections.
The envPrefix System
Each connection type uses a predictable environment variable prefix to expose its credentials to tools. This ensures tools can discover and use credentials automatically.
| Connection Type | Env Prefix | Example Variables |
|---|---|---|
| BigQuery | BQ_ | BQ_PROJECT_ID, BQ_DATASET, BQ_SERVICE_ACCOUNT_KEY |
| Snowflake | SF_ | SF_ACCOUNT, SF_WAREHOUSE, SF_DATABASE, SF_SCHEMA, SF_USERNAME, SF_PASSWORD |
| Databricks | DBX_ | DBX_HOST, DBX_HTTP_PATH, DBX_CATALOG, DBX_TOKEN |
| API Key | APIKEY_ | APIKEY_<NAME> (user-defined) |
When a tool like query_bigquery runs, it looks for variables with the BQ_ prefix. If they exist, the tool connects to BigQuery using those values. If they don't, the tool returns an error explaining that a BigQuery connection is needed.
The envPrefix system is an implementation detail you generally don't need to think about. It's documented here for transparency and for advanced users who write custom integrations via run_code or shell_exec.
Managing Connections
Creating a Connection
- Navigate to your organization's Settings page.
- Open the Connections tab.
- Click Add Connection.
- Select the connection type (BigQuery, Snowflake, Databricks, or API Key).
- Fill in the required fields (these vary by type — see the setup guides below).
- Click Save.
Attaching a Connection to a Workspace
- Open the target workspace.
- Go to Settings → Connections.
- Select the connection you want to attach from the dropdown.
- Click Save.
The connection's credentials are injected into the workspace immediately. The AI can now use the corresponding data tool.
Removing a Connection from a Workspace
- Open the workspace's Settings → Connections.
- Click the remove icon next to the connection.
- Click Save.
The environment variables are removed from the workspace pod. The AI will no longer be able to query that data source from this workspace.
Removing a connection from a workspace does not delete the connection itself. The connection remains available in your org settings and can be attached to other workspaces.
Connection Testing
Every connection type supports a Test Connection button during setup. This sends a lightweight query to the data source to verify that:
- The credentials are valid.
- The network path is reachable.
- The specified database, dataset, or catalog exists.
- The account has sufficient permissions.
Always test your connection before attaching it to a workspace. A failed test will display a specific error message to help you troubleshoot.
Setup Guides
For step-by-step instructions on configuring each connection type, see: