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 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 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, When present and set to a value other than none, enables conflation for the subscription. Can also be set to Recognizes the same time specifiers used in the
AMPS configuration file (for example, Defaults to |
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
Defaults to the SOW key fields for SOW topics. No default for non-SOW topics. This option is required for non-SOW topics. |
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. |
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 this instance of 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 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 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, When present and set to a value other than none, enables conflation for the subscription. Can also be set to Recognizes the same time specifiers used in the
AMPS configuration file (for example, Defaults to |
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
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
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 |
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 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 this instance of 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 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 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, When present and set to a value other than none, enables conflation for the subscription. Can also be set to Recognizes the same time specifiers used in the
AMPS configuration file (for example, Defaults to |
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
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
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 |
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 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 this instance of 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 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 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, When present and set to a value other than none, enables conflation for the subscription. Can also be set to Recognizes the same time specifiers used in the
AMPS configuration file (for example, Defaults to |
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
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. |
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. |
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 this instance of 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 |
Used by bookmark subscriptions to identify the point at which replay is completed. When a bookmark is present on the subscribe
request and this acknowledgment is requested,
AMPS sends a |
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
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 When the topic has |
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 When the topic has 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.
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:
- Adding the
all
keyword to theSubId
header field in theunsubscribe
message will unsubscribe the client from all AMPS SOW topic subscriptions. - With each
subscription
command issued, AMPS will return aSubId
with theprocessed
acknowledgment message. Issuing anunsubscribe
command using the sameSubId
header field which was returned as part of the originalsubscribe
command’sprocessed
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 This command requires at least one of the
|
QueryId |
To cancel an in-progress SOW query, the
unsubscribe command accepts the Query ID entered
in AMPS by the client when the original This command requires at least one of the
|
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