DELETE

On this page

The DELETE statement deletes rows from a table.

Required privileges

The user must have the DELETE and SELECT privileges on the table.

Synopsis

Parameters

Success responses

Successful DELETE statements return one of the following:

Disk space usage after deletes

Deleting a row does not immediately free up the disk space. This is due to the fact that CockroachDB retains the ability to query tables historically.

If disk usage is a concern, the solution is to reduce the time-to-live (TTL) for the zone by setting gc.ttlseconds to a lower value, which will cause garbage collection to clean up deleted objects (rows, tables) more frequently.

Select performance on deleted rows

Queries that scan across tables that have lots of deleted rows will have to scan over deletions that have not yet been garbage collected. Certain database usage patterns that frequently scan over and delete lots of rows will want to reduce the time-to-live values to clean up deleted rows more frequently.

Sorting the output of deletes

To sort the output of a DELETE statement, use:

> SELECT ... FROM [DELETE ...] ORDER BY ...

For an example, see Sort and return deleted rows.

For more information about ordering query results in general, see Ordering Query Results.

Delete performance on large data sets

If you are deleting a large amount of data using iterative DELETE ... LIMIT statements, you are likely to see a drop in performance for each subsequent DELETE statement.

For an explanation of why this happens, and for instructions showing how to iteratively delete rows in constant time, see Why are my deletes getting slower over time?.

Force index selection for deletes

By using the explicit index annotation (also known as "index hinting"), you can override CockroachDB's index selection and use a specific index for deleting rows of a named table.

The syntax to force a specific index for a delete is:

> DELETE FROM table@my_idx;

This is equivalent to the longer expression:

> DELETE FROM table@{FORCE_INDEX=my_idx};

To view how the index hint modifies the query plan that CockroachDB follows for deleting rows, use an EXPLAIN statement. To see all indexes available on a table, use SHOW INDEXES.

Examples

Delete all rows

You can delete all rows from a table by not including a WHERE clause in your DELETE statement.

> DELETE FROM account_details;

DELETE 7

Delete specific rows

When deleting specific rows from a table, the most important decision you make is which columns to use in your WHERE clause. When making that choice, consider the potential impact of using columns with the Primary Key/Unique constraints (both of which enforce uniqueness) versus those that are not unique.

Delete rows using Primary Key/unique columns

Using columns with the Primary Key or Unique constraints to delete rows ensures your statement is unambiguous—no two rows contain the same column value, so it's less likely to delete data unintentionally.

In this example, account_id is our primary key and we want to delete the row where it equals 1. Because we're positive no other rows have that value in the account_id column, there's no risk of accidentally removing another row.

> DELETE FROM account_details WHERE account_id = 1 RETURNING *;

 account_id | balance | account_type
------------+---------+--------------
          1 |   32000 | Savings
(1 row)

DELETE 1

Delete rows using non-unique columns

Deleting rows using non-unique columns removes every row that returns TRUE for the WHERE clause's a_expr. This can easily result in deleting data you didn't intend to.

> DELETE FROM account_details WHERE balance = 30000 RETURNING *;

 account_id | balance | account_type
------------+---------+--------------
          2 |   30000 | Checking
          3 |   30000 | Savings
(2 rows)

DELETE 2

The example statement deleted two rows, which might be unexpected.

Return deleted rows

To see which rows your statement deleted, include the RETURNING clause to retrieve them using the columns you specify.

Use all columns

By specifying *, you retrieve all columns of the delete rows.

> DELETE FROM account_details WHERE balance < 23000 RETURNING *;

 account_id | balance | account_type
------------+---------+--------------
          4 |   22000 | Savings
(1 row)

DELETE 1

Use specific columns

To retrieve specific columns, name them in the RETURNING clause.

> DELETE FROM account_details WHERE account_id = 5 RETURNING account_id, account_type;

 account_id | account_type
------------+--------------
          5 | Checking
(1 row)

DELETE 1

Change column labels

When RETURNING specific columns, you can change their labels using AS.

> DELETE FROM account_details WHERE balance < 24500 RETURNING account_id, balance AS final_balance;

 account_id | final_balance 
------------+---------------
          6 |         23500
(1 row)

DELETE 1

Sort and return deleted rows

To sort and return deleted rows, use a statement like the following:

> SELECT * FROM [DELETE FROM account_details RETURNING *] ORDER BY account_id;

 account_id | balance  | account_type
------------+----------+--------------
          7 | 79493.51 | Checking
          8 | 40761.66 | Savings
          9 |  2111.67 | Checking
         10 | 59173.15 | Savings
(4 rows)

See also

• INSERT
• UPDATE
• UPSERT
• TRUNCATE
• ALTER TABLE
• DROP TABLE
• DROP DATABASE
• Other SQL Statements
• Limiting Query Results

Was this helpful?