Cookbook: SOW

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.

Command: sow

Basic SOW Query

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

Header	Comment
Topic (required)	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.

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 (required)	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 sow section for a description of supported 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 (required)	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

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 top_n option.

Header	Comment
Topic (required)	Sets the topic to query. The topic specified can be the literal topic name, or a regular expression that matches multiple topics.
Options	The top_n option specifies the maximum number of records to return from the query. 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. For example, to specify that the first ten records are returned, you would use the option top_n=10
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

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 (required)	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.

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 (required)	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.

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 (required)	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.

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 (required)	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

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 (required)	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

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 (required)	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 sow section for a description of supported options.