Saved and scheduled queries
Saved and Scheduled are two modes of the History tab. A saved query is a BigQuery Studio saved query, so you and your team see the same one in both tools. A scheduled query runs on a BigQuery schedule, and editing one changes only the fields you touched.
Open Query history and switch the modes in the tab header: Queries | Saved | Scheduled | Optimize. Queries and Optimize are described in Query history and History Optimize. This page covers Saved and Scheduled. You can also run Saved queries or Scheduled queries from the command palette.
Saved queries
A saved query is a BigQuery Studio saved query. Querylab.io stores it the way Studio does, in a repository in your own project with one file, content.sql, and a commit for every save. A query you save here shows up in BigQuery Studio, and one saved in Studio shows up here. Anyone with access to the project can open it. There are no sharing settings in the app; share a query in BigQuery Studio. A querylab-folder label that an earlier version put on the Dataform repository is ignored.
Saving
- ⌘ S (Ctrl S on Windows and Linux) in a query tab. A tab that is not saved yet opens the Save query dialog. A tab that is already saved commits a new version.
- Save as… in the editor menu saves the SQL of a saved tab as a new query.
The Save query dialog asks for a name and shows where the query goes, for example Saves to analytics-prod · us-central1. Change picks another project or location. It warns you when a saved query with that name already exists in the location.
A saved tab shows a mark in the tab list. A dot on the mark means the SQL has changed since the last save.
When someone else saved first
A save names the version it was based on. If somebody saved a newer version in the meantime, nothing is overwritten, and a dialog says Changed since you opened it, with who saved and when, if that is known. Choose one:
- Open theirs opens their version in a new tab.
- Save mine as a copy saves your SQL as a new query.
- Overwrite saves your SQL on top of theirs. Their version stays in the version list.
Saved mode
Saved lists the saved queries of one project, the most recently saved first. The project is the one picked in the History header. Rows load per location, and a counter shows how many locations are read. A location that fails is listed with the reason (permission denied, the API is turned off, or a missing scope) instead of being left out quietly.
- Mine / Everyone. Mine shows the queries whose latest version you saved. Everyone shows all of them.
- Search matches names and SQL. Reading the SQL happens in the background; the list says how far it got and how many queries could not be read.
- Region limits the list to one location.
- The detail pane shows the SQL, the versions with who saved each and when, and the actions: Open, Copy SQL, rename, Open in BigQuery Studio and delete. Open this version on an older version opens that SQL in a tab. Deleting a saved query deletes its versions too.
A query that an older Querylab.io saved before it used Studio’s layout is marked Not in BigQuery Studio yet. It still opens here. Save it once and Studio shows it.
Scheduled queries
A scheduled query is a BigQuery scheduled query, run by the Data Transfer Service. Scheduled mode lists the schedules of the project, from any tool, with their status: OK, Failing, Paused or Running. Filter by All, Failing or Paused, or search by name.
The detail pane shows when it runs (in UTC), where the results go, the location, the next run, who it runs as, whether it emails you when a run fails, and the SQL. The actions are Run now, Edit, Pause or Resume, Backfill and delete. Recent runs lists the last runs with their state, and Open this run in History shows the job of a run in Queries mode.
Deleting a schedule stops it and deletes its run history.
Creating and editing a schedule
Choose Schedule Query in a query tab’s menu to open the schedule panel with that tab’s SQL. Edit on a schedule opens the same panel with the schedule’s own SQL. The panel has four steps.
- When. Hourly, daily, weekly, monthly or a custom schedule such as
every 6 hoursorevery mon 09:00. Runs must be at least 5 minutes apart. BigQuery schedules only in UTC, so for a daily, weekly or monthly schedule you pick the time in a time zone (yours by default) and the panel shows both, for exampleRuns every day at 09:00 Europe/Berlin (07:00 UTC). The schedule does not follow summer time: when your clocks change, the run moves in local time, and the panel says by how much. It lists the next runs in your time zone. - Where results go. A dataset, a table name and what to do if the table exists: append, write only if empty, or overwrite. A table name can use
{run_date}(YYYYMMDD) or{run_time|"%Y%m%d"}. An optional partition column must be a DATE or TIMESTAMP column of the results. A query that returns rows needs a destination table, and without one every run fails, so the panel does not let you create it. A script, DML or DDL statement has no destination. Overwrite warns when the table has policy tags, because each run replaces the table and removes them. - If a run fails. Email you.
- Run as. Run as me opens Google’s consent page and asks for the code it shows. Run as a service account takes the account’s email; the account needs permission to run the query and write the results.
The schedule runs in the location of the destination dataset, or of the table the statement changes when there is no destination. The panel asks you to pick a location only when it cannot work that out, for example for a script.
Editing a schedule sends only the fields you changed, and needs no new credential. Everything else on the schedule, including settings Querylab.io has no field for, stays as it is. The panel says Nothing has changed when there is nothing to send. A schedule whose settings Querylab.io cannot read stays as it is, and the panel offers to replace it with a new one.
For what a scheduled query is in BigQuery, the @run_time and @run_date parameters and how they bill, see Scheduled queries in BigQuery.