sow
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 |
| Command to be executed.
Value: |
| The SOW topic from which the records will be queried. |
| Acknowledgment type for the given command.
Value is a comma separated list of one or more of the following: |
| Number of records to return in a single |
| 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. |
| If specified with an AMPS command requesting an acknowledgment message, all requested acknowledgment messages will contain the |
| Content filter expression. See the Content Filtering chapter in the AMPS User Guide for more information on using content filters. |
| 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, |
| Unique identifier which is returned as part of the response delivered back to the client. |
| A comma-delimited list of |
| 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 |
| This is the default |
| Tells AMPS not to send the AMPS-generated |
| 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 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 When the topic has |
| Send on |
| 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 When the topic has The maximum size of this option is 64KB. |
| Replace the subscription associated with When provided as part of |
| Skips the number of messages specified before returning results. A command that provides this option must also provide a |
| Return up to the number of messages specified from the SOW query. |
| Specifies the fields to include in messages provided on this subscription. The contents of this option are a comma-delimited list of inclusion specifiers. |
| 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. |
| 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 |
| No acknowledgment message is returned. This is the default behavior. |
| The |
| Not supported at this time. |
| AMPS has compiled the filter(s) for the |
| The |
| 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.
The ordering of records returned by a SOW query is undefined unless the OrderBy
header on the command is provided.
Last updated