# 4. Querying and Subscribing

This section describes commands used to retrieve content messages from AMPS, including both queries and subscriptions.

For details on the differences between these commands, see the AMPS User Guide.

## delta_subscribe

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

The following table 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.

Header fields supported by delta_subscribe

### Options Field

The following table contains a list of the `Options` available and their definitions when used in the AMPS `sow_and_delta_subscribe` command.

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. This option is not valid with the `oof` option unless the keys provided are identical to the keys for the topic.
`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.
`non_regex_topic` | Specifies that the topic name should be a literal match, even if the topic name contains regular expression characters.
`oof` | Send an OOF message for records 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.

Options types supported by delta_subscribe

### Returns

A `delta_subscribe` command returns the following command types:

Command | Description
--- | ---
`publish` | A message published to AMPS.
`oof` | Returned when the `oof` option is requested on the command, the subscription is to a topic in the State of the World, and the subscription is not a bookmark subscribe.
`ack` | Acknowledgements requested, as described in the following section.

Command types returned by delta_subscribe

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.

The following table 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`.

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

A `sow_and_delta_subscribe` command is used to combine the functionality of commands `sow` and a `delta_subscribe` in a single command.

The `sow_and_delta_subscribe` command is used (a) to query the contents of a SOW topic (this is the `sow` command); and (b) to place a subscription such that any messages matching the subscribed SOW topic and query filter will be published to the AMPS client (this is the `delta_subscribe` command). As with the `delta_subscribe` command, `publish` messages representing updates to SOW records will contain only the information that has changed.

If a `sow_and_delta_subscribe` is issued on a record that does not currently exist in the SOW topic, or if it is used on a topic that does not have a SOW-topic store defined, then a `sow_and_delta_subscribe` will behave like a `sow_and_subscribe` command.

### Header Fields

The following table contains the header fields supported by a `sow_and_delta_subscribe` command.

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.

Header fields supported by sow_and_delta_subscribe

### Options Field

The following table contains a list of the `Options` available and their definitions when used in the AMPS `sow_and_delta_subscribe` command.

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. This option is not valid with the `oof` option unless the keys provided are identical to the keys for the topic.
`grouping=[keys]` | For use with aggregated subscriptions. The format of this option is a comma-delimited list of XPath identifiers within brackets. For example, to aggregate entries based on their `/description` (producing one record in the aggregation for each distinct value in `/description`), 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.
`non_regex_topic` | Specifies that the topic name should be a literal match, even if the topic name contains regular expression characters.
`oof` | Send an `OOF` message for records that have fallen out of focus from the original subscription. When focus tracking is enabled, AMPS will also deliver the full message to a subscription when a previously out-of-focus message comes into focus.
`projection=[fields]` | For use with aggregated subscriptions. Specifies a comma-delimited set of fields to project, within brackets. Each entry has the format described in the AMPS User Guide. This option must contain an entry for every field in the aggregated message. If there is no entry for a field in this option, that field will not appear in the aggregated message, even if the field is in the underlying message. There is no default for this option. When this option is provided, a `grouping` must also be provided. This option cannot be used with a bookmark. The maximum size of this option is 64KB.
`replace` | Replace the subscription associated with `CmdId` with another subscription.
`top_n=n` | AMPS will provide at most `n` records, starting at the beginning of the result set as defined by the `OrderBy` header. This option is equivalent to providing a `TopN` header.
`skip_n=n` | AMPS will skip the specified number of records in the result set before returning results. This option is used with the `top_n` option to create a paginated subscription.
`send_keys` | AMPS will send the SOW keys (that is, the data fields used to identify unique messages in the SOW) back with matching messages from the SOW.
`select` | 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.

Options supported by sow_and_delta_subscribe

### Returns

A `sow_and_delta_subscribe` command returns the following command types:

Command | Description
--- | ---
`group_begin` | Indicates the beginning of results from a SOW query.
`group_end` | Indicates the end of results from a SOW query.
`sow` | Indicates a record returned from a SOW query
`publish` | A new message or update published to AMPS.
`oof` | Returned when the `oof` option is requested on the command, the subscription is to a topic in the State of the World, and the subscription is not a bookmark subscribe.
`ack` | Acknowledgements requested, as described in the following section.

Command types returned by sow_and_delta_subscribe

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. The following table 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`.

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

A `sow_and_subscribe` command is used to combine the functionality of `sow` and a `subscribe` command in a single command.

The `sow_and_subscribe` command is used (a) to query the contents of a SOW topic (this is the `sow` command); and (b) to place a subscription such that any messages matching the subscribed SOW topic and query filter will be published to the AMPS client (this is the `subscribe` command). As with the `subscribe` command, `publish` messages representing updates to SOW records are provided for records that match the filter when there is an update published to that record.

### Header Fields

The following table contains the header fields supported by a `sow_and_subscribe` command.

Field | Description
--- | ---
`Command` | The command to be executed. Value: `sow_and_subscribe`.
`Topic` | The target SOW topic to query and subscribe.
`AckType` | Acknowledgment type for the given command. Value is a comma separated string of one of more of the following: `none`, `received`, `processed`, `completed` or `stats`.
`BatchSize` | Number of records to return in a single sow query results message. 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 “Options types supported by sow_and_subscribe” 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.

Header fields supported by sow_and_subscribe

### Returns

A `sow_and_subscribe` command returns the following command types:

Command | Description
--- | ---
`group_begin` | Indicates the beginning of results from a SOW query.
`group_end` | Indicates the end of results from a SOW query.
`sow` | Indicates a record returned from a SOW query
`publish` | A new message or update published to AMPS.
`oof` | Returned when the `oof` option is requested on the command, the subscription is to a topic in the State of the World, and the subscription is not a bookmark subscribe.
`ack` | Acknowledgements requested, as described in the following section.

Command types returned by sow_and_subscribe

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. The following table contains the `AckType` messages that can be returned by a `sow_and_subscribe`.

Acknowledgment | Description
--- | ---
`none` | No `ack` message is returned. This is the default behavior.
`bookmark` | Specifies that the subscription should return bookmarks, if available, on each publish message. Bookmarks are only available if the topic that is subscribed to is recorded in the transaction log. Notice that this option does not set the starting point for a bookmark subscription: use the `Bookmark` header for that purpose. This option is not required to receive bookmarks for a bookmark subscription. Those subscriptions always include bookmarks on each publish message.
`completed` | The `sow_and_subscribe` message has completed the `sow` portion of the command, and all future messages will be updated based on publishes.
`persisted` | Not supported at this time.
`processed` | AMPS has completed the work necessary to register the subscription and begin the SOW query.
`received` | The `sow_and_subscribe` message has been received.
`stats` | Returns an `ack` message with `Matches`, `TopicMatches` and `RecordsReturned`.

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

The following table contains a list of the `Options` available and their definitions when used in the AMPS `sow_and_subscribe` command.

Option | Description
--- | ---
`none` | This is the default `Options` type.
`conflation=n` | Specifies whether to conflate this subscription.The value provided can be a time interval, `auto`, or `none` When present and set to a value other than none, enables conflation for the subscription. Can also be set to `auto`, which requests that AMPS attempt to determine an appropriate conflation interval based on client consumption. Recognizes the same time specifiers used in the AMPS configuration file (for example, `100ms` or `1s` or `1m`). 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. This option is not valid with the `oof` option unless the keys provided are the same as the keys for the underlying topic.
`grouping=[keys]` | For use with aggregated subscriptions. The format of this option is a comma-delimited list of XPath identifiers within brackets. For example, to aggregate entries based on their `/description` (producing one record in the aggregation for each distinct value in `/description`), 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.
`non_regex_topic` | Specifies that the topic name should be a literal match, even if the topic name contains regular expression characters.
`oof` | Send on `OOF` message for records which have fallen out of focus from the original subscription.
`pause` | Pause a bookmark subscription. This option is only valid for bookmark subscriptions that do not use the `live` option. When this option is present, AMPS pauses the subscription or subscriptions provided in the `SubId` of the command.
`projection[fields]` | For use with aggregated subscriptions. Specifies a comma-delimited set of fields to project, within brackets. Each entry has the format described in the AMPS User Guide. This option must contain an entry for every field in the aggregated message. If there is no entry for a field in this option, that field will not appear in the aggregated message, even if the field is in the underlying message. There is no default for this option. When this option is provided, a `grouping` must also be provided. This option cannot be used with a bookmark. The maximum size of this option is 64KB.
`rate=n` | Set the maximum message delivery rate for a bookmark subscription. This option is only valid for bookmark subscriptions that do not use the `live` option. The rate can be specified as either the number of messages per second (for example, `1000`), the number of bytes per second (for example, `100KB`), or a multiple of the original replay rate (for example, `1.5X`).
`replace` | Replace the subscription associated with `CmdId` with another subscription. When provided as part of `sow_and_subscribe`, AMPS runs a SOW query for the new subscription.
`resume` | Resume a bookmark subscription. This option is only valid for bookmark subscriptions that do not use the `live` option. When this option is present, AMPS resumes the subscription or subscriptions provided in the `SubId` of the command.
`top_n=n` | AMPS will provide at most `n` records, starting at the beginning of the result set as defined by the `OrderBy` header. This option is equivalent to providing a `TopN` header.
`skip_n=n` | AMPS will skip the specified number of records in the result set before returning results. This option is used with the `top_n` option to create a paginated subscription.
`send_keys` | AMPS will send the SOW keys (that is, the data fields used to identify unique messages in the SOW) back with matching messages from the SOW.
`select` | 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.

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

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 4.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.

Header fields supported by subscribe

### Options Field

The following table 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. This option is not valid with the `oof` option unless the keys provided are identical to the keys for the topic.
`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.
`non_regex_topic` | Specifies that the topic name should be a literal match, even if the topic name contains regular expression characters.
`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.

Options types supported by subscribe

### Returns

A `subscribe` command returns the following command types:

Command | Description
--- | ---
`publish` | A message published to AMPS.
`oof` | Returned when the `oof` option is requested on the command, the subscription is to a topic in the State of the World, and the subscription is not a bookmark subscribe.
`ack` | Acknowledgements requested, as described in the following section.

Command types returned by subscribe

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.

The following table 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 `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.

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

The `sow` command is use to query the contents of a previously defined topic in the state of the world (including also views, queues, and conflated topics). A `sow` command can be used to query an entire SOW `Topic`, or a filter can be used to further refine the results from the State of the World. 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 specifier, `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.

Header fields supported by sow

### Options Field

The following table 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.

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.

The following table 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.

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` acknowledgment 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

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.

Header fields supported by unsubscribe

### Returns

The `unsubscribe` command supports the `received` and `processed` acknowledgment message types, as described in the following table.

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.

Acknowledgment messages supported by unsubscribe