REMOVE
Delete the records you choose.
Syntax
Give the table, then a FILTER.
REMOVE table FILTER(condition, …)
REMOVE EDGE IN name_edge FILTER(condition, …)Parameters and arguments
tableThe table to delete from. It must be a table your account may write, and one that permits deletion
Required: YesFILTER(…)Chooses the records to delete. It takes every condition FILTER takes, including
Required: YesIN [ … ],BETWEENandOR.WHERE(…)means the same, and a condition's value can be a variable or, in a FOR loop, a column of the current row
Examples
Delete the stock records marked as drafts.
Return type and behaviour
REMOVE answers that it succeeded, with the number of records deleted in deletedCount. A FILTER that matches no record is not an error: the answer carries a notice, "REMOVE matched 0 rows", so you can see that nothing was deleted.
Errors and exceptions
| Error | What happened | How to recover |
|---|---|---|
HTQL-2011 REMOVE requires a FILTER clause | The statement has no FILTER | Add FILTER(condition) |
HTQL-3010 Table is read-only | The table is a platform table or is not one your account may write | Remove from a table your account may write |
HTQL-3004 Table is protected and cannot be deleted | The table does not permit deletion | Choose another table |
HTQL-4013 | A column in the FILTER does not exist on the table | Check the column's name |
Placement and context
REMOVE is a statement of its own. It can also appear in the body of a FOR loop.
Limitations
- Not supported: a REMOVE without a FILTER. To empty a whole table, TRUNCATE is the statement; it has its own entry.
REMOVE EDGEalso needs a FILTER. A FILTER that matches no edge is not an error: the answer carries the notice "REMOVE EDGE matched 0 rows".- A table name that starts with an underscore is not read as a table:
REMOVE _nameis read as a function call. - A table can be marked as one that does not permit deletion. REMOVE on such a table is refused.
Permissions and security
REMOVE runs as the caller, confined by row-level security to the caller's own account. A platform table such as orders refuses a direct write with HTQL-3010: its records change through the statement that owns them, such as INSERT ORDER {…}. A content table is written by a caller who holds the content area, and a link collection by the account that owns it.
A column classified above the caller's clearance cannot be written by that caller. The statement is refused, never partly applied.
Best practices
- Run the same FILTER in a LOOKUP first, and check the rows it returns.
- Filter on a unique column, such as an identifier, to delete one record.
- Check the notice in the answer: a count of zero means nothing was deleted.