4. Querying and Subscribing

delta_subscribe

Description

The delta_subscribe command is like the subscribe command except that subscriptions placed through delta_subscribe will receive only messages that have changed between the SOW record and the new update.

If delta_subscribe is used on a topic which does not have a SOW store defined, then delta_subscribe behaves like a subscribe command.

Header Fields

Table 4.1 contains the header fields available to a delta_subscribe command.

Field Description
Command
Command to be executed. Value: delta_publish
Topic
Topic with which to place a subscription.
AckType Acknowledgment type for the delta_subscribe command. Value is a comma separated list of one or more of the following: none, received, processed, completed or stats.
CommandId If specified with an AMPS command requesting an acknowledgment message, all requested acknowledgment messages will contain the CommandId in the acknowledgment response header.
DataOnly A Boolean (true or false) used to determine the type of data sent to the subscriber. A value of true will, for example, not include a SOAP envelope.
Filter String which is used as a content filter expression. When using XML, the filter must be wrapped in a CDATA.
Options A comma separated list of flags available to the subscribe command. Table 3.2 describes the Options available for use in the delta-subscribe command.
SendEmpty Boolean (true or false) value used to determine whether empty messages which are published will be forwarded to matching subscriptions. The default value is true.
SendSubscriptionIds Boolean (true or false) subscription identifiers will not be sent for all matched messages if set to false.
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.

Bookmark A bookmark specifying the point in the transaction log at which to start the subscription. If the topic provided is not recorded in a transaction log, AMPS enters the subscription without replaying messages. You can provide a single bookmark, or a comma-delimited list of bookmarks. When a list is provided, AMPS starts the subscription at the earliest bookmark in the list.

Table 4.1: Header fields supported by delta_subscribe

Options Field

Table 4.2 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).

Defaults to 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.

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), you would use the following option:

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.

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.
max_backlog=n When subscribing to a queue, the number of unacknowledged messages the client is willing to accept at a time. AMPS will not exceed this number, but may choose a smaller number depending on the queue configuration.
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.
oof Send an OOF message for records which 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.
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.

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.
send_keys AMPS will send the SOW keys fields back with messages from the SOW. Notice that without this option, messages will never contain these fields (since, by definition, they do not change from update to update).
timestamp AMPS will include a header with the time at which AMPS processed the incoming publish command for this message.

Table 4.2: Options types supported by delta_subscribe

Returns

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

Table 4.3 contains the AckType messages which can be returned by a delta_subscribe.

Acknowledgment Description
none No ack is returned. This is the default behavior.
completed When a bookmark is present on the subscribe request and this acknowledgment is requested, AMPS sends a completed acknowledgment message to indicate that bookmark replay is complete. Further messages on this subscription are from new publishes.
persisted When a bookmark is present and this acknowledgment is requested, AMPS periodically sends a persisted acknowledgment message to indicate the most recent bookmark in the server’s transaction log.
processed AMPS has compiled the filters for the delta_subscribe message(s).
received The delta_subscribe message has been received.
stats Returns an acknowledgment message with Matches, TopicMatches and RecordsReturned.

Table 4.3: Acknowledgment messages supported by delta_publish

Errors

Any errors that occur during this command will be returned in the status of a processed acknowledgment and logged to the log file. Regardless of success or failure, the processed acknowledgment will be returned only if requested by including processed in the AckType field of the delta_subscribe message header.

sow_and_delta_subscribe

Description

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

Table 4.4 contains the header fields supported by a sow_and_delta_subscribe command.

Field Description
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.
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 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 one or more of the options in Table 3.5 , which describes all of the Options available.
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 is true.
SendOOF Messages that have fallen out of focus from the subscription are sent to the client. Default is 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.

Table 4.4: Header fields supported by sow_and_delta_subscribe

Options Field

Table 4.5 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).

Defaults to 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.

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), you would use the following option:

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.
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 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 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 AMPS processed the incoming publish command for this message.

Table 4.5: Options supported by sow_and_delta_subscribe

Returns

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. The SOW Queries chapter in the AMPS User Guide provides more information about SOW topic query behavior. Table 4.6 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.

Table 4.6: Acknowledgment messages supported by sow_and_delta_subscribe

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.

sow_and_subscribe

Description

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

Table 4.7 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. 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.
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. Table 3.9 describes the options available.
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 is 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.

Table 4.7: Header fields supported by sow_and_subscribe

Returns

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.

The SOW Queries chapter in the AMPS User Guide will provide more information about SOW topic query behavior. Table 4.8 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.

Table 4.8: Acknowledgment messages supported by sow_and_subscribe

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.

Options Field

Table 4.9 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).

Defaults to 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.

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), you would use the following option:

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.
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 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 AMPS processed the incoming publish command for this message.

Table 4.9: Options types supported by sow_and_subscribe

Errors

Errors for a sow_and_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.

subscribe

Description

The subscribe command is the primary way to retrieve messages from the AMPS processing stream. A client can issue a subscribe command on a topic to receive all published messages to that topic in the future. Additionally, content filtering can be used to choose which messages the client is interested in receiving.

Header Fields

Field Description
Command
Command to be executed. Value: subscribe.
Topic
Topic to place a subscription against.
AckType Acknowledgment type for the given command. Value is a comma separated list of one or more of the following: none, received, processed or completed.
Bookmark A bookmark specifying the point in the transaction log at which to start the subscription. If the topic provided is not recorded in a transaction log, AMPS enters the subscription without replaying messages. You can provide a single bookmark, or a comma-delimited list of bookmarks. When a list is provided, AMPS starts the subscription at the earliest bookmark in the list.
CommandId If specified with an AMPS command requesting an acknowledgment message, all requested acknowledgment messages will contain the CommandId in the ack response header.
DataOnly A Boolean value (true or false) which, if true, will send only raw data to subscriber for a matching publish message. In the case where the message type is XML, the SOAP envelope will not be included.
Filter A CDATA wrapped string, used as a content filter expression.
Options A comma separated list of flags available to the subscribe command. Table 3.11 describes the Options available for use in the subscribe command.
SendSubscriptionIds Boolean (true or false) that tells if true requests AMPS to send subscription identifiers with a matched message.
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 The maximum number of messages to provide from a bookmark subscription. This parameter is only valid for replay from the transaction log. This parameter is not valid if no bookmark is provided, if the provided bookmark is 0|1| (start from now), or if the command includes the live option.

Table 4.10: Header fields supported by subscribe

Options Field

Table 4.11 contains a list of the Options available and their definitions when used in the AMPS 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).

Defaults to none.

conflation_key=[keys]

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.

fully_durable

Tells AMPS to send messages to subscribing clients only after they have been persisted to the local transaction log and acknowledged by all downstream instances that use synchronous replication.

This option is only valid for bookmark subscriptions.

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), you would use the following option:

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 for bookmark subscriptions.

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.
max_backlog=n When subscribing to a queue, the number of unacknowledged messages the client is willing to accept at a time. AMPS will not exceed this number, but may choose a smaller number depending on the queue configuration.
no_sowkey Tells AMPS not to send the AMPS-generated SowKey for messages.
oof Not supported by this command type.
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 for bookmark subscriptions.

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).
rate_max_gap=n When entering a bookmark subscribe that is rate-limited, specify the maximum amount of time that AMPS will wait between messages.
replace Replace the subscription associated with CmdId with another 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.
select Specifies the fields to include in messages provided on this subscription. The contents of this option are a comma-delimited list of inclusion specifiers.
send_keys Not supported by this command type.
timestamp AMPS will include a header with the time at which AMPS processed the incoming publish command for this message.

Table 4.11: Options types supported by subscribe

Returns

It is possible to specify a processed acknowledgment be sent back to the client that issued the subscribe command. Within this processed acknowledgment, a client can get back the result of placing the subscription (success or failure) and the SubscriptionId, which uniquely identifies the subscription within AMPS. Keeping track of the SubscriptionId is useful for unsubscribing from subscriptions and issuing SOW queries.

Table 4.12 contains a list of the supported acknowledgment messages available to the subscribe command.

Acknowledgment Description
none No acknowledgment message is returned. This is the default behavior.
completed When a bookmark is present on the subscribe request and this acknowledgment is requested, AMPS sends a completed acknowledgment message to indicate that bookmark replay is complete and the subscription has reached the point in the transaction log at which the subscribe command was received. Messages delivered after the completed ack are from new publishes.
processed AMPS has completed the work necessary to register the subscription. When a bookmark is present and this acknowledgment is requested, this acknowledgment indicates that AMPS is about to begin replay.
persisted When a bookmark is present and this acknowledgment is requested, AMPS periodically sends a persisted acknowledgment message to indicate the most recent bookmark in the server’s transaction log.
received The subscribe message has been received.

Table 4.12: Acknowledgment messages supported by subscribe

Errors

Any errors that occur during this command will be returned in the status of a processed acknowledgment and logged to the log file. Regardless of success or failure, the processed acknowledgment will only be returned if requested by including processed in the AckType field.

sow

Description

The sow command is use to query the contents of a previously defined SOW Topic. A sow command can be used to query an entire SOW Topic, or a filter can be used to further refine the results found inside a SOW Topic. For more information, see the State of the World and SOW Queries chapters in the AMPS User Guide

Header Fields

Field Description
Command
Command to be executed. Value: sow.
Topic
The SOW topic from which the records will be queried.
AckType Acknowledgment type for the given command. Value is a comma separated list of one or more of the following: none, received, processed, completed or stats
BatchSize Number of records to return in a single sow query result message. While the default value is 1, it is recommended to use a higher BatchSize value, as even small increases can yield greater performance in query result delivery.
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.
CommandId If specified with an AMPS command requesting an acknowledgment message, all requested acknowledgment messages will contain the CommandId in the ack response header.
Filter Content filter expression. See the Content Filtering chapter in the AMPS User Guide for more information on using content filters.
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 specifer, ASC or DESC.
QueryId Unique identifier which is returned as part of the response delivered back to the client.
SowKeys A comma-delimited list of SowKeys that identify the messages to return from the query.
TopN Return up to the number of messages specified from the SOW query.

Table 4.13: Header fields supported by sow

Options Field

Table 4.14 contains a list of the Options available and their definitions when used in the AMPS sow command.

Option Description
none This is the default Options type.
no_sowkey Tells AMPS not to send the AMPS-generated SowKey for messages.
grouping=[keys]

For use with aggregated SOW queries.

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), you would use the following option:

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.

When the topic has History enabled, this option can be used with a bookmark to aggregate the historical state of the SOW.

oof Send on OOF message for records which have fallen out of focus from the original subscription.
projection=[fields]

For use with aggregated SOW queries.

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.

When the topic has History enabled, this option can be used with a bookmark to aggregate the historical state of the SOW.

The maximum size of this option is 64KB.

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.
skip_n Skips the number of messages specified before returning results. A command that provides this option must also provide a top_n option (or header) and an OrderBy header.
top_n Return up to the number of messages specified from the SOW query.
select Specifies the fields to include in messages provided on this subscription. The contents of this option are a comma-delimited list of inclusion specifiers.
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.
timestamp AMPS will include a header with the time at which AMPS processed the incoming publish command for this message.

Table 4.14: Options types supported by sow

Returns

When a sow message is received, AMPS can return a received message as notification that the message has arrived. When the message filter has been processed, AMPS will return the processed acknowledgment message along with any errors that might have occurred.

The results returned by a SOW are put into a sow record group by first sending a group_begin message, followed by the matching SOW records. A group_end message is used to denote the close of query results processing.

Table 4.15 contains a listing of the acknowledgment messages supported by the sow command.

Acknowledgment Description
none No acknowledgment message is returned. This is the default behavior.
completed The sow command has completed.
persisted Not supported at this time.
processed AMPS has compiled the filter(s) for the sow message.
received The sow command has been received.
stats Returns statistics related to the state of the SOW query results.

Table 4.15: Acknowledgment messages returned by sow

The stats message include 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.

Errors

Any errors which occur during a sow command are returned in the processed acknowledgement message. The error is identified in the Status header field in the acknowledgment message, and the reason given in the Reason header field.

caution The ordering of records returned by a SOW query is undefined.

unsubscribe

Description

The unsubscribe command allows a client to notify AMPS that it no longer wishes to receive messages related to a previous subscription.

There are two ways that a client can unsubscribe from an existing subscription:

  1. Adding the all keyword to the SubId header field in the unsubscribe message will unsubscribe the client from all AMPS SOW topic subscriptions.
  2. With each subscription command issued, AMPS will return a SubId with the processed acknowledgment message. Issuing an unsubscribe command using the same SubId header field which was returned as part of the original subscribe command’s processed acknowledgment message will unsubscribe a client from a single subscription.

Header Fields

Field Description
Command
Command to be executed. Value: unsubscribe.
SubId

Subscription ID entered in AMPS by the client when the original subscription was placed. AMPS accepts a single subscription ID or a comma-delimited list of subscription ID. The keyword all can also be used to unsubscribe from all current subscriptions for the client. When both SubId and QueryId are provided, AMPS removes all matching subscriptions and SOW queries.

This command requires at least one of the SubId or QueryIdY fields to be set.

QueryId

To cancel an in-progress SOW query, the unsubscribe command accepts the Query ID entered in AMPS by the client when the original sow command was placed. AMPS accepts a single query ID or a comma-delimited list of query IDs. When both SubId and QueryId are provided, AMPS removes all matching subscriptions and SOW queries.

This command requires at least one of the SubId or QueryId fields to be set.

AckType Acknowledgment type for the given command. Value is a comma separated list of one or more of the following: none, received or persisted.
CommandId If specified within an AMPS command requesting an acknowledgment message, all requested acknowledgment messages will contain the CommandId in the ack response header.

Table 4.16: Header fields supported by unsubscribe

Returns

The unsubscribe command supports the received and processed acknowledgment message types, as described in Table 4.17.

Acknowledgment Description
none No acknowledgment message is returned. This is the default behavior.
completed Not supported at this time.
processed AMPS has processed the unsubscribe message(s).
persisted Not supported at this time.
received The unsubscribe message has been received.
stats Not supported at this time.

Table 4.17: Acknowledgment messages supported by unsubscribe