Query and Subscribe
Last updated
AMPS Server Documentation 5.3.5 (Early Access)
Last updated
AMPS has a special command that will execute a query and place a subscription at the same time to prevent a gap between the query and subscription where messages can be lost. Without a command like this, it is difficult to reproduce the SOW state locally on a client without creating complex code to reconcile incoming messages and state.
For example, this command is useful for recreating part of the SOW in a local cache and keeping it up to date. Without a special command to place the query and subscription at the same moment, a client is left with two options:
Issue the query request, process the query results, and then place the subscription, which misses any records published between the time when the query and subscription were placed;
or
Place the subscription and then issue the query request, which could send messages placed between the subscription and query twice.
Instead of requiring every program to work around these options, the AMPS sow_and_subscribe command allows clients to place a query and get the streaming updates to matching messages in a single command.
In a sow_and_subscribe command, AMPS behaves as if the SOW command and subscription are placed at the exact same moment. The SOW query will be sent before any messages from the subscription are sent to the client. Additionally, any new publishes that come into AMPS that match the sow_and_subscribe filtering criteria and come in after the query started will be sent after the query finishes (and the query will not include those messages.) As with a simple SOW query, any other messages that arrive for the client while the SOW query is running will also be delivered after the query results.
AMPS allows a sow_and_subscribe command on topics that do not have a SOW enabled. In this case, AMPS simply returns no messages between group_begin and group_end.
The sequence diagram below illustrates the message flow for sow_and_subscribe commands:
For topics that have History configured, AMPS SOW Query and Subscribe also allows you to begin the subscription with a historical SOW query. For historical SOW queries, the subscription begins at the point of the query with the results of the SOW query. The subscription then replays messages from the transaction log. Once messages from the transaction log have been replayed, the subscription then provides messages as AMPS publishes them.
In effect, a SOW Query and Subscribe with a historical query allows you to recreate the client state and processing as though the client had issued a SOW Query and Subscribe at the point in time of the historical query.
A historical SOW and Subscribe requires that the SOW topic is recorded in the transaction log and that history is enabled on the SOW. If history is not enabled for the topic, a sow_and_subscribe command returns the current state of the SOW and the subscription begins atomically at the point in time when AMPS processes the command.
A sow_and_subscribe command can include the conflation interval and conflation key options for server side conflation (as described in ), just as a regular subscription can. When the command requests conflation, the results of the SOW query are not conflated. Conflation only applies to the subscription.
As described in , AMPS allows you to replace an existing subscription. When the subscription is entered with the sow_and_subscribe command, AMPS will re-run the SOW query delivering the messages that are in scope with the new filter but which were not previously delivered. If the subscription requests out-of-focus (OOF) messages, AMPS will deliver out of focus messages for messages that matched the previous filter but do not match the new filter. As with the initial Query and Subscribe, AMPS guarantees to deliver any changes to the SOW that match the filter and occur after the point of the query.
