When tables changeBeta
The published tables are not fixed. A table can be added, removed or change its columns, with no notice in advance. Build so that a change shows up as a clear message to a person, not a wrong number.
What you will see
| What happened | Signal | Your query answers |
|---|---|---|
| A table was added | tables.changed, in added | Nothing changes |
| A table was removed | tables.changed, in removed | 404 table_not_published. GET /v1/tables/{name} answers 404 not_found |
| A column was removed or renamed | tables.changed, in changed | 400 bigquery_error, and message names the column |
| A column was added | tables.changed, in changed | Nothing changes, unless you use select * |
| A column changed type | tables.changed, in changed | It may still run, and the JSON value type can change: a number can become a string |
table_not_published is also what a mistyped table name gets, and a name with a dataset in it. The API does not tell a table that went from one that never existed. Check GET /v1/tables. If the table is still listed, wait a minute and try once more. If it is not, it is gone.
What fires nothing. tables.changed watches table names and top-level column names and types. A change in a table's description, caveats or grain fires no event, and neither does a change inside a nested field. Numbers can change meaning with no signal, so read a table's docs again whenever you touch a query on it.
The event
{
"id": "evt_8a7b6c5d4e3f20110f1e2d3c4b5a6978",
"type": "tables.changed",
"timestamp": "2026-11-06T06:40:02Z",
"data": {
"data_version": "9f2c41ab77d0e310",
"added": ["example_new"],
"removed": ["example_old"],
"changed": ["example_daily"]
}
}
- The lists hold table names only, sorted.
changedmeans a top-level column name or type moved. It does not say which one: readGET /v1/tables/{name}and compare it with what you saved. - It reaches a webhook subscribed to
tables.changed, and it stays inGET /v1/events?type=tables.changedfor 30 days. - Its order against
data.refreshedis not promised. It often arrives first, during a build, anddata_versioncan move again before the build ends. Read the current state fromGET /v1/status, not from the order of events.
What to do
Before anything goes wrong:
- Keep your SQL in one place, such as a
queries/folder with one file per metric. - Know which tables each query reads.
- Name your columns in the SQL. Avoid
select *, so a new column changes nothing. - Keep a copy of each table's
columnsfromGET /v1/tables/{name}, to compare later.
When tables.changed arrives: code can do steps 1 and 4 alone. The rest needs a person or an agent session, so have your automation say what needs looking at, not try to repair itself.
- If no table you read is in
removedorchanged, do nothing. - For each table you read in
changed, readGET /v1/tables/{name}, compare its columns with your copy, and read its description again. - Run each affected query once with a small
max_rows, and check the columns and value types. - If something broke, tell a person which metric is affected and why.
- Update your saved copy.
When a table goes:
- Stop showing that metric. Show "This data is no longer available" with the table's name. Never show a blank chart or a zero.
- Keep the rest of the page working. One failed query must not take down the others.
- Tell the user which metric went. They can ask inseeq whether it moved or was retired, through their usual channel or by asking their assistant to tell inseeq.
- Look at
GET /v1/tablesfor a replacement, and read its docs. Do not swap the table on your own. A table with a similar name can have a different grain, and the numbers would be wrong without any error. Propose it to the user.
Do not retry these
bigquery_error fails the same way every time, and so does table_not_published once you have made the one check above. Retrying spends calls and hides the problem. Fail visibly, and fix the SQL or the page.
Without a webhook
A cron job gets the same event from GET /v1/events?type=tables.changed. See polling. An app with no events at all can compare GET /v1/tables with its saved list on each deploy or once a day.
What stays stable
- An open cursor keeps reading its original result, even after a refresh or a table change. Each page is the same snapshot.
data_versionmoves within about 5 minutes of a successful refresh, or of a change to the list of tables or their columns. Cached answers from the old version then stop being served. A failed build does not move it.