sow command

The sow command is used to query the contents of a previously defined topic in the SOW (including also views, queues, and conflated topics). A sow command can be used to query an entire SOW Topic, or a filter can be used to further refine the results from the SOW. For more information, see the State of the World and SOW Queries chapters in the AMPS User Guide.

Header Fields

Field	Description
cmd	Command to be executed. Value: sow
topic	The SOW topic from which the records will be queried.
ack_type	Acknowledgment type for the given command. Value is a comma separated list of one or more of the following: none, received, processed, completed or stats.
batch_size	Number of records to return in a single sow query result message. The AMPS server default value is 1. It is recommended to use a higher value, as even small increases can yield greater performance in query result delivery. Current AMPS client libraries provide a BatchSize of 10 by default. The BatchSize header only applies to a sow query.
bookmark	A bookmark specifying the historical state of the SOW to return results from. For SOW topics where historical query is enabled, AMPS returns the saved state of the SOW as of that bookmark. For SOW topics where historical query is not enabled, AMPS ignores this parameter.
cmd_id	If specified with an AMPS command requesting an acknowledgment message, all requested acknowledgment messages will contain the CommandId in the ack response header.
filter	Content filter expression. See the Content Filtering chapter in the AMPS User Guide for more information on using content filters.
order_by	Return the SOW results sorted by the specified fields. Fields are a comma-delimited list of AMPS identifiers, and may optionally include a sort specifier, ASC or DESC.
query_id	Unique identifier which is returned as part of the response delivered back to the client.
sow_keys	A comma-delimited list of SowKeys that identify the messages to return from the query.
top_n	Return up to the number of messages specified from the SOW query.

Options Field

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

Option	Description
none	This is the default Options type.
no_sowkey	Tells AMPS not to send the AMPS-generated SowKey for messages.
grouping=[keys]	For use with aggregated SOW queries. The format of this option is a comma-delimited list of XPath identifiers within brackets. For example, to aggregate entries based on their /description (producing one record in the aggregation for each distinct value in /description), the value of this option would be: [/description] This option must contain an entry for every field in the aggregated message. If there is no entry for a field in this option, that field will not appear in the aggregated message, even if the field is in the underlying message. When this option is provided, a projection must also be provided. When the topic has History enabled, this option can be used with a bookmark to aggregate the historical state of the SOW.
oof	Send on OOF message for records which have fallen out of focus from the original subscription.
projection=[fields]	For use with aggregated SOW queries. Specifies a comma-delimited set of fields to project, within brackets. Each entry has the format described in the AMPS User Guide. This option must contain an entry for every field in the aggregated message. If there is no entry for a field in this option, that field will not appear in the aggregated message, even if the field is in the underlying message. There is no default for this option. When this option is provided, a grouping must also be provided. When the topic has History enabled, this option can be used with a bookmark to aggregate the historical state of the SOW. The maximum size of this option is 64KB.
replace	Replace the subscription associated with CmdId with another subscription. When provided as part of sow_and_subscribe, AMPS runs a SOW query for the new subscription.
skip_n=n	Skips the number of messages specified before returning results. A command that provides this option must also provide a top_n option (or header) and an OrderBy header.
top_n=n	Return up to the number of messages specified from the SOW query.
select=[fields]	Specifies the fields to include in messages provided on this subscription. The contents of this option are a comma-delimited list of inclusion specifiers.
send_keys	AMPS will send the SOW keys (that is, the data fields used to identify unique messages in the SOW) back with matching messages from the SOW.
timestamp	AMPS will include a header with the time at which AMPS processed the incoming publish command for this message.

Returns

When a sow message is received, AMPS can return a received message as notification that the message has arrived. When the message filter has been processed, AMPS will return the processed acknowledgment message along with any errors that might have occurred.

The results returned by a SOW are put into a sow record group by first sending a group_begin message, followed by the matching SOW records. A group_end message is used to denote the close of query results processing.

The following table contains a listing of the acknowledgment messages supported by the sow command.

Acknowledgment	Description
none	No acknowledgment message is returned. This is the default behavior.
completed	The sow command has completed.
persisted	Not supported at this time.
processed	AMPS has compiled the filter(s) for the sow message.
received	The sow command has been received.
stats	Returns statistics related to the state of the SOW query results.

The stats message include three values in the header: Matches, TopicMatches, and the RecordsReturned. These are defined below:

TopicMatches

The total number of records compared across all matching SOW topics.

Matches

The number of records returned that match the topic regular expression and the content filter. This value can be greater than RecordsReturned in the case where the number of returned records is limited by TopN.

RecordsReturned

The total number of records returned to the client, which can be limited by the TopN header value.

Errors

Any errors which occur during a sow command are returned in the processed acknowledgment message. The error is identified in the Status header field in the acknowledgment message, and the reason given in the Reason header field.

tip

The ordering of records returned by a SOW query is undefined unless the OrderBy header on the command is provided.