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.
Command
The command to be executed.
Value: sow_and_delta_subscribe
Topic
The target SOW topic to query and subscribe to.
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.
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.
CommandId
If specified with an AMPS command requesting an acknowledgment message, all ack messages will contain the CommandId in the acknowledgment message.
DataOnly
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.
Options
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.
QueryId
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.
SendEmpty
If set to true, empty published messages are forwarded to matching subscriptions.
Default: true
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.
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.
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.
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.
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:
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
Acknowledgements 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.
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.
Last updated