sow_and_subscribe

A sow_and_subscribe command is used to combine the functionality of sow and a subscribe command in a single command.

The sow_and_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 subscribe command). As with the subscribe command, publish messages representing updates to SOW records are provided for records that match the filter when there is an update published to that record.

Header Fields

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

Field	Description
Command	The command to be executed. Value: sow_and_subscribe
Topic	The target SOW topic to query and subscribe.
AckType	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.
BatchSize	Number of records to return in a single sow query results message. The AMPS server default value is 1. It is recommended to use a higher value, as even small increases can yield greater performance in query result delivery. Current AMPS client libraries provide a BatchSize of 10 by default. The BatchSize header only applies to the sow query.
Bookmark	A bookmark specifying the historical state of the SOW to return results from. For SOW topics where historical query is enabled, AMPS returns the saved state of the SOW as of that bookmark. For SOW topics where historical query is not enabled, AMPS ignores this parameter. If the topic is enabled for historical query and AMPS has a transaction log that covers the topic, AMPS returns the saved state of the SOW as of that bookmark and starts a bookmark subscription at a point in the transaction log immediately after the point at which the SOW state was saved. In other words, if the granularity of the historical SOW preserves the state of the SOW at 11:30:10 AM and 11:30:50 AM, a request for a bookmark at 11:30:20 AM will provide the SOW state as of 11:30:10 AM, and begin the replay immediately after that SOW state. This ensures no messages are missed, but means that the subscription may begin before the bookmark.
CommandId	If specified with an AMPS command requesting an acknowledgment message, all ack messages will contain the CommandId in the acknowledgment message.
DataOnly	Only send raw data to subscriber for a matching publish message if true. For example, this will remove the SOAP envelope in an XML message.
Filter	Content filter expression.
Options	A comma separated list of flags available to the sow_and_subscribe command. The Options Field table below describes the Options available for use in the sow_and_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.
QueryId	Identifier used to identify the client's SOW topic query. This identifier will be added to all messages representing a response to the sow_and_subscribe command.
SendOOF	Messages that have fallen out of focus from the subscription are sent to the client. Default: false
SendKeys	Option to instruct AMPS that the client would like to receive the SowKey back.
SendSubscriptionIds	If true, subscription identifiers will be sent for a matched message.
SowKeys	A comma-delimited list of SowKeys that identify the messages to return from the query.
SubscriptionId	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.
TopN	Return up to the number of messages specified from the SOW query.

Returns

A sow_and_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, processed along with a populated Status header field describing the acknowledgment message.

If the sow_and_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 that can be returned by a sow_and_subscribe.

Acknowledgment	Description
none	No ack message is returned. This is the default behavior.
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.
completed	The sow_and_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 completed the work necessary to register the subscription and begin the SOW query.
received	The sow_and_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: 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.

Options Field

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

Option	Description
none	This is the default Options type.
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 the same as the keys for the underlying 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. This option is only valid for bookmark subscriptions.
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 on OOF message for records which have fallen out of focus from the original subscription.
pause	Pause a bookmark subscription. This option is only valid for bookmark subscriptions that do not use the live option. When this option is present, AMPS pauses the subscription or subscriptions provided in the SubId of the command.
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.
rate=n	Set the maximum message delivery rate for a bookmark subscription. This option is only valid for bookmark subscriptions that do not use the live option. The rate can be specified as either the number of messages per second (for example, 1000), the number of bytes per second (for example, 100KB), or a multiple of the original replay rate (for example, 1.5X).
replace	Replace the subscription associated with CmdId with another subscription. When provided as part of sow_and_subscribe, AMPS runs a SOW query for the new subscription.
resume	Resume a bookmark subscription. This option is only valid for bookmark subscriptions that do not use the live option. When this option is present, AMPS resumes the subscription or subscriptions provided in the SubId of the command.
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.

Errors

Errors for a sow_and_subscribe query are returned in the Status field if an AckType has been defined. Errors will also be logged in the errors and events log (subject to logging configuration).