Query Runner

Query Runner

Query Runner executes SQL against your connected database services directly from Collate. The API is split across five resources: running and stopping queries, the admin-level connection configuration for a service, per-team and per-user credential overrides on top of that admin config, and saved queries.

Execution

Trigger a query, stop a running one, and fetch results.

Configs

The admin-level connection configuration for a service.

Saved Queries

Save, list, update, and execute reusable queries.

Team Configs

Team-level credential overrides on top of the admin config.

User Configs

Per-user credential overrides, token refresh, and accessible role/database/schema lookups.

Resource Model

Concept	Base Path	Who manages it
Execution	`/v1/collate/apps/queryRunner`	Any user with query access
Admin Config	`/v1/queryRunner/configs`	Workspace admin, one config per service
Team Config	`/v1/queryRunner/team-configs`	Team owner or admin, one config per team per service
User Config	`/v1/queryRunner/user-configs`	Each user, one config per service
Saved Query	`/v1/queryRunner/savedQueries`	The owning user only

A query normally uses the calling user’s config for that service. If no user config exists, it falls back to an available connected team config. Setting preferTeam=true skips the user config and resolves a team config. Setting teamId selects a specific team. Both config types sit on top of an admin config that defines the service type and which fields users are allowed to override (userConfigurableFields, such as role, database, schema, warehouse, or dataset).

Common Behavior

Authenticate every request with a bearer token. Admin, team, and user config secrets are masked in responses to ordinary users and must be resubmitted or explicitly preserved on update. Authorized bot callers can receive decrypted credentials, so avoid logging those responses. For setup details, see Authentication.

​Query Runner