# 5. Removing Messages

## sow_delete

### Description

In AMPS, there are three different ways to remove records from the SOW. The first method is to construct a `publish` message that matches the message to be removed, with the `Command` field set to be a `sow_delete` message. This has the net effect of causing AMPS recreate the `SowKey` for the particular message, then look up the `SowKey` message in the SOW and finally remove it.

The other method to remove messages from the SOW is to construct a `sow_delete` message and pass in a comma separated list of `SowKey`s in the message header which will cause all of the messages to be removed from the SOW Topic.

The third way to remove records from the SOW is similar to the manner in which a `sow` query command with a `filter` is performed. In this case, instead of returning the results of the `sow` command, those records that match the filter will be deleted from the SOW.

The `sow_delete` command is also used to acknowledge messages from a queue. With this form of `sow_delete`, a client sends one or more bookmarks (as a comma-delimited list) that specify the messages to acknowledge.

### Header Fields

Table 5.1 contains the header fields supported by a `sow_delete`.

Field | Description
--- | ---
    Command
| Command to be executed. Value: `sow_delete`.
    Topic
| The SOW Topic from which to delete the messages(s).
`AckType` | Acknowledgment type for the given command. Value is a comma separated list of one or more of the following: `none`, `received`, `processed`, `persisted`, `completed` and `stats`.
`CommandId` | If specified with an AMPS command requesting an `ack`, all requested acknowledgment messages will contain the `CommandId` in the acknowledgment message header.
`SowKeys` | A comma separated list of unique ids to be deleted. AMPS uses these ids to locate and remove the specified records. Notice that these values are the internal ID used by AMPS – the SowKey – and not the value of a field in the message. To use the values of fields in the message to locate the records to remove, use a `Filter` or `Data`.
`Filter` | Content filter expression. See the Content Filtering chapter in the AMPS User Guide for more information on using content filters. When provided, AMPS removes the matching records.
`Data` | Message data that identifies the record to be removed. When provided, AMPS uses this `Data` to look up the record that would be updated were this command a publish. AMPS then deletes that record.
`Bookmark` | Processed when the `sow_delete` command is acknowledging a message from a queue. When this option is used, the message must have been provided from a message queue, and the `SowKeys` and `Filter` headers may not be used.
`Options` | Available when the `sow_delete` command is acknowledging a message from a queue. When a value of `cancel` is provided in this field, the message is returned to the queue and made available to other subscribers. When a value of `expire` is provided in this field, the message is automatically expired by AMPS, removing the message from the queue and invoking any actions configured to listen for message expirations.

Table 5.1: Header fields supported by sow_delete

| The `SowKeys`, `Filter`, `Data` and `Bookmark` header fields cannot be used together. They are mutually exclusive. Using them together in the same `sow_delete` command will cause indeterminate results.

### Returns

For a `sow_delete` message, AMPS will send acknowledgment message, `completed` and `stats` for the following acknowledgment message types: `received`, `processed` and `persisted` along with a populated `Status` header field describing the acknowledgment.

Acknowledgment | Description
--- | ---
`none` | No acknowledgment message is returned. This is the default behavior.
`completed` | Supported for a `sow_delete` with a `Filter` defined. The `completed` acknowledgment message is returned when the query portion of the command has completed.
`persisted` | When an AMPS engine returns an acknowledgment message of `persisted` this guarantees that All downstream synchronous replication(s) have acknowledged that the message(s) have been deleted from their respective SOW topic(s). The `sow_delete` message has been sent to all available downstream asynchronous replications.
`processed` | AMPS has compiled the filter(s) for the `sow_delete` messages.
`received` | The `sow_delete` message has been received.
`stats` | Returns an acknowledgment message with `Matches`, `TopicMatches` and `RecordsDeleted`.

Table 5.2: Acknowledgment messages types supported by sow_delete

The `stats` acknowledgment message include three values in the header, the `Matches`, `TopicMatches` and the `RecordsDeleted`. These are defined below:

#### TopicMatches

The total number of records compared across all matching SOW topics.

#### Matches

The number of records returned that match the topic regular expression and the content filter.

#### RecordsDeleted

The total number of records deleted.

### Errors

Errors that occur during a `sow_delete` are returned as part of the `processed` acknowledgment message and recorded to the log. Typical errors involved a missing topic, or a missing/invalid `SowKey`.