Overview of SOW Queries
Last updated
Last updated
Copyright 2013-2024 60East Technologies, Inc.
A client can issue a query by sending AMPS a sow command and specifying an AMPS topic. Optionally a filter can be used to further refine the query results. AMPS also allows you to restrict the query to a specific set of messages identified by a set of SowKeys. When AMPS receives the sow command request, it will validate the filter and start executing the query. When returning a query result back to the client, AMPS will package the sow results into a sow record group by first sending a group_begin message followed by the matching SOW records, if any, and finally indicating that all records have been sent by terminating with a group_end message. AMPS returns the results for a SOW query in a single, atomic operation. Any messages for the client that arrive during the SOW query are delivered after the SOW results.
AMPS treats queries as a single, atomic operation. All results from a query are sent to a client before the results of any subsequent commands. Use care when issuing queries that return a result set large enough to take several seconds or more to transmit over the network.
When planning for large queries, please see the information on how AMPS handles a situation where messages are produced faster than the client or network can consume them. This is discussed in the section on Slow Client mitigation.
The sequence diagram below illustrates the message flow for a SOW query.
For purposes of correlating a query request to its result, each query command can specify a QueryId. The QueryId specified will be returned as part of the response that is delivered back to the client. The group_begin and group_end messages will have the QueryId attribute set to the value provided by the client. The client specified QueryId is what the client can use to correlate query commands and responses coming from the AMPS engine.
AMPS does not allow a sow command on topics that do not have a SOW enabled. If a client queries a topic that does not have a SOW enabled, AMPS returns an error.
The ordering of records returned by a SOW query is undefined by default. You can include an OrderBy parameter on the query to specify a particular ordering based on the contents of the messages.
