Queries

A query is a saved LakeSail SQL definition with a name, description, team sharing, and a catalog binding. SQL jobs can reference it instead of storing their own SQL snapshot.

This page covers creating, sharing, and using queries in jobs. See Defining jobs for the full job workflow.

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 not required to save a query. A job needs a compute profile on a ready cluster when it runs.

The query stores SQL and catalog metadata only. When a job runs it, the job's data access applies. For S3-backed tables, the underlying data must be in the compute profile's network workspace bucket.

What a query holds

A query holds:

• Name and description for identification and context in list views.
• Query text, the SQL itself (up to 8191 characters; see Limits & quotas).
• 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).
• Team whose members can use the query according to their team roles.

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.
   • Team: the team that can use the query. LakeSail selects it automatically when you belong to one team.
   • Description (optional): usage notes, owner, or other context.
   • 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 and is available through its assigned team and any organization roles that grant access.

Change the team

1. Open the query.
2. Click Edit Query.
3. Select a different Team.
4. Save.

Changing the team replaces the previous team assignment. The selected team must also have access to any catalogs attached to the query.

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, without a job redeploy. That is the point of the reference: one canonical SQL, used in many places.

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 affects the next run of any job that references it. To keep a job on its current SQL:

• Pair the query with a job using the Snapshot source (pins the SQL to the job at save time).
• Or duplicate the query before editing it, then point the job to the new copy when it is ready.

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.
• Shared SQL: share a query with teams that need to use the same SQL in their jobs.
• Stable job source: use a snapshot when a job must not change with later query edits.

API reference

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