sow_and_delta_subscribe command

A sow_and_delta_subscribe command is used to combine the functionality of commands sow and a delta_subscribe in a single command.

The sow_and_delta_subscribe command is used: (a) to query the contents of a SOW topic (this is the sow command); and (b) to place a subscription such that any messages matching the subscribed SOW topic and query filter will be published to the AMPS client (this is the delta_subscribe command). As with the delta_subscribe command, publish messages representing updates to SOW records will contain only the information that has changed.

If a sow_and_delta_subscribe is issued on a record that does not currently exist in the SOW topic, or if it is used on a topic that does not have a SOW-topic store defined, then a sow_and_delta_subscribe will behave like a sow_and_subscribe command.

Header Fields

The following table contains the header fields supported by a sow_and_delta_subscribe command.

Field	Description
cmd	The command to be executed. Value: sow_and_delta_subscribe
topic	The target SOW topic to query and subscribe to.
ack_type	Acknowledgment type for the given command. Value is a comma separated string of one of more of the following: none, received, processed, completed or stats.
batch_size	Number of records to return in a single sow query results message. While the default value is 1, it is recommended to use a higher value, as even small increases can yield greater performance in query result delivery.
cmd_id	If specified with an AMPS command requesting an acknowledgment message, all ack messages will contain the CommandId in the acknowledgment message.
data_only	If true, send only raw data to subscriber for a matching publish message. For example, this will remove the SOAP envelope in an XML message.
filter	Content filter expression.
opts	A comma separated list of flags available to the sow_and_delta_subscribe command. The Options Field table below describes the Options available for use in the sow_and_delta_subscribe command.
orderby	Return the SOW results sorted by the specified fields. Fields are a comma-delimited list of AMPS identifiers, and may optionally include a sort specifier, ASC or DESC.
query_id	Identifier used to identify the client's SOW topic query. This identifier will be added to all messages that represent a response to the sow_and_delta_subscribe command.
send_empty	If set to true, empty published messages are forwarded to matching subscriptions. Default: true
send_oof	Messages that have fallen out of focus from the subscription are sent to the client. Default: false
send_keys	Option to instruct AMPS that the client would like to receive the SowKey back.
send_matching_ids	If true subscription identifiers will be sent for a matched message.
sow_keys	A comma-delimited list of SowKeys that identify the messages to return from the query. For example, you might send a query with the SowKeys value 42,100,3467 which would return records with those SowKey values, if any exist in the SOW.
sub_id	The subscription ID for this command. When provided with a new subscription, this is the identifier that AMPS will use for the subscription. When provided with the replace option, this field specifies the subscription to replace. When provided with a pause or resume option, this field specifies the subscriptions to pause or resume. For a new subscription, the AMPS clients will generate a subscription ID if one is not provided.
top_n	Return up to the number of messages specified from the SOW query.

Options Field

The following table contains a list of the Options available and their definitions when used in the AMPS sow_and_delta_subscribe command.

Option	Description
none	This is the default Options type.
bookmark	Specifies that the subscription should return bookmarks, if available, on each publish message. Bookmarks are only available if the topic that is subscribed to is recorded in the transaction log. Notice that this option does not set the starting point for a bookmark subscription: use the Bookmark header for that purpose. This option is not required to receive bookmarks for a bookmark subscription. Those subscriptions always include bookmarks on each publish message.
conflation=n	Specifies whether to conflate this subscription. The value provided can be a time interval, auto, or none. When present and set to a value other than none, enables conflation for the subscription. Can also be set to auto, which requests that AMPS attempt to determine an appropriate conflation interval based on client consumption. Recognizes the same time specifiers used in the AMPS configuration file (for example, 100ms or 1s or 1m). Default: none
conflation_key=[key]	When conflation is enabled, specifies the fields to use to determine message uniqueness. The format of this option is a comma-delimited list of XPath identifiers within brackets. For example, to conflate based on the value of the /tickerId and /customerId within a message, the value of this option would be: [/tickerId,/customerId] Defaults to the SOW key fields for SOW topics. No default for non-SOW topics. This option is required for non-SOW topics. This option is not valid with the oof option unless the keys provided are identical to the keys for the topic.
grouping=[keys]	For use with aggregated subscriptions. The format of this option is a comma-delimited list of XPath identifiers within brackets. For example, to aggregate entries based on their /description (producing one record in the aggregation for each distinct value in /description), the value of this option would be: [/description] This option must contain an entry for every field in the aggregated message. If there is no entry for a field in this option, that field will not appear in the aggregated message, even if the field is in the underlying message. When this option is provided, a projection must also be provided. This option cannot be used with a bookmark.
live	Tells AMPS to send messages to subscribing clients before they have been persisted to the transaction log.
no_empties	Tells AMPS not to send empty publish messages to matching subscriptions. This can be useful for suppressing messages where no fields have changed.
no_sowkey	Tells AMPS not to send the AMPS-generated SowKey for messages.
non_regex_topic	Specifies that the topic name should be a literal match, even if the topic name contains regular expression characters.
oof	Send an OOF message for records that have fallen out of focus from the original subscription. When focus tracking is enabled, AMPS will also deliver the full message to a subscription when a previously out-of-focus message comes into focus.
projection=[fields]	For use with aggregated subscriptions. Specifies a comma-delimited set of fields to project, within brackets. Each entry has the format described in the AMPS User Guide. This option must contain an entry for every field in the aggregated message. If there is no entry for a field in this option, that field will not appear in the aggregated message, even if the field is in the underlying message. There is no default for this option. When this option is provided, a grouping must also be provided. This option cannot be used with a bookmark. The maximum size of this option is 64KB.
replace	Replace the subscription associated with CmdId with another subscription.
top_n=n	AMPS will provide at most n records, starting at the beginning of the result set as defined by the OrderBy header. This option is equivalent to providing a TopN header.
skip_n=n	AMPS will skip the specified number of records in the result set before returning results. This option is used with the top_n option to create a paginated subscription.
send_keys	AMPS will send the SOW keys (that is, the data fields used to identify unique messages in the SOW) back with matching messages from the SOW.
select=[fields]	Specifies the fields to include in messages provided on this subscription. The contents of this option are a comma-delimited list of inclusion specifiers.
timestamp	AMPS will include a header with the time at which this instance of AMPS processed the incoming publish command for this message.

Returns

A sow_and_delta_subscribe command returns the following command types:

Command	Description
group_begin	Indicates the beginning of results from a SOW query.
group_end	Indicates the end of results from a SOW query.
sow	Indicates a record returned from a SOW query.
publish	A new message or update published to AMPS.
oof	Returned when the oof option is requested on the command, the subscription is to a topic in the SOW, and the subscription is not a bookmark subscribe.
ack	Acknowledgments requested, as described in the following section.

AMPS will send acknowledgment messages for the following AckType fields: received and processed, along with a populated Status header field describing the acknowledgment message.

If the sow_and_delta_subscribe command is successful, AMPS will return a group_begin message to notify the client that a group of messages is being returned as part of the sow portion of the command. For more information about SOW topic query behavior, see the chapter on Querying the State of the World in the AMPS User Guide. The following table contains the AckType messages which can be returned by a sow_and_delta_subscribe.

Acknowledgment	Description
none	No ack message is returned. This is the default behavior.
completed	The sow_and_delta_subscribe message has completed the sow portion of the command, and all future messages will be updated based on publishes.
persisted	Not supported at this time.
processed	AMPS has compiled the filter(s) for the sow_and_delta_subscribe message(s).
received	The sow_and_delta_subscribe message has been received.
stats	Returns an ack message with Matches, TopicMatches and RecordsReturned.

The stats acknowledgment message includes three values in the header, the Matches, TopicMatches and the RecordsReturned. 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. This value can be greater than RecordsReturned in the case where the number of returned records is limited by TopN.

RecordsReturned

The total number of records returned to the client, which can be limited by the TopN header value.

Errors

Errors for a sow_and_delta_subscribe query are either returned in the Status field if an AckType has been defined, or the errors may be inserted into the AMPS log.