# When tables change

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

```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](https://api.inseeq.com/docs/automations.md#polling-with-cron). 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](https://api.inseeq.com/llms.txt) or the [contract](https://api.inseeq.com/openapi.json).
