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
|
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
.