Removing Messages (SOW/Topic or Message Queue)

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 SowKeys 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. This form can only be used for acknowledging messages from a queue topic.

Header Fields

The following table 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.

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.

The Bookmark header can only be used to acknowledge messages from queue topics.

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: 1. All downstream synchronous replication(s) have acknowledged that the message(s) have been deleted from their respective SOW topic(s). 2. 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.

The stats acknowledgment message include three values in the header, 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.