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).
Last updated