Appearance

Queries ​

A query is a saved SQL statement — named, described, team-shared, and bound to a catalog. Queries are the SQL equivalent of a versioned library: you save them once, then run them from jobs (batch) or sessions (interactive).

This page covers creating, running, and referencing queries. For the interactive runtime that executes queries live, see Sessions. For batch execution, see Defining jobs.

Prerequisites ​

  • A catalog is recommended — queries bind to one so the SQL doesn't have to qualify the catalog/schema path on every reference. See Connect a catalog. You can save a query without a catalog by entering a schema name directly, but a managed catalog is the typical choice.
  • A cluster is required to run a query (interactively via a session, or in batch via a job). It is not required to save one.

What a query holds ​

A query is a small, focused object:

  • Name and description — for identification and context in list views.
  • Query text — the SQL itself (up to 8191 characters).
  • Catalog binding — either a catalog ID (references a managed catalog's provider config) or a catalog schema name to use directly.
  • Tags — free-form labels for categorization (etl, sales, daily).
  • Teams — teams that can use the query, assigned via Share with team.

Queries are authored by a member and owned by the member who created them. Sharing with teams is how other people get access.

Create a query ​

  1. Open Queries in the sidebar and click Create query.
  2. Fill in:
    • Name — e.g. Daily Sales Summary.
    • Description (optional) — usage notes, owner, anything future-you will want.
    • Catalog — pick from your managed catalogs, or leave empty and enter a Schema name.
    • Query text — the SQL.
    • Tags (optional) — e.g. etl, daily.
  3. Click Save.

The query appears in the Queries list. By default only you can see it; share it with a team to grant access to others.

Share with a team ​

  1. Open the query.
  2. Click Share (or the team assignment control).
  3. Add one or more teams. Everyone in those teams can run and reference the query.
  4. Remove a team the same way to revoke access.

A query can belong to any number of teams. Permissions are additive — belonging to any shared team is enough to use the query.

Run a query interactively ​

Queries don't execute on their own — they run inside a session on a cluster. The typical flow:

  1. Create a session on the cluster you want to use (see Sessions).
  2. From the query's detail page, click Run.
  3. Pick the session.
  4. Results stream back to the UI or your connected client.

A session can run as many queries as you like, one after another. Warm sessions return results in seconds.

Reference a query from a job ​

SQL jobs can reference a saved query instead of inlining SQL. This is how you keep the SQL in one place and have multiple jobs (different schedules, different compute configs) share it.

  1. Create a SQL job (see Defining jobs).
  2. For the source, pick Saved query and choose the query.
  3. Save the job.

Every run of the job resolves the query text at dispatch time. If you edit the query, the next run picks up the new SQL automatically — no job redeploy needed. That's the point of the reference: one canonical SQL, many places it's used.

If you want a job to be frozen against a specific SQL snapshot (no drift when the query changes), use the Snapshot source variant instead.

Edit and delete ​

Editing a query immediately affects any sessions that re-run it and the next run of any job that references it. If that's too aggressive for your workflow:

  • Pair the query with a job using the Snapshot source (pins the SQL to the job at save time).
  • Or, duplicate the query before experimenting — give the copy a different name and iterate on it.

Deleting a query fails if any job references it. Remove or redirect those jobs first.

Common patterns ​

  • One query, many schedules — one Daily Sales query referenced by an hourly job (for freshness) and a nightly job (for history). Edit the SQL once, both pick it up.
  • Parameterized exploration — keep a library of tagged queries (#exploration, #revenue) that analysts run interactively in sessions. No job needed.
  • Batch-from-BI-tool-output — prototype a query in a session, save it once it's right, then reference it from a job for scheduled runs.

API reference ​

  • Queries — CreateQuery, UpdateQuery, DeleteQuery, team sharing.