# 10. AMPS Programming: Working with Commands

The AMPS clients provide named convenience methods for core AMPS functionality. These named methods work by creating messages and sending those messages to AMPS. All communication with AMPS occurs through messages.

You can use the `Command` object to customize the messages that AMPS sends. This is useful for more advanced scenarios where you need precise control over the message, or in cases where you need to use an earlier version of the client to communicate with a more recent version of AMPS, or in cases where a named method is not available.

## Understanding AMPS Messages

AMPS messages are represented in the client as AMPS.Message objects. The Message object is generic, and can represent any type of AMPS message, including both outgoing and incoming messages. This section includes a brief overview of elements common to AMPS command message. Full details of commands to AMPS are provided in the AMPS Command Reference Guide.

All AMPS command messages contain the following elements:

- Command. The command tells AMPS how to interpret the message. Without a command, AMPS will reject the message. Examples of commands include `publish`, `subscribe`, and `sow`.
- CommandId. The command id, together with the name of the client, uniquely identifies a command to AMPS. The command ID can be used later on to refer to the command or the results of the command. For example, the command id for a `subscribe` message becomes the identifier for the subscription. The AMPS client provides a command id when the command requires one and no command id is set.

Most AMPS messages contain the following fields:

- Topic. The topic that the command applies to, or a regular expression that identifies a set of topics that the command applies to. For most commands, the topic is required. Commands such as `logon`, `start_timer`, and `stop_timer` do not apply to a specific topic, and do not need this field.
- Ack Type. The ack type tells AMPS how to acknowledge the message to the client. Each command has a default acknowledgment type that AMPS uses if no other type is provided.
- Options. The `options` are a comma-separated list of options that affect how AMPS processes and responds to the message.

Beyond these fields, different commands include fields that are relevant to that particular command. For example, SOW queries, subscriptions, and some forms of SOW deletes accept the Filter field, which specifies the filter to apply to the subscription or query. As another example, publish commands accept the Expiration field, which sets the SOW expiration for the message.

For full details on the options available for each command and the acknowledgment messages returned by AMPS, see the AMPS Command Reference Guide.

## Creating and Populating the Command

To create a command, you simply construct a command object of the appropriate type:

    command = AMPS.Command("sow")

Once created, you set the appropriate fields on the message. For example, the following code creates a sow query, setting the command, topic, and filter for the query:

    command = AMPS.Command("sow")                                   \
                 .set_topic("messages-sow")                         \
                 .set_filter("/id > 20")

When sent to AMPS using the `execute()` method, AMPS performs a SOW query from the topic `messages-sow` using a filter of `/id > 20`. The results of sending this message to AMPS are no different than using the form of the `sow` method that sets these fields.

## Using execute

Once you’ve created a message, use the `execute` method to send the message to AMPS. One form of the `execute` method returns a `MessageStream` that you can use from the calling thread to process responses from AMPS. The other form, `execute_async`, method sends the message to AMPS,waits for a `processed` acknowledgment, then returns. Messages are processed on the client background thread.

For example, the following snippet sends the command created above:

    client.execute(command)

This returns a `MessageStream` identical to the `MessageStream` returned by the equivalent `client.sow()` method.

You can also provide a message handler to receive acknowledgments, statistics, or the results of subscriptions and SOW queries. The AMPS client maintains a background thread that receives and processes incoming messages. The call to `execute_async` returns on the main thread as soon as AMPS acknowledges the command as having been processed, and messages are received and processed on the background thread:

    def handleMessages(m):
       print ("%s : %s" % (m.get_ack_type(), m.get_reason()))
       # other message handling here

    client.execute_async(command, handleMessages)

While this message handler simply prints the ack type and reason for sample purposes, message handlers in production applications are typically designed with a specific purpose. For example, your message handler may fill a work queue, or check for success and throw an exception if the command failed.

### Using execute to Publish

Notice that the `publish` command does not provide typically return results other than acknowledgment messages. To send a `publish` command, use the `execute_async()` method, providing `None` for the message handler:

    client.execute_async(publishCmd, None)

Since the code sets the message handler to `None`, this code does not receive acknowledgments. To detect publish failures, set the `FailedWriteHandler` for the client.

## Command Cookbook

This section is a quick guide to commonly used AMPS commands. For the full range of options on AMPS commands, see theAMPS Command Reference.

## Publishing

This section presents common recipes for publishing to a topic in AMPS using the `Command` or `Message` interfaces. This section provides information on how to configure the request to AMPS. You can adapt this information to your application and the specific interface you are using.

The AMPS server does not return a stream of messages in response to a `publish` command.

| AMPS `publish` commands do not return a stream of messages. A publish command must be used with asynchronous message processing, and should typically pass an empty message handler.

### Basic Publish

In its simplest form, a subscription needs only the topic to publish to and the data to publish. The AMPS client automatically constructs the necessary AMPS headers and formats the full `publish` command.

In many cases, a publisher only needs to use the basic publish command.

Header | Comment
--- | ---
    Topic
| Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted. Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.
`Data` | The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.

Table 10.1: Basic Publish

### Publish With CorrelationId

AMPS provides publishers with a header field that can be used to contain arbitrary data, the `CorrelationId`.

Header | Comment
--- | ---
    Topic
| Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted. Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.
`Data` | The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.
`CorrelationId` | The `CorrelationId` to provide on the message. AMPS provides the `CorrelationId` to subscribers. The `CorrelationId` has no significance for AMPS. The `CorrelationId` may only contain characters that are valid in base-64 encoding.

Table 10.2: Publish With CorrelationId

### Publish With Explicit SOW Key

When publishing to a SOW topic that is configured to require an explicit SOW key, the publisher needs to set the SowKey header on the message.

Header | Comment
--- | ---
    Topic
| Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted. Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.
`Data` | The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.
`SowKey` | The SOW Key to use for this message. This header is only supported for publishes to a topic that requires an explicit SOW Key.

Table 10.3: Publish with Explicit SOW Key

## Command Cookbook: Subscribing

This section presents common recipes for subscribing to a topic in AMPS using the `Command` or `Message` interfaces. This section provides information on how to configure the request to AMPS. You can adapt this information to your application and the specific interface you are using.

### Basic Subscription

In its simplest form, a subscription needs only the topic to subscribe to.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. All messages from the topic will be delivered on this subscription. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.

Table 10.4: Basic Subscription

### Basic Subscription With Options

In its simplest form, a subscription needs only the topic to subscribe to. To add options to the subscription, set the `Options` header on the `Command`.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. All messages from the topic will be delivered on this subscription. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-delimited set of options for this command. See the AMPS Command Reference for a description of supported options.

Table 10.4: Basic Subscription with Options

### Basic Subscription With Select List

In its simplest form, a subscription needs only the topic to subscribe to. To use a select list with the subscription, set the `Options` header on the `Command` to the select list specifier.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. All messages from the topic will be delivered on this subscription. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-delimited set of options for this command. See the AMPS Command Reference for a description of supported options. For example, to remove all fields except for `/id` and `/ticker`, you might use an option string of `select=[-/,+/id,+/ticker]`

Table 10.5: Basic Subscription with Select List

### Content Filtered Subscription

To provide a content filter on a subscription, set the `Filter` property on the command. The AMPS User Guide provides details on the filter syntax.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Filter` | Sets the content filter to be applied to the subscription. Only messages that match the content filter will be provided to the subscription.

Table 10.6: Content Filtered Subscription

### Conflated Subscription to a SOW Topic

To request conflation on a subscription, set the `Options` property on the command to specify the conflation interval. When the topic has a SOW (including a view or a conflated topic), there is no need to provide a `conflation_key`.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Options` | A comma-separated list of options for the command. Set the conflation interval in the options. For example, to set a conflation interval of 250 milliseconds, provide the following option:
    conflation=250ms
To set the conflation interval to 1 minute, provide an option of:
    conflation=1m

Table 10.7: Conflated Subscription to a SOW topic

### Conflated Subscription to a Topic With No SOW

To request conflation on a subscription, set the `Options` property on the command to specify the conflation interval. When the topic does not have a SOW, you must provide a `conflation_key`.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Options` | A comma-separated list of options for the command. Set the conflation interval and the fields that determine a unique message in the options. For example, to set a conflation interval of 250 milliseconds for messages that have the same value for `/id`, provide the following option:
     conflation=250ms,conflation_key=
    [/id]
To set the conflation interval to 1 minute for messages are the same as determined by a combination of `/customerId` and `/issueNumber` provide an option of:
    conflation=1m,
    conflation_key=[/customerId,/iss
    ueNumber]

Table 10.8: Conflated Subscription to a SOW topic

### Bookmark Subscription

To create a bookmark subscription, set the `Bookmark` property on the command. The value of this property can be either a specific bookmark, a timestamp, or one of the client-provided constants. The AMPS User Guide provides details on creating timestamps. Notice that the `MOST_RECENT` constant tells the AMPS client to find the appropriate message in the client bookmark store and begin the subscription at that point. In this case, the client sends that bookmark value to AMPS. The `Bookmark` option is only supported for topics that are recorded in an AMPS transaction log.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Bookmark` | Sets the point in the transaction log at which the subscription will begin. The bookmark provided can be a specific AMPS bookmark, a timestamp, or one of the client-provided constants. AMPS also accepts a comma-delimited list of bookmarks. In this case, AMPS begins the subscription from whichever of the bookmarks is earliest in the transaction log.

Table 10.9: Bookmark Subscription

### Rate Controlled Bookmark Subscription

To create a bookmark subscription, set the `Bookmark` property on the command. The value of this property can be either a specific bookmark, a timestamp, or one of the client-provided constants. The AMPS User Guide provides details on creating timestamps. Notice that the `MOST_RECENT` constant tells the AMPS client to find the appropriate message in the client bookmark store and begin the subscription at that point. In this case, the client sends that bookmark value to AMPS. The `Bookmark` option is only supported for topics that are recorded in an AMPS transaction log.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Bookmark` | Sets the point in the transaction log at which the subscription will begin. The bookmark provided can be a specific AMPS bookmark, a timestamp, or one of the client-provided constants. AMPS also accepts a comma-delimited list of bookmarks. In this case, AMPS begins the subscription from whichever of the bookmarks is earliest in the transaction log.
`Options` | A comma-separated list of options for the command. To control the rate at which AMPS delivers messages, the options for the command must include a rate specifier. For example, to specify a limit of 750 messages per second, include `rate=750` in the options string.

Table 10.10: Bookmark Subscription

### Bookmark Subscription With Completed Acknowledgement

To create a bookmark subscription, set the `Bookmark` property on the command. The value of this property can be either a specific bookmark, a timestamp, or one of the client-provided constants. The AMPS User Guide provides details on creating timestamps. Notice that the `MOST_RECENT` constant tells the AMPS client to find the appropriate message in the client bookmark store and begin the subscription at that point. In this case, the client sends that bookmark value to AMPS. The `Bookmark` option is only supported for topics that are recorded in an AMPS transaction log.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Bookmark` | Sets the point in the transaction log at which the subscription will begin. The bookmark provided can be a specific AMPS bookmark, a timestamp, or one of the client-provided constants. AMPS also accepts a comma-delimited list of bookmarks. In this case, AMPS begins the subscription from whichever of the bookmarks is earliest in the transaction log.
`Acknowledgements` | Sets the acknowledgement messages that AMPS returns. The AMPS clients typically request a `processed` acknowledgement for a subscription to verify whether the subscription succeeded. To receive a `completed` acknowledgement, which indicates the point at which replay is complete for the subscription, include `completed` in the set of acknowledgements requested. AMPS will return a message with a command type of `ack` and an ack type of `completed` at that point in the subscription.

Table 10.11: Bookmark Subscription With Completed Acknowledgement

### Bookmark Subscription With Content Filter

To create a bookmark subscription, set the `Bookmark` property on the command. The property can be either a specific bookmark, a timestamp, or one of the client-provided constants. The AMPS User Guide provides details on creating timestamps. Notice that the `MOST_RECENT` constant tells the AMPS client to find the appropriate message in the client bookmark store and begin the subscription at that point. In this case, the client sends that bookmark value to AMPS.

To add a filter to a bookmark subscription, set the `Filter` property on the command. The AMPS User Guide provides details on the filter syntax.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Bookmark` | Sets the point in the transaction log at which the subscription will begin. The bookmark provided can be a specific AMPS bookmark, a timestamp, or one of the client-provided constants. AMPS also accepts a comma-delimited list of bookmarks. In this case, AMPS begins the subscription from whichever of the bookmarks is earliest in the transaction log.
`Filter` | Sets the content filter to be applied to the subscription. Only messages that match the content filter will be provided to the subscription.

Table 10.12: Bookmark Subscription With Content Filter

### Rate Controlled Bookmark Subscription With Maximum Gap

To create a bookmark subscription, set the `Bookmark` property on the command. The value of this property can be either a specific bookmark, a timestamp, or one of the client-provided constants. The AMPS User Guide provides details on creating timestamps. Notice that the `MOST_RECENT` constant tells the AMPS client to find the appropriate message in the client bookmark store and begin the subscription at that point. In this case, the client sends that bookmark value to AMPS. The `Bookmark` option is only supported for topics that are recorded in an AMPS transaction log.

The `rate` option specifies the rate at which to replay messages, while the `max_gap` option specifies the maximum amount of time for AMPS to allow between messages.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Bookmark` | Sets the point in the transaction log at which the subscription will begin. The bookmark provided can be a specific AMPS bookmark, a timestamp, or one of the client-provided constants. AMPS also accepts a comma-delimited list of bookmarks. In this case, AMPS begins the subscription from whichever of the bookmarks is earliest in the transaction log.
`Options` | A comma-separated list of options for the command. To control the rate at which AMPS delivers messages, the options for the command must include a rate specifier. For example, to specify that AMPS replays no faster than twice the original rate, include `2X` in the options string. To specify that AMPS will go no more than 3 seconds without producing a message, regardless of the original replay timing, use a `rate_max_gap` of `3s`. To provide the options described , above, you would use the options string: `rate=2X,rate_max_gap=3s`

Table 10.13: Bookmark Subscription with Maximum Gap Between Messages

### Pausing a Bookmark Subscription

To pause a bookmark subscription, you must provide the subscription ID and the `pause` option on a subscribe command.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`SubId` | A comma-delimited list of subscription IDs to pause.
`Options` | A comma-delimited list of options for the command. To pause a subscription, the options must include `pause`.

Table 10.14: Pause a Bookmark Subscription

### Resuming a Bookmark Subscription

To resume a bookmark subscription, you must provide the subscription ID and the `resume` option on a subscribe command.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
    SubId
| A comma-delimited list of subscription IDs to resume.
    Options
| A comma-delimited list of options for the command. To resume a subscription, the options must include `resume`.

Table 10.15: Resume a Bookmark Subscription

### Replacing the Filter on a Subscription

To replace the content filter on a subscription, provide the `SubId` of the subscription to be replaced, add the `replace` option, and set the `Filter` property on the command with the new filter. The AMPS User Guide provides details on the filter syntax.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`SubId` | The identifier for the subscription to update. The `SubId` is the `CommandId` for the original `subscribe` command.
`Options` | A comma-separated list of options. To replace the filter on a subscription, include `replace` in the list of options.
`Filter` | Sets the content filter to be applied to the subscription. Only messages that match the content filter will be provided to the subscription.

Table 10.16: Replacing the Filter on a Subscription

### Subscribing to a Queue and Requesting a max_backlog

To subscribe to a queue and request a `max_backlog` greater than `1`, use the `Options` field of the `subscribe` command to set the requested `max_backlog`.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Options` | A comma-separated list of options. To request a value for the max_backlog, pass the value in the options as follows:
    max_backlog=
    NN
For example, to request a max backlog of 7, your application would pass the following option:
    max_backlog=7

Table 10.17: Requesting a max_backlog

## SOW query

This section presents common recipes for querying a SOW topic in AMPS using the `Command` or `Message` interfaces. This section provides information on how to configure the request to AMPS. You can adapt this information to your application and the specific interface you are using.

### Basic SOW Query

In its simplest form, a SOW query needs only the topic to query.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The SOW query returns all messages in the SOW. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.

Table 10.18: Basic SOW Query

### Basic SOW With Options

In its simplest form, a SOW needs only the topic to subscribe to. To add options to the subscription, set the `Options` header on the `Command`.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The SOW query returns all messages in the SOW. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-delimited set of options for this command. See the `AMPS Command Reference` for a description of supported options.

Table 10.19: Basic SOW Query with Options

### SOW Query With Ordered Results

In its simplest form, a SOW needs only the topic to subscribe to. To return the results in a specific order, provide an ordering expression in the `OrderBy` header.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The SOW query returns all messages in the SOW. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`OrderBy` | Orders the results returned as specified. Requires a comma-separated list of identifiers of the form:
    /field/[ASC | DESC]
For example, to sort in descending order by `orderDate` so that the most recent orders are first, and ascending order by `customerName` for orders with the same date, you might use a specifier such as:
    /orderDate DESC, /customerName ASC

Table 10.20: Basic SOW Query with Ordered Results

### SOW Query With TopN Results

In its simplest form, a SOW needs only the topic to subscribe to. To return only a specific number of records, provide the number of records to return in the `TopN` header.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The SOW query returns all messages in the SOW. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`TopN` | The maximum number of records to return. AMPS uses the `OrderBy` header to determine the order of the records. If no `OrderBy` header is provided, records are returned in an indeterminate order. In most cases, using an OrderBy header when you use the TopN header will guarantee that you get the records of interest.
`OrderBy` | Orders the results returned as specified. Requires a comma-separated list of identifiers of the form:
    /field/[ASC | DESC]
For example, to sort in descending order by `orderDate` so that the most recent orders are first, and ascending order by `customerName` for orders with the same date, you might use a specifier such as:
    /orderDate DESC, /customerName ASC

Table 10.21: SOW Query with TopN Results

### Content Filtered SOW Query

To provide a content filter on a SOW query, set the `Filter` property on the command. The AMPS User Guide provides details on the filter syntax.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Filter` | Sets the content filter to be applied to the query. Only messages that match the content filter will be returned in response to the query.

Table 10.22: Content Filtered SOW Query Subscription

### Historical SOW Query

To create a historical SOW query, set the `Bookmark` property on the command. The property can be either a specific bookmark or a timestamp. The AMPS User Guide provides details on creating timestamps.

This command is only supported on SOW topics that have `History` enabled.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Bookmark` | Sets the historical point in the SOW at which to query. The query returns the saved state of the records in the SOW as of the point in time specified in this header.

Table 10.23: Historical SOW Query

### Historical SOW Query With Content Filter

To create a historical SOW query, set the `Bookmark` property on the command. The property can be either a specific bookmark or a timestamp. The AMPS User Guide provides details on creating timestamps. To add a filter to the query, set the `Filter` property on the command. The AMPS User Guide provides details on the filter syntax.

This command is only supported on SOW topics that have `History` enabled.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Bookmark` | Sets the historical point in the SOW at which to query. The query returns the saved state of the records in the SOW as of the point in time specified in this header.
`Filter` | Sets the content filter to be applied to the query. Only messages that match the content filter will be provided to the query.

Table 10.24: Historical SOW Query With Content Filter

### SOW Query for Specific Records

AMPS allows a consumer to query for specific records as identified by a set of `SowKeys`. For topics where AMPS assigns the `SowKey`, the SowKey for the record is the AMPS-assigned identifier. For topics configured to require a user-provided `SowKey`, the `SowKey` for the record is the original key provided when the record was published. The AMPS User Guide provides more details on SOW keys.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`SowKeys` | A comma-delimited list of `SowKey` values. AMPS returns only the records specified in this list. For example, a valid format for a list of keys would be:
     1853097931817257202,104027799402
    01650075,22363879930342650852

Table 10.25: SOW Query by SOW Key

### SOW Query with Pagination

AMPS allows a consumer to page through records in the SOW using the `top_n` and `skip_n` options. With this approach, the application uses the `top_n` option to limit the number of records returned to a single page worth of records. The application uses the `skip_n` option to set the number of records to skip ahead to get to the page to display, and sets the `OrderBy` header to specify the ordering for the records. For example, if 10 records fit on a page, and the pages are ordered by the `ClientName` field of the records, to display the fourth page, the application would set `top_n` to `10`, `skip_n` to `30` (to skip the first three pages of records), and `OrderBy` to `/ClientName`.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The topic specified must be a literal topic name. Pagination is not supported with regular expression subscriptions.
`OrderBy` | Orders the results returned as specified. Requires a comma-separated list of identifiers of the form:
    /field/[ASC | DESC]
For example, to sort in descending order by `orderDate` so that the most recent orders are first, and ascending order by `customerName` for orders with the same date, you might use a specifier such as:
    /orderDate DESC, /customerName ASC
`Options` | An options string that sets the `top_n` and `skip_n` values for this query. For example, to skip 100 records and return the next 10 records, use an options string such as:
    top_n=10,skip_n=100

Table 10.26: SOW Query With Pagination

### Aggregated SOW Query

An aggregated SOW query is a SOW query that provides aggregation options in the options field. To add these options to the subscription, set the `Options` header on the `Command`.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The SOW query returns all messages in the SOW. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-delimited set of options for this command. For an aggregated SOW query, the options provide the `projection` and `grouping` for the aggregation. See the AMPS Command Reference for a description of supported options.

Table 10.27: Aggregated SOW Query

## SOW and Subscribe

This section presents common recipes for atomic sow and subscribe in AMPS using the `Command` or `Message` interfaces. This section provides information on how to configure the request to AMPS. You can adapt this information to your application and the specific interface you are using.

### Basic SOW and Subscribe

In its simplest form, a SOW and Subscribe needs only the topic to subscribe to.

Header | Comment
--- | ---
    Topic
| Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.

Table 10.28: Basic SOW and Subscribe

### SOW and Subscribe With Options

In its simplest form, a SOW and subscribe command needs only the topic to subscribe to. To add options to the subscription, set the `Options` header on the `Command`.

Header | Comment
--- | ---
    Topic
| Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-delimited set of options for this command. See the `AMPS Command Reference` for a full description of supported options. The most common options for this command are:
`oof` | Request out of focus notifications
`timestamp` | Include timestamps on messages

Table 10.29: Basic SOW and Subscribe with Options

### SOW and Subscribe With Select List

In its simplest form, a SOW and subscribe command needs only the topic to subscribe to. To add options to the subscription, set the `Options` header on the `Command`. To use a select list, include the specifier for the select list in the options provided.

Header | Comment
--- | ---
    Topic
| Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-delimited set of options for this command. See the `AMPS Command Reference` for a full description of supported options. For example, to remove all fields except for `id` and `ticker`, and also request out of focus notifications, you might use an options string of: `oof,select=[-/,+/id,+/ticker]`

Table 10.30: Basic SOW and Subscribe with Select List

### Content Filtered SOW and Subscribe

To provide a content filter on a SOW and Subscribe, set the `Filter` property on the command. The AMPS User Guide provides details on the filter syntax.

Header | Comment
--- | ---
    Topic
| Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Filter` | Sets the content filter to be applied to the query. Only messages that match the content filter will be returned in response to the query.

Table 10.31: Content Filtered SOW and Subscribe

### Conflated SOW and Subscribe

To request conflation on the subscription for a SOW and subscribe, set the `Options` property on the command to specify the conflation interval. When the topic has a SOW (including a view or a conflated topic), there is no need to provide a `conflation_key`.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Options` | A comma-separated list of options for the command. Set the conflation interval in the options. For example, to set a conflation interval of 250 milliseconds, provide the following option:
    conflation=250ms
To set the conflation interval to 1 minute, provide an option of:
    conflation=1m

Table 10.32: Conflated SOW and Subscribe

### Paginated SOW and Subscribe

To request a paginated subscription for a SOW and subscribe, set the `Options` property on the command to specify the number of records to return and the number of records to skip before returning records. Most paginated subscriptions also specify the `oof` option to be notified when a record is out of focus.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic specified must be a literal topic name. Pagination is not supported with regular expression subscriptions.
`OrderBy` | Specifies how to order the results within the paginated result set. If the `OrderBy` is not provided, the results are ordered by the `SowKey` for the messages.
`Options` | A comma-separated list of options for the command. Set the number of results returned with `top_n`, and the starting point within the result set with `skip_n`. For example, to display records 31-50 of the result set, you could provide the following option:
    top_n=20,skip_n=30,oof
This tells AMPS to skip the first 30 records of the result set, and then provide the top 20 records from the remaining results. Out of focus notifications will be provided.

Table 10.33: Paginated SOW and Subscribe

### Historical SOW and Subscribe

To create a historical SOW query with a subscription, set the `Bookmark` property on the command. The property can be either a specific bookmark or a timestamp. The AMPS User Guide provides details on creating timestamps. This command is only supported on SOW topics that are recorded in an AMPS transaction log.

When `History` is enabled for the SOW topic, the `Bookmark` provided must be a timestamp or a specific bookmark value, including the special values `NOW` (`0|1|`) or `EPOCH` (`0`).

If the `Bookmark` provided is a value other than NOW (`0|1|`), the SOW topic must have `History` enabled.

Header | Comment
--- | ---
    Topic
| Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Bookmark` | Sets the historical point in the SOW at which to query. The query returns the saved state of the records in the SOW as of the point in time specified in this header.

Table 10.34: Historical SOW and Subscribe

### Historical SOW and Subscribe With Content Filter

To create a historical SOW query with a subscription, set the `Bookmark` property on the command. The property can be either a specific bookmark or a timestamp. The AMPS User Guide provides details on creating timestamps. This command is only supported on SOW topics that are recorded in an AMPS transaction log. If the `Bookmark` provided is a value other than NOW (`0|1|`), the SOW topic must have `History` enabled.

Header | Comment
--- | ---
    Topic
| Sets the topic to query. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Bookmark` | Sets the historical point in the SOW at which to query. The query returns the saved state of the records in the SOW as of the point in time specified in this header.
`Filter` | Sets the content filter to be applied to the query. Only messages that match the content filter will be provided to the query.

Table 10.35: Historical SOW and Subscribe With Content Filter

### Aggregated SOW and Subscribe

An aggregated SOW and subscribe command is a SOW and subcribe command that provides aggregation options. To add these options to the sow and subscribe command, set the `Options` header on the `Command`.

Header | Comment
--- | ---
    Topic
| Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-delimited set of options for this command. For an aggregated subscription, the options provide the `projection` and `grouping` for the command. An aggregated sow and subscribe can include options in addition to the `projection` and `grouping`. The most common additional options are:
`oof` | Request out of focus notifications
`timestamp` | Include timestamp headers on messages.
See the AMPS Command Reference for a full description of supported options.

Table 10.36: Aggregated SOW and Subscribe

## Delta Publishing

This section presents common recipes for publishing to a topic in AMPS using the `Command` or `Message` interfaces. This section provides information on how to configure the request to AMPS. You can adapt this information to your application and the specific interface you are using.

### Basic Delta Publish

In its simplest form, a subscription needs only the topic to publish to and the data to publish. The AMPS client automatically constructs the necessary AMPS headers and formats the full `delta_publish` command.

In many cases, a publisher only needs to use the basic delta publish command.

Header | Comment
--- | ---
    Topic
| Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted. Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.
`Data` | The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.

Table 10.37: Basic Delta Publish

### Delta Publish With CorrelationId

AMPS provides publishers with a header field that can be used to contain arbitrary data, the `CorrelationId`. A delta publish message can be used to update the `CorrelationId` as well as the data within the message.

Header | Comment
--- | ---
    Topic
| Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted. Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.
`Data` | The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.
`CorrelationId` | The `CorrelationId` to provide on the message. AMPS provides the `CorrelationId` to subscribers. The `CorrelationId` has no significance for AMPS. The `CorrelationId` may only contain characters that are valid in base-64 encoding.

Table 10.38: Delta Publish With CorrelationId

### Delta Publish With Explicit SOW Key

When publishing to a SOW topic that is configured to require an explicit SOW key, the publisher needs to set the SowKey header on the message.

Header | Comment
--- | ---
    Topic
| Sets the topic to publish to. The topic specified must be a literal topic name. Regular expression characters in the topic name are not interpreted. Some topics in AMPS, such as views and conflated topics, cannot be published to directly. Instead, a publisher must publish to the underlying topics.
`Data` | The data to publish to the topic. The AMPS client does not interpret, escape, or validate this data: the data is provided to the server verbatim.
`SowKey` | The SOW Key to use for this message. This header is only supported for publishes to a topic that requires an explicit SOW Key.

Table 10.39: Delta Publish with Explicit SOW Key

## Delta Subscribing

This section presents common recipes for subscribing to a topic in AMPS using the `Command` or `Message` interfaces. This section provides information on how to configure the request to AMPS. You can adapt this information to your application and the specific interface you are using.

### Basic Delta Subscription

In its simplest form, a delta subscription needs only the topic to subscribe to.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. All messages from the topic will be delivered on this subscription. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.

Table 10.40: Basic Delta Subscription

### Basic Delta Subscription With Options

In its simplest form, a subscription needs only the topic to subscribe to. To add options to the subscription, set the `Options` header on the `Command`.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. All messages from the topic will be delivered on this subscription. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-delimited set of options for this command. See the `AMPS Command Reference` for a description of supported options.

Table 10.41: Basic Delta Subscription

### Content Filtered Delta Subscription

To provide a content filter on a subscription, set the `Filter` property on the command. The AMPS User Guide provides details on the filter syntax.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`Filter` | Sets the content filter to be applied to the subscription. Only messages that match the content filter will be provided to the subscription.

Table 10.42: Content Filtered Subscription

## SOW and Delta Subscribe

This section presents common recipes for atomic sow and delta subscribe in AMPS using the `Command` or `Message` interfaces. This section provides information on how to configure the request to AMPS. You can adapt this information to your application and the specific interface you are using.

### Basic SOW and Delta Subscribe

In its simplest form, a SOW and Delta Subscribe needs only the topic to subscribe to.

Header | Comment
--- | ---
    Topic
| Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.

Table 10.43: Basic SOW Query

### SOW and Delta Subscribe With Options

In its simplest form, a SOW and subscribe command needs only the topic to subscribe to. To add options to the subscription, set the `Options` header on the `Command`.

Header | Comment
--- | ---
    Topic
| Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-delimited set of options for this command. See the `AMPS Command Reference` for a full description of supported options. The most common options for this command are:
`oof` | Request out of order notifications
`timestamp` | Include timestamps on messages

Table 10.44: Basic SOW and Delta Subscribe with Options

### Content Filtered SOW and Delta Subscribe

To provide a content filter on a SOW and Delta Subscribe, set the `Filter` property on the command. The AMPS User Guide provides details on the filter syntax.

Header | Comment
--- | ---
    Topic
| Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Filter` | Sets the content filter to be applied to the query. Only messages that match the content filter will be returned in response to the query.

Table 10.45: Content Filtered SOW and Delta Subscribe

### Paginated SOW and Delta Subscribe

To request a paginated subscription for a SOW and delta subscribe, set the `Options` property on the command to specify the number of records to return and the number of records to skip before returning records. Most paginated subscriptions also specify the `oof` option to be notified when a record is out of focus.

Header | Comment
--- | ---
    Topic
| Sets the topic to subscribe to. The topic provided can be either the exact name of the topic, or a regular expression that matches the names of the topics for the subscription.
`OrderBy` | Specifies how to order the results within the paginated result set. If the `OrderBy` is not provided, the results are ordered by the `SowKey` for the messages.
`Options` | A comma-separated list of options for the command. Set the number of results returned with `top_n`, and the starting point within the result set with `skip_n`. For example, to display records 31-50 of the result set, you could provide the following option:
    top_n=20,skip_n=30,oof
This tells AMPS to skip the first 30 records of the result set, and then provide the top 20 records from the remaining results. Out of focus notifications will be provided.

Table 10.46: Paginated SOW and Delta Subscribe

### Aggregated SOW and Delta Subscribe

An aggregated SOW and delta subscribe is a SOW and delta subscribe command that provides aggregation options. To add these options ot the command, set the `Options` header on the `Command`.

Header | Comment
--- | ---
    Topic
| Sets the topic to query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-delimited set of options for this command. For an aggregated SOW and delta subscribe, the options provide the `projection` and `grouping` for the command. A SOW and delta subscribe can provide options in addition to the `projection` and `grouping`. The most common additional options are:
`oof` | Request out of order notifications
`timestamp` | Include timestamps on messages
`no_empties` | Do not send a delta message if the update does not change the value of a field.

Table 10.47: Aggregated SOW and Delta Subscribe

## SOW Delete

This section presents common recipes for sending a sow_delete command using the `Command` or `Message` interfaces. This section provides information on how to configure the request to AMPS. You can adapt this information to your application and the specific interface you are using.

### Delete All Records in a SOW

To delete all records in a SOW, provide a filter that evaluates to TRUE for every record in the SOW. By convention, 60East recommends `1=1` for the filter.

Header | Comment
--- | ---
    Topic
| Sets the topic from which to remove records.
    Filter
| A filter specifying the messages to remove. By convention, use `1=1` to remove all records in the SOW.

Table 10.48: Delete All Records in a SOW

### Delete SOW Records Matching a Filter

To delete the records that match a particular filter, provide the filter in the `sow_delete` command.

Header | Comment
--- | ---
    Topic
| Sets the topic from which to remove records.
    Filter
| A filter specifying the messages to remove.

Table 10.49: Delete All Records in a SOW

### Delete A Specific Message By Data

To delete a specific message, provide the data for the message to delete. With this form of SOW delete, AMPS deletes the message that would have been updated if the data were provided as a publish message. Notice that this form of `sow_delete` relies on the `Key` definition in the SOW configuration, and is not generally useful with explicitly-keyed SOW topics.

Header | Comment
--- | ---
    Topic
| Sets the topic from which to remove records.
    Data
| The message to remove.

Table 10.50: Delete All Records in a SOW

### Deleting Specific Messages Using Keys

To delete specific messages using SOW keys, provide the SOW keys for the message to delete.

Header | Comment
--- | ---
    Topic
| Sets the topic from which to remove records.
    SOWKeys
| A comma-delimited list of SOWKeys that specify the messages to remove.

Table 10.51: Delete All Records in a SOW

### Acknowledging Messages from a Queue

To acknowledge messages from an AMPS queue, provide the bookmarks for the messages to acknowledge. Notice that this is the only form of the sow_delete command that can acknowledge messages from a queue, and that this form of `sow_delete` is not accepted for topics that are not queue topics.

Header | Comment
--- | ---
    Topic
| Sets the topic that contains the messages to acknowledge.
    Bookmark
| A comma-delimited list of Bookmarks that specify the messages to acknowledge.

Table 10.52: Acknowledging a queue message