# 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 messages. 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 command. 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 command, use the `execute` method to send the command 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 typically does not 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 the AMPS 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.

Important

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

Command: `publish`

In its simplest form, a publish 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

## 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

Command: `subscribe`

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

### 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

### 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

### Subscription with Content Filter

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 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 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 specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-separated list of options for the command. Set the conflation interval in the options. For example, to set a conflation interval of 250 milliseconds, provide the following option:
    conflation=250ms
To set the conflation interval to 1 minute, provide an option of:
    conflation=1m

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 specified can be the literal topic name, or a regular expression that matches multiple topics.
`Options` | A comma-separated list of options for the command. Set the conflation interval 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 that 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 with no SOW

### 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 specified can be the literal topic name, or a regular expression that matches multiple topics.
`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.

To manage the message delivery rate to a bookmark subscription, set the `rate` option specifying the rate at which to replay messages.

Header | Comment
--- | ---
Topic | Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`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

### 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 `rate_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 specified can be the literal topic name, or a regular expression that matches multiple topics.
`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.11: Bookmark Subscription with Maximum Gap Between Messages

### Bookmark Subscription with Completed Acknowledgment

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.

To receive acknowledgment messages to a bookmark subscription, set the `AckType` on the command specifying the type of acknowledgments to receive. In this case, be sure to include the `completed` type.

Header | Comment
--- | ---
Topic | Sets the topic to subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`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.
`AckType` | Sets the acknowledgment messages that AMPS returns. The AMPS clients typically request a `processed` acknowledgment for a subscription to verify whether the subscription succeeded. To receive a `completed` acknowledgment, which indicates the point at which replay is complete for the subscription, include `completed` in the set of acknowledgments 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.12: Bookmark Subscription With Completed Acknowledgment

### 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 specified can be the literal topic name, or a regular expression that matches multiple topics.
`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.13: Bookmark Subscription With Content Filter

### 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 specified can be the literal topic name, or a regular expression that matches multiple topics.
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 specified can be the literal topic name, or a regular expression that matches multiple topics.
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 specified can be the literal topic name, or a regular expression that matches multiple topics.
`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 specified can be the literal topic name, or a regular expression that matches multiple topics.
`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

Command: `sow`

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

### SOW Query with Options

In its simplest form, a SOW query needs only the topic to query. To add options to the query, 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 query needs only the topic to query. 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 query needs only the topic to query. 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 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

### SOW Query with Content Filter

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

Command: `sow_and_subscribe`

In its simplest form, a SOW and Subscribe command needs only the topic to query and 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 query and 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 query and subscribe to. To add options to the subscription, set the `Options` header on the `Command`. To use a select list, include the specifier for the select list in the options provided.

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

### SOW and Subscribe with Content Filter

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

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 command, set the `Options` property on the command to specify the conflation interval. When the topic has a SOW (including a view or a conflated topic), there is no need to provide a `conflation_key`.

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-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 command, set the `Options` property on the command to specify the number of records to return and the number of records to skip before returning records. Most paginated subscriptions also specify the `oof` option to be notified when a record is out of focus.

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

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

Table 10.35: Historical SOW and Subscribe With Content Filter

### Aggregated SOW and Subscribe

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

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

Command: `delta_publish`

In its simplest form, a delta publish 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

Command: `delta_subscribe`

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

### Delta Subscription with Options

In its simplest form, a delta 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

### Delta Subscription with Content Filter

To provide a content filter on a delta 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 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 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

Command: `sow_and_delta_subscribe`

In its simplest form, a SOW and Delta Subscribe needs only the topic to query and 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 Delta Subscribe needs only the topic to query and 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.44: Basic SOW and Delta Subscribe with Options

### SOW and Delta Subscribe with Content Filter

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 query and subscribe to. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
`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 command that provides aggregation options. To add these options to 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 focus 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

Command: `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 Records Matching a Filter

### 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 a Specific Message

### Delete 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 SOW Keys that specify the messages to remove.

Table 10.51: Delete Specific Messages using SOW Keys

### Acknowledge 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: Acknowledge a Queue Message