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

  • table

    The table to delete from. It must be a table your account may write, and one that permits deletion

    Required: Yes
  • FILTER(…)

    Chooses the records to delete. It takes every condition FILTER takes, including IN [ … ], BETWEEN and OR. WHERE(…) means the same, and a condition's value can be a variable or, in a FOR loop, a column of the current row

    Required: Yes

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
ErrorWhat happenedHow to recover
HTQL-2011 REMOVE requires a FILTER clauseThe statement has no FILTERAdd FILTER(condition)
HTQL-3010 Table is read-onlyThe table is a platform table or is not one your account may writeRemove from a table your account may write
HTQL-3004 Table is protected and cannot be deletedThe table does not permit deletionChoose another table
HTQL-4013A column in the FILTER does not exist on the tableCheck 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 EDGE also 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 _name is 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.