Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs - basic table editing (#63601)

Jeff Bruemmer4deefb87b3be
diff --git a/docs/actions/introduction.md b/docs/actions/introduction.md
index 2c51b2a05e1..08e33941634 100644
--- a/docs/actions/introduction.md
+++ b/docs/actions/introduction.md
@@ -22,11 +22,13 @@ Here are a few ideas for what you can do with actions:
Actions must be added to a [model](../data-modeling/models.md), but actions only run on the raw tables that back those models (so actions will never edit your [model definition](../data-modeling/models.md#edit-a-models-query)).
+If you're an admin who just wants to edit data in your tables, check out [Editable table data](../data-modeling/editable-tables.md).
+
## Enabling actions for a database
For actions to work, you'll first need to do the following two things:
-1. **Enable model actions for the database connection**. To enable actions for a database connection, admins should click on the **gear** icon in the upper right and navigate to **Admin settings** > **Databases**, then click on the database you want to create actions for. On the right side of the connection settings form, toggle the **Model actions** option. For actions to work, the database user account (the account you're using to connect to the database) must have [write permissions](../databases/users-roles-privileges.md#privileges-to-enable-actions). And for now, actions are only supported on PostgreSQL and MySQL databases.
+1. **Enable model actions for the database connection**. To enable actions for a database connection, admins should click on the **gear** icon in the upper right and navigate to **Admin settings** > **Databases**, then click on the database you want to create actions for. On the right side of the connection settings form, toggle the **Model actions** option. For actions to work, the database user account (the account you're using to connect to the database) must have [write permissions](../databases/users-roles-privileges.md#privileges-to-enable-actions-and-editable-table-data). And for now, actions are only supported on PostgreSQL and MySQL databases.
2. **Create at least one model from that database.** Actions are associated with models, so you'll need to have created (or have access to) at least one model before you can start creating actions.
## Who can use actions
diff --git a/docs/data-modeling/editable-tables.md b/docs/data-modeling/editable-tables.md
new file mode 100644
index 00000000000..7a25360705e
--- /dev/null
+++ b/docs/data-modeling/editable-tables.md
@@ -0,0 +1,85 @@
+---
+title: Editable tables
+summary: Admins can create, update, and delete data in tables right in Metabase.
+---
+
+# Editable tables
+
+{% plans-blockquote.html feature="Editable table data" %}
+
+Admins can enable editable table data in Metabase.
+
+![Edit table](./images/edit-table.png)
+
+## Setting up editable tables
+
+_Currently, editable table data is only available for PostgreSQL and MySQL._
+
+To set up table editing, admins can:
+
+1. Click the **gear** icon in the top right.
+2. Select **Admin settings**.
+3. Click **Databases**.
+4. Select your database.
+5. Toggle on **Editable table data**.
+
+For this to work, Metabase's connection to your database must support writing back to its tables. See [privileges to enable actions and editable table data](../databases/users-roles-privileges.md#privileges-to-enable-actions-and-editable-table-data).
+
+## Update or delete records in a table
+
+To update or delete records in a table:
+
+1. Open the left sidebar.
+2. In the Data section, click **Databases**.
+3. Hover over the table you want to edit and click the **Pencil** icon.
+4. Edit rows in the table just like you would in a spreadsheet.
+
+Depending on the data in the column, Metabase may show a list of values to choose from. If you need to add an option to that list, simply type out the option and add it (you may need to refresh the browser for the new option to show up in the list).
+
+![Add option](./images/add-option.png)
+
+To remove an option from the list of values, you'll need to change any records with that value to a different value.
+
+## Create a new record
+
+![Create new record](./images/create-new-record.png)
+
+You can add a row to a table by clicking **+ New record** in the top right of the table. Fill out the fields. Metabase will respect field constraints, so if a field is required, Metabase will prevent you from saving the record until you fill in the required field.
+
+## Delete a record
+
+To delete a record, check the box next to the record you want to delete and click **Delete**. Deletion is permanent. Metabase will prompt you to confirm the deletion.
+
+You can also select multiple rows and delete them all at once (nervous sweating).
+
+If you try to delete a row that has foreign key references from other tables, your database may prevent the deletion to maintain referential integrity. You'll see an error message like "Other rows refer to this row so it cannot be deleted." To delete these rows, you'll either need to remove the referencing rows first, or change the foreign key constraints in your database.
+
+## Metabase enforces type constraints
+
+- You can't edit sequential primary keys.
+- If you try to add a value of a different type (like changing the number 13579 to the string "Wizard"), Metabase won't allow it.
+
+## Editable table data vs. actions
+
+Metabase offers two ways to modify data in your database: **editable table data** and [actions](../actions/introduction.md).
+
+### When to use editable table data
+
+Use editable table data to:
+
+- Do data maintenance or cleanup.
+- Modify many records at once.
+- Get direct access to all table data.
+- Do one-off data corrections.
+
+You need to be an admin to edit tables directly.
+
+### When to use actions
+
+Use actions to:
+
+- Create custom forms.
+- Give non-admins the ability to modify data.
+- Add a button to a dashboard to trigger a form or query.
+
+See [actions](../actions/introduction.md).
\ No newline at end of file
diff --git a/docs/data-modeling/images/add-option.png b/docs/data-modeling/images/add-option.png
new file mode 100644
index 00000000000..e5b3facfadd
Binary files /dev/null and b/docs/data-modeling/images/add-option.png differ
diff --git a/docs/data-modeling/images/create-new-record.png b/docs/data-modeling/images/create-new-record.png
new file mode 100644
index 00000000000..782cd0f175a
Binary files /dev/null and b/docs/data-modeling/images/create-new-record.png differ
diff --git a/docs/data-modeling/images/edit-table.png b/docs/data-modeling/images/edit-table.png
new file mode 100644
index 00000000000..25843d4c281
Binary files /dev/null and b/docs/data-modeling/images/edit-table.png differ
diff --git a/docs/databases/connections/mysql.md b/docs/databases/connections/mysql.md
index a85fc52e3c3..5277ca8c967 100644
--- a/docs/databases/connections/mysql.md
+++ b/docs/databases/connections/mysql.md
@@ -189,6 +189,14 @@ Turn this setting on to allow [actions](../../actions/introduction.md) from mode
We'll create tables with model data and refresh them on a schedule you define. To enable [model persistence](../../data-modeling/model-persistence.md), you need to grant this connection's credentials read and write permissions on a schema Metabase provides.
+## Editable table data
+
+Turn this setting **ON** to enable editing of table data directly within Metabase. When enabled, Admins can create, update, and delete records in your tables through Metabase's interface.
+
+Your database connection will need Write permissions to enable this feature. Meaning: the database user account that you use to connect Metabase to your database must have appropriate privileges to modify data in the tables you want to make editable.
+
+See [privileges](../users-roles-privileges.md).
+
## Database routing
With database routing, an admin can build a question once using one database, and the question will run its query against a different database with the same schema depending on who is viewing the question.
diff --git a/docs/databases/connections/postgresql.md b/docs/databases/connections/postgresql.md
index ae729db24ef..df9f101eaa0 100644
--- a/docs/databases/connections/postgresql.md
+++ b/docs/databases/connections/postgresql.md
@@ -194,6 +194,14 @@ Turn this setting on to allow [actions](../../actions/introduction.md) from mode
We'll create tables with model data and refresh them on a schedule you define. To enable [model persistence](../../data-modeling/model-persistence.md), you need to grant this connection's credentials read and write permissions on a schema Metabase provides.
+## Editable table data
+
+Turn this setting **ON** to enable editing of table data directly within Metabase. When enabled, Admins can create, update, and delete records in your tables through Metabase's interface.
+
+Your database connection will need Write permissions to enable this feature. Meaning: the database user account that you use to connect Metabase to your database must have appropriate privileges to modify data in the tables you want to make editable.
+
+See [privileges](../users-roles-privileges.md).
+
## Database routing
With database routing, an admin can build a question once using one database, and the question will run its query against a different database with the same schema depending on who is viewing the question.
diff --git a/docs/databases/users-roles-privileges.md b/docs/databases/users-roles-privileges.md
index 4b8c25bc29f..e1236438d01 100644
--- a/docs/databases/users-roles-privileges.md
+++ b/docs/databases/users-roles-privileges.md
@@ -7,7 +7,7 @@ title: Database users, roles, and privileges
We recommend creating a `metabase` database user with the following database roles:
- [`analytics` for read access](#minimum-database-privileges) to any schemas or tables used for analysis.
-- Optional [`metabase_actions` for write access](#privileges-to-enable-actions) to tables used for Metabase actions.
+- Optional [`metabase_actions` for write access](#privileges-to-enable-actions-and-editable-table-data) to tables used for Metabase actions.
- Optional [`metabase_model_persistence` for write access](#privileges-to-enable-model-persistence) to the schema used for Metabase model persistence.
- Optional [`metabase_transforms` for write access](#privileges-to-enable-transforms) to the schema used for Metabase transforms.
@@ -87,25 +87,25 @@ GRANT ALL PRIVILEGES ON "database" TO metabase;
This is a good option if you're connecting to a local database for development or testing.
-## Privileges to enable actions
+## Privileges to enable actions and editable table data
-[Actions](../actions/introduction.md) let Metabase write back to specific tables in your database.
+Both [actions](../actions/introduction.md) and the [editable table data](../data-modeling/editable-tables.md) let Metabase write back to specific tables in your database.
-In addition to the [minimum database privileges](#minimum-database-privileges), you'll need to grant write access to any tables used with actions:
+In addition to the [minimum database privileges](#minimum-database-privileges), you'll need to grant write access to any tables you want to be able to write to.
-- Create a new role called `metabase_actions`.
-- Give the role `INSERT`, `UPDATE`, and `DELETE` privileges to any tables used with Metabase actions.
-- Give the `metabase_actions` role to the `metabase` user.
+- Create a new role called `metabase_writer`.
+- Give the role `INSERT`, `UPDATE`, and `DELETE` privileges to the relevant tables.
+- Give the `metabase_writer` role to the `metabase` user.
```sql
--- Create a role to bundle database privileges for Metabase actions.
-CREATE ROLE metabase_actions WITH LOGIN;
+-- Create a role to bundle database privileges for Metabase writing to your database.
+CREATE ROLE metabase_writer WITH LOGIN;
--- Grant write privileges to the TABLE used with Metabase actions.
-GRANT INSERT, UPDATE, DELETE ON "your_table" IN SCHEMA "your_schema" TO metabase_actions;
+-- Grant write privileges to the TABLE
+GRANT INSERT, UPDATE, DELETE ON "your_table" IN SCHEMA "your_schema" TO metabase_writer;
-- Grant role to the metabase user.
-GRANT metabase_actions TO metabase;
+GRANT metabase_writer TO metabase;
```
## Privileges to enable model persistence
@@ -183,7 +183,7 @@ Let's say you have customers named Tangerine and Lemon:
- Create roles to bundle privileges specific to each customer's use case. For example:
- `tangerine_queries` to bundle read privileges for people to query and create stored procedures against the Tangerine schema.
- `lemon_queries` to bundle read privileges for people to query tables in the Lemon schema.
- - `lemon_actions` to bundle the write privileges needed to create [actions](#privileges-to-enable-actions) on a Lemonade table in the Lemon schema.
+ - `lemon_actions` to bundle the write privileges needed to create [actions](#privileges-to-enable-actions-and-editable-table-data) on a Lemonade table in the Lemon schema.
- Add each user to their respective roles.
```sql