Datasources and credentials

Connection kinds, credential identity and revisions, connection tests, and datasource limits.

A datasource names a connection within a workspace. Each credential holds one database identity and its complete connection configuration. A datasource can have several credentials of the same backend kind.

For the setup procedure, use Connect a datasource. The catalog, joins and business knowledge are covered in Context.

Datasource identity

Field	Meaning
`id`	Datasource record identity. Recreating a deleted datasource creates a new identity.
`slug`	Workspace-unique identifier used to select the datasource. It stays fixed when editing the connection or display name.
`name`	Optional display name. Changing it does not replace credentials.
`kind`	Backend type, such as `postgres` or `bigquery`. A replacement credential must keep this kind.
`configured`	At least one credential exists. This does not establish connectivity or permission to query.
`revision`	Datasource metadata revision, separate from each credential's revision.

A datasource can exist without a credential. Reading its metadata does not test the connection.

Connection kinds and fields

Every connection object includes kind. The table gives the other required fields and optional fields with their defaults. All 13 kinds also accept embedded, which defaults to false. For provider setup steps, use the connection guides.

Provider and `kind`	Required fields	Optional fields
PostgreSQL, `postgres`	`connection_string`	`schema`
MySQL, `mysql2`	`connection_string`	None
SQL Server, `mssql`	`authentication`, described below	None
SAP HANA, `hana`	`connection_string`	`schema`
BigQuery, `bigquery`	`service_account_key`: service-account JSON object or JSON string	None
Snowflake, `snowflake`	`user`, `warehouse`, `account`	`database`, `database_schema`
Redshift, `redshift`	`host`, `database`, `username`, `password`	`port` = `5439`, `ssl` = `true`, `schema`
ClickHouse, `clickhouse`	`host`, `user`, `password`	`secure` = `true`, `verify` = `true`
DuckDB / MotherDuck, `duckdb`	`connection_string`	None
Managed files, `files`	None	`path` = `files`
Databricks, `databricks`	`host`, `http_path`, `access_token`, `catalog`	`schema`
MongoDB Atlas SQL, `mongodb`	`uri`, `database`, `user`, `password`	None
SSH tunnel, `ssh`	`host`, `username`, `private_key`, `dst_addr`, `dst_port`, `db`, described below	`port` = `22`

Optional fields without a listed default are unset. Unknown fields are rejected. Connection strings and credential values are used literally; a value beginning with $ is not a reference to another stored secret.

SQL Server authentication

The authentication object supports two forms:

`authentication.type`	Fields
`connection_string`	Required: `connection_string`.
`active_directory_service_principal`	Required: `server`, `database`, `client_id`, `tenant_id`, `client_secret`. Optional: `port` = `1433`.

Provider boundaries

SSH: db requires client, name, user and password; db_schema defaults to public. The gateway accepts PostgreSQL (postgres) and MySQL (mysql or mysql2) clients. SSH currently uses a Querio-managed key. Although the connection schema requires private_key, that field does not select an independent per-connection key.
Snowflake: authentication uses a Querio-managed key pair. An independent private key per credential is not configurable.
MongoDB: this connection uses MongoDB Atlas SQL through its ODBC driver. It is not a general MongoDB wire-protocol connection.
DuckDB: in-memory and MotherDuck connections are accepted. Local .duckdb database files are rejected; use managed files for uploaded tables.
Managed files: path is a directory beneath the configured context root, defaulting to files. It must stay inside that root. The engine exposes Parquet files in that directory as tables named after the files. It does not treat arbitrary workspace files as tables.

Credential identity and replacement

Credential reads return only ID, name, revision, Default status and timestamps. They never return connection values, passwords, tokens or keys. The connection form cannot refill saved values, so a replacement must supply the complete configuration, including unchanged secrets. A password-only patch will not work.

Replacement keeps the credential ID and its assignments, and advances its revision. API replacement and deletion require the current expectedRevision (an integer of at least 1). A stale revision returns 409; reload credential metadata before retrying.

The first credential on a newly configured datasource is initially assigned to Everyone. Later credentials need explicit assignments. Check the effective assignments before adding another credential for the same people.

Default is the stable credential targeted by the older single-connection editing form. Renaming it does not change its identity or Default status. Neither Default nor the credential name selects the identity used for queries.

Query selection

To query, a person needs datasource permission and exactly one distinct authorized credential for that datasource. Admins need both too; management permission does not grant credential use. Several assignments to the same credential still count as one.

Authorized credentials	Result
None	`403`: no authorized credential.
Exactly one	Use that credential.
More than one distinct credential	`409`: ambiguous credentials; no credential is chosen.

Missing datasource permission returns 403 before credential selection. Introspection uses the same authorized credential. See Users, roles and groups for grant paths, denials and exact errors.

New Explore selection

New Explore starts with a person's saved default datasources that are still visible to them. If none remain visible, it selects the first visible datasource; if none are visible, it selects nothing. Use Select datasource to check or change the selection before asking a question.

This selection does not grant query access or choose a credential. There is currently no Favorite datasources setting in the app to change saved defaults. See Ask and refine a question for the selection task.

Connection tests and introspection

Check	What it establishes
Test supplied connection details	Opens a connection and pings it without saving those details. It does not test a user's saved credential assignments.
Save through the connection form	Tests the supplied complete configuration before saving. A failed test does not save the replacement.
Test a saved datasource	Resolves the caller's credential and pings that connection.
Introspect	Reads schema, table and column metadata visible to the selected database identity.
Run a query as the intended user	Exercises that user's datasource access, credential selection and the requested database operation.

The API's testConnection option defaults to false. Creating a datasource through the API without a test does not establish that it works. Test responses give success or failure and elapsed time, without returning the supplied configuration or native driver error details.

A successful ping does not establish table access or query success. Check the expected schemas and tables after introspection: one schema can succeed while another fails. Then run a small query as the intended user to check the actual database privileges.

Limits and deletion

Item	Limit or behavior
Slug	1-120 ASCII characters. Starts with a letter or digit; remaining characters may also include `.`, `_` or `-`.
Display name	Optional; when present, 1-120 characters after trimming.
Credential name	Required; 1-120 characters after trimming, unique within the datasource.
Complete connection	At most 1 MiB of JSON encoded as UTF-8. Must match the datasource kind.
Delete credential	Requires its current revision. Removes that credential and its use assignments; keeps the datasource and its datasource permissions.
Delete Default credential	Blocked while other credentials remain: `The default credential cannot be deleted while other credentials exist`.
Delete datasource	Removes the datasource, its credentials and associated access assignments. Keeps catalogs and workspace files.

Deleting a datasource does not delete the upstream database. Existing Explores that depend on it can no longer query through that connection. Catalog and workspace files remain, but recreating the datasource requires a new connection setup and access check.

On this page