Cookbook: SOW and Subscribe
This section presents common recipes for atomic SOW and Subscribe in AMPS using the Command
or Message
interfaces. This section provides information on how to configure the request to AMPS. You can adapt this information to your application and the specific interface you are using.
Command: sow_and_subscribe
Basic SOW and Subscribe
In its simplest form, a SOW and Subscribe command needs only the topic to query and subscribe to.
Topic
(required)
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
SOW and Subscribe with Options
In its simplest form, a SOW and Subscribe command needs only the topic to query and subscribe to. To add options to the subscription, set the Options
header on the Command
.
Topic
(required)
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Options
A comma-delimited set of options for this command. See the sow_and_subscribe
section for a full description of supported options. The most common options for this command are:
oof
- Request out of focus notifications.timestamp
- Include timestamps on messages.
SOW and Subscribe with Select List
In its simplest form, a SOW and Subscribe command needs only the topic to query and subscribe to. To add options to the subscription, set the Options
header on the Command
. To use a select list, include the specifier for the select list in the options provided.
Topic
(required)
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Options
A comma-delimited set of options for this command. See the sow_and_subscribe
section for a full description of supported options. For example, to remove all fields except for id
and ticker
, and also request out of focus notifications, you might use an options string of: oof,select=[-/,+/id,+/ticker]
.
SOW and Subscribe with Content Filter
To provide a content filter on a SOW and Subscribe command, set the Filter
property on the command. The AMPS User Guide provides details on the filter syntax.
Topic
(required)
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Filter
Sets the content filter to be applied to the query. Only messages that match the content filter will be returned in response to the query.
Conflated SOW and Subscribe
To request conflation on the subscription for a SOW and Subscribe command, set the Options
property on the command to specify the conflation interval. When the topic has a SOW (including a view or a conflated topic), there is no need to provide a conflation_key
.
Topic
(required)
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Options
A comma-separated list of options for the command. Set the conflation interval in the options. For example, to set a conflation interval of 250 milliseconds, provide the following option: conflation=250ms
. To set the conflation interval to 1 minute, provide an option of: conflation=1m
.
Paginated SOW and Subscribe
To request a paginated subscription for a SOW and Subscribe command, set the Options
property on the command to specify the number of records to return and the number of records to skip before returning records. Most paginated subscriptions also specify the oof
option to be notified when a record is out of focus.
Topic
(required)
Sets the topic to query and subscribe to. The topic specified must be a literal topic name. Pagination is not supported with regular expression subscriptions.
OrderBy
Specifies how to order the results within the paginated result set. If the OrderBy
is not provided, the results are ordered by the SowKey
for the messages.
Options
A comma-separated list of options for the command. Set the number of results returned with top_n
, and the starting point within the result set with skip_n
. For example, to display records 31-50 of the result set, you could provide the following option: top_n=20,skip_n=30,oof
. This tells AMPS to skip the first 30 records of the result set, and then provide the top 20 records from the remaining results. Out of focus notifications will be provided.
Historical SOW and Subscribe
To create a historical SOW query with a subscription, set the Bookmark
property on the command. The property can be either a specific bookmark or a timestamp. The AMPS User Guide provides details on creating timestamps. This command is only supported on SOW topics that are recorded in an AMPS transaction log.
When History
is enabled for the SOW topic, the Bookmark
provided must be a timestamp or a specific bookmark value, including the special values NOW
(0|1|
) or EPOCH
(0
).
If the Bookmark
provided is a value other than NOW
(0|1|
), the SOW topic must have History
enabled.
Topic
(required)
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark
Sets the historical point in the SOW at which to query. The query returns the saved state of the records in the SOW as of the point in time specified in this header.
Historical SOW and Subscribe with Content Filter
To create a historical SOW query with a subscription, set the Bookmark
property on the command. The property can be either a specific bookmark or a timestamp. The AMPS User Guide provides details on creating timestamps. This command is only supported on SOW topics that are recorded in an AMPS transaction log. If the Bookmark
provided is a value other than NOW (0|1|
), the SOW topic must have History
enabled.
Topic
(required)
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Bookmark
Sets the historical point in the SOW at which to query. The query returns the saved state of the records in the SOW as of the point in time specified in this header.
Filter
Sets the content filter to be applied to the query. Only messages that match the content filter will be provided to the query.
Aggregated SOW and Subscribe
An aggregated SOW and Subscribe command is a command that provides aggregation options. To add these options to the sow_and_subscribe
command, set the Options
header on the Command
.
Topic
(required)
Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Options
A comma-delimited set of options for this command. For an aggregated subscription, the options provide the projection
and grouping
for the command. An aggregated SOW and Subscribe can include options in addition to projection
and grouping
. The most common additional options are:
oof
- Request out of focus notifications.timestamp
- Include timestamp headers on messages.
Last updated