Aggregated Subscriptions

In addition to precomputed views and aggregates, AMPS provides the ability for the server to compute an aggregation for an individual subscription. When an application requests an aggregated subscription, rather than providing messages for the subscription verbatim, the AMPS server will calculate the requested aggregates and produce a message that contains the aggregated data.

Most of the time, AMPS applications use views to provide aggregation, as described in the section on Understanding Views. AMPS views are shared across subscriptions, and are calculated once, when a message updates a view, regardless of the number of subscribers that subscribe to the view. AMPS provides aggregated subscriptions as a way to do ad hoc aggregation in cases where a specific aggregate is only needed for a short period time, will only be used by a single subscriber, or must be provided before the server can be restarted with a defined view. If the aggregation is frequently used, or if multiple subscribers will use the aggregation, consider using a view rather than an aggregated subscription.

To request an aggregated subscription, the subscriber provides a definition of the fields to project and the grouping to apply with each subscription. AMPS performs the aggregation and constructs the specified message before delivering the message.

For example, imagine a topic in the SOW that uses the /id field to create the SOW key. The topic contains the following messages:

{ "id":1, "tickerId" : "IBM", "price" : 150.34 }
{ "id":2, "tickerId" : "IBM", "price" : 149.76 }
{ "id":3, "tickerId" : "IBM", "price" : 149.32 }
{ "id":4, "tickerId" : "IBM", "price" : 151.10 }

A subscriber enters a SOW query with the following options:

projection=[MAX(/price) AS /max,/tickerId as /ticker],grouping=[/tickerId]

AMPS aggregates the messages in the SOW and delivers the following projected record:

{ "ticker" : "IBM", "max" : 151.10 }

Aggregated subscriptions are supported for commands that use the SOW: sow, sow_and_subscribe, and sow_and_delta_subscribe. However, there are limitations on some variants of the commands, as described in the following sections.

The memory consumed to maintain an aggregated subscription is counted as part of the total memory for the client that submitted the subscription when considering the MessageMemoryLimit for that client.

When to Use Aggregated Subscriptions

Aggregated subscriptions require AMPS to compute the aggregate for each subscription individually, at the time that messages are processed for the subscription. In addition, for aggregated subscriptions, the current state of the aggregation is retained for each subscription.

In cases where more than one subscriber is using the same aggregation, a View is more efficient: each record in the view is only computed once, saving CPU cycles, and ongoing updates for the record are only stored once, requiring less memory. Likewise, if the aggregation uses more than one topic or aggregates messages of a different type than the final result, you must configure a View on the server.

An aggregated subscription could be more appropriate than a persistent view if one or more of the following is true:

• A subscription has unique and unpredictable aggregation needs. For example, if no other subscription is computing a given aggregation, and it is not possible to predict in advance the aggregates to compute, then per-subscription aggregation is a good solution.

• The application is under development and iterating quickly. It can be convenient to use aggregated subscriptions while developing aggregate definitions that will be eventually provided as view topics.

• The persistent view is expensive and seldom needed. For example, if an aggregation is memory-intensive and only needed once a week at a time when the instance is otherwise lightly-used, the overall memory usage of the AMPS instance may be reduced during the rest of the week by using an aggregated subscription.

The considerations above are general guidance to help you consider options between per-subscription aggregation and a persistent view. In general, if it is possible to use an AMPS view for a given aggregation task and that view will be frequently used, a view is often the best option. If a view cannot be used (because the aggregation is not known in advance) or the view would seldom be used, an aggregated subscription may be a better option.

Requesting an Aggregated Subscription

To request an aggregated subscription, set the following options on the subscription:

Option	Description
projection=[field specifications]	Specifies a comma-delimited set of fields to project, within brackets. Each entry has the format described in Constructing View Fields. This option must contain an entry for every field in the aggregated message. If there is no entry for a field in this option, that field will not appear in the aggregated message, even if the field is in the underlying message. For example, to project the total value of orders for a specific item, you might take the sum of the /price multiplied by the /quantity for each item, along with the original /description, as follows: projection=[SUM(/price * /quantity) AS /total, /description] When a field appears in the projection option, but is not part of a grouping clause or used in an aggregation function, the message will have the value of that field in the last message processed by AMPS. There is no default for this option. When this option is provided, a grouping must also be provided.
grouping=[keys]	For an aggregated subscription, the format of this option is a comma-delimited list of XPath identifiers within brackets. For example, to aggregate entries based on their /description (producing one record in the aggregation for each distinct value in /description), you would use the following option: grouping=[/description] There is no default for this option. When this option is provided, a projection must also be provided.

For example, to request a count, by customer, of the order records stored in a topic in the SOW, you could use the following options:

projection=[COUNT(/orderId)AS /orderCount, /customer AS /customer],grouping=[/customer]

Considerations for Aggregated Subscriptions

When planning to use an aggregated subscription, the following considerations apply:

• The source of an aggregated subscription is a single topic, of the same message type as will be produced by the aggregation. The topic for the subscription must not be a regular expression.

• The topic for the subscription must be a topic in the SOW. This includes views and the SOW view of a queue.

• When subscribing to a queue, an aggregated subscription does not remove messages from the queue. Like a view definition with the queue as an underlying topic, an aggregated subscription browses the queue without taking messages from the queue.

• Filters for the subscription apply to the original messages, not the results of the projection. A filter for an aggregated subscription is equivalent to the Filter element in a View definition rather than a filter for a subscription that uses the view.

• A subscription that uses per-subscription aggregation does not support the replace option except for changing pagination options.

• An aggregated subscription cannot be a bookmark subscription. That is, replay from the transaction log does not support aggregated subscriptions.

• Select lists cannot be used with aggregated subscriptions.