Menu

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 happenedSignalYour query answers
A table was addedtables.changed, in addedNothing changes
A table was removedtables.changed, in removed404 table_not_published. GET /v1/tables/{name} answers 404 not_found
A column was removed or renamedtables.changed, in changed400 bigquery_error, and message names the column
A column was addedtables.changed, in changedNothing changes, unless you use select *
A column changed typetables.changed, in changedIt 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

JSON
{
  "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. changed means a top-level column name or type moved. It does not say which one: read GET /v1/tables/{name} and compare it with what you saved.
  • It reaches a webhook subscribed to tables.changed, and it stays in GET /v1/events?type=tables.changed for 30 days.
  • Its order against data.refreshed is not promised. It often arrives first, during a build, and data_version can move again before the build ends. Read the current state from GET /v1/status, not from the order of events.

What to do

Before anything goes wrong:

  1. Keep your SQL in one place, such as a queries/ folder with one file per metric.
  2. Know which tables each query reads.
  3. Name your columns in the SQL. Avoid select *, so a new column changes nothing.
  4. Keep a copy of each table's columns from GET /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.

  1. If no table you read is in removed or changed, do nothing.
  2. For each table you read in changed, read GET /v1/tables/{name}, compare its columns with your copy, and read its description again.
  3. Run each affected query once with a small max_rows, and check the columns and value types.
  4. If something broke, tell a person which metric is affected and why.
  5. Update your saved copy.

When a table goes:

  1. Stop showing that metric. Show "This data is no longer available" with the table's name. Never show a blank chart or a zero.
  2. Keep the rest of the page working. One failed query must not take down the others.
  3. 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.
  4. Look at GET /v1/tables for 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_version moves 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.

Back to the rules or the contract.

When tables change · inseeq Data API