Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion databases/bigtable.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Each changed row is one request, and its cells change together. A save has no tr
| Cell set to NULL, or **Remove Field** | The cell set to `null` in the `PUT`, which deletes every version of it |
| Deleted row | `DELETE` on the key |

A new row needs a `_key` and at least one cell. **Duplicate** and pasted rows copy every cell but `_key`, which shows DEFAULT until you type a key. The grid offers only the columns the rows on the page hold, so an empty table shows `_key` alone: write a table's first row, or a cell under a column the page does not show, with `INSERT` or `PUT` in the request editor. The column family must already exist, and the **DDL** tab of the Structure tab lists them under `columnFamilies`.
A new row needs a `_key` and at least one cell. **Duplicate** copies every cell but `_key`, which shows DEFAULT until you type a key. A pasted row keeps the `_key` it carries. The grid offers only the columns the rows on the page hold, so an empty table shows `_key` alone: write a table's first row, or a cell under a column the page does not show, with `INSERT` or `PUT` in the request editor. The column family must already exist, and the **DDL** tab of the Structure tab lists them under `columnFamilies`.

An existing row's key cannot change. The save is refused, so duplicate the row, give the copy the new key, and delete the old one. **Set DEFAULT** in the row inspector is refused on an existing row too; set the cell to NULL to delete it, or enter a value. Text typed into a cell or into `_key` that starts with `b64:` is written as the bytes its base64 decodes to. Cells are written with the server's clock.

Expand Down
12 changes: 6 additions & 6 deletions features/change-tracking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,9 +55,9 @@ On MongoDB, Firestore and the Firebase Realtime Database a document can lack a f
## Adding and deleting rows

- **Add Row** (`Cmd+Shift+N`), the **+** button, or **Edit > Add Row**. The row appears at the bottom with the cursor in its first writable cell. A UUID primary key the server does not fill gets a new UUID, and the cursor skips it. Later edits fold into the INSERT rather than queueing as updates.
- **Duplicate Row** (`Cmd+Shift+D`) on the right-click menu copies a row and resets its primary key and its identity columns to `DEFAULT`, so the database assigns new ones. A UUID primary key the server does not fill gets a new UUID instead.
- **Duplicate Row** (`Cmd+Shift+D`) on the right-click menu copies every selected row, as one undo step, and resets each copy's primary key and identity columns to `DEFAULT`, so the database assigns new ones. A UUID primary key the server does not fill gets a new UUID instead.
- **Delete**: select rows by their row numbers (`Shift`-click for a range, `Cmd`-click for separate rows), or cells in them, and press `Delete` or `Forward Delete`. They stay visible with a strikethrough, and saving asks "Delete 5 rows from customers?" before they go.
- **Paste** (`Cmd+V`, or **Paste** on the right-click menu) inserts copied rows as new rows, with a new UUID in a UUID primary key the server does not fill.
- **Paste** (`Cmd+V`, or **Paste** on the right-click menu) inserts copied rows as new rows. A primary key the server fills, such as an identity, `AUTO_INCREMENT`, a default that calls a function like `nextval()` or `gen_random_uuid()`, or SQLite's `INTEGER PRIMARY KEY`, is reset to `DEFAULT`, a UUID primary key the server does not fill gets a new UUID per row, and any other pasted key is kept. Quoted CSV fields keep their spaces.
- **Fill Column** on the header right-click menu writes one value, NULL, or a new UUID or UUIDv7 per row into every loaded row. It is absent on primary key columns and on columns the server owns.

A new row starts at `DEFAULT` in every column the server fills in. That covers a column with a default expression, and an identity or `AUTO_INCREMENT` column, which carries no default of its own. The INSERT leaves those columns out, so the server assigns them.
Expand Down Expand Up @@ -112,15 +112,15 @@ Press `Cmd+S`, or click the toolbar checkmark. Values go out as bound parameters

A table without a primary key is matched on every original column value instead, with `IS NULL` for the nulls. On MySQL, MariaDB, TiDB and OceanBase a `FLOAT`, `DOUBLE` or `JSON` column is compared through `CONCAT()`, because the text those types read back as does not compare equal to the value it came from. On SQL Server an `ntext`, `text`, `image`, `xml`, `geography`, `geometry` or `hierarchyid` column is compared through `CAST`, because `=` refuses those types or the value reads back as the type's bytes. A `sql_variant` column cannot be compared without losing its type, so a save that has to match one stops and names it.

On an engine with transactions, the statements run inside one, so a failure rolls the whole save back and the table is left as it was. Without them, the statements that ran before the failure stand. Either way a failed save reports **Save Failed** with the server's message and keeps the queue intact, so correct the value and save again. A save that succeeds clears the queue, clears undo, and reloads the grid at the same place, with its sort, value filter and selection. In a query tab the reload runs the statement behind the result again, not the one at the caret.
While a save runs, its tab takes no edits, and Undo and **Discard Changes…** wait for it to finish. On an engine with transactions, the statements run inside one, so a failure rolls the whole save back and the table is left as it was. Without them, the statements that ran before the failure stand. Either way a failed save reports **Save Failed** with the server's message and keeps the queue intact, so correct the value and save again. A save that succeeds clears the queue, clears undo, and reloads the grid at the same place, with its sort, value filter and selection. In a query tab the reload runs the statement behind the result again, not the one at the caret.

Every queued change has to become a statement before anything is sent. When a change cannot, such as a new Redis row with no key, or it holds a value the driver cannot write, such as an edit to one leaf of an Elasticsearch nested array or to a column the server owns made before the table's structure finished loading, or a pgvector value whose length differs from its `vector(n)` column, the save stops, names what it could not write, and keeps the whole queue. Undo that change, or make it with a query, then save again.

The statements a driver writes for itself, as SQL Server, Oracle and ClickHouse do, are read before anything is sent. An `UPDATE` or `DELETE` with no `WHERE` of its own would reach every row of the table, so the save stops, names the table, and keeps the whole queue. A `WHERE` inside a comment, a string or a subquery does not count.

Each generated SQL statement is held to the number of rows it was written for. On a table with no primary key, two identical rows cannot be told apart, so a statement meant for one of them matches both; the save stops there and reports what happened instead of rewriting the other row.

Such a statement is held to the other end too. Finding fewer rows than it was written for means the row it meant to write is no longer there, so the save rolls back and keeps the edits rather than reporting a success that wrote nothing. Engines whose drivers report no real count, ClickHouse among them, are not held to it. Of the drivers that write their own statements, SQL Server and Oracle are held to it on a table without a primary key, and MongoDB and Redis are not. SQL Server bounds that match with `TOP (1)` and Oracle with `ROWNUM = 1`, so of two identical rows they write one.
Such a statement is held to the other end too. Finding fewer rows than it was written for means the row it meant to write is no longer there, so the save rolls back and keeps the edits rather than reporting a success that wrote nothing. An edit keyed on a primary key is held to it on PostgreSQL, CockroachDB, Redshift, KingbaseES, SQLite, libSQL, Turso and DuckDB, whose count is the rows the statement matched: a row deleted or rekeyed since it was read, hidden from updates by a row-level security policy, or skipped by a trigger stops the save. An edit that follows a delete in the same save is not, since the delete can cascade to its row. MySQL, MariaDB, TiDB and OceanBase count only rows whose value changed, so there an edit is not held to it. Engines whose drivers report no real count, ClickHouse among them, are not held to it. Of the drivers that write their own statements, SQL Server and Oracle are held to it on a table without a primary key, and MongoDB and Redis are not. SQL Server bounds that match with `TOP (1)` and Oracle with `ROWNUM = 1`, so of two identical rows they write one.

Where a count cannot hold a statement to its row, the row is looked up right before the statement runs instead: on ClickHouse, Snowflake and Trino for every edit and delete, and on Dameng for a table without a primary key. Finding no row, or more than the change was made on, stops the save before anything is written and keeps the queue. A ClickHouse statement is also limited to the data part its row was found in, and the row is checked after it runs. See [ClickHouse](/databases/clickhouse#running-queries).

Expand All @@ -132,7 +132,7 @@ To drop the whole queue, choose **File > Discard Changes…** and confirm; a sta

## Undo and redo

`Cmd+Z` and `Cmd+Shift+Z`. Focus decides what they act on: text in the SQL editor, queued changes in the grid. Deleting several rows undoes as one step. The stacks are per tab, and a save clears them.
`Cmd+Z` and `Cmd+Shift+Z`. Focus decides what they act on: text in the SQL editor, queued changes in the grid. Deleting several rows undoes as one step. **Undo Delete** on the right-click menu is a step of its own, so `Cmd+Z` after it deletes the rows again and the next `Cmd+Z` restores them. The stacks are per tab, and a save clears them.

## Restoring a save

Expand All @@ -150,7 +150,7 @@ Every row is planned against the table as it stands now, and the sheet says what
| Row no longer exists | Nothing left to write to |
| A row with this key already exists | Something took the deleted row's key |

**Restore** writes the changes back the way any other save does: through the same [safe mode](/features/safe-mode) prompt, in one transaction where the engine has them, and into query history. The restore is itself restorable.
**Restore** reads each edited or inserted row again inside the write. A row someone changed after the sheet listed it stops the restore before anything is written, so open the sheet again to see what is left. It then writes the changes back the way any other save does: through the same [safe mode](/features/safe-mode) prompt, in one transaction where the engine has them, and into query history. The restore is itself restorable.

<Warning>
Only what TablePro wrote is restored. Triggers that fired, audit rows they wrote, and rows a cascade deleted stay as they are.
Expand Down
Loading