Queries

At any point in time, applications can issue SOW queries to retrieve all of the messages that match a given topic and content filter. When a query is executed, AMPS will test each message in the SOW against the content filter specified and all messages matching the filter will be returned to the client. The topic can be a literal topic name or a regular expression pattern. For more information on issuing queries, please see Querying the State of the World (SOW) in the AMPS User Guide.

A SOW query is atomic. Updates that occur while the query is running, or while a client is receiving results, are not returned as part of the query.

Spark: Basic SOW Query Example

Here's how to use spark to query the current state of an AMPS SOW topic.

This example assumes that:

• You have configured a topic named test-sow in the AMPS server of message type JSON.

• The test-sow topic uses the /id field of the message to calculate the key for the topic.

To retrieve the current state of the topic, an application issues the sow command. Unlike a subscription, which stays active until it is explicitly stopped (or the application disconnects), the sow command provides results for a specific point in time. Once the results are returned, the command is over.

First, publish a message or two to the test-sow topic:

1. Open a new terminal in your Linux environment.

2. Use the following command (with AMPS_DIR set to the directory where you installed AMPS) to send a single message to AMPS:

   $ echo '{"id":1,"note":"Crank it up with a SOW!"}' | \
     $AMPS_DIR/bin/spark publish -server localhost:9007 \
     -type json -topic test-sow

3. spark automatically connects to AMPS and sends a logon command with the default credentials (the current username and an empty password). With the publish command, spark reads the message from the standard input and publishes the message to the JSON topic test-sow. The command produces output similar to the following line (the rate calculation will likely be different:

   total messages published: 1 (333.33/s)

4. When the publisher sends the message, AMPS parses the message to determine the value of the Key fields in the message, and then either inserts the message for that key, or overwrites the existing message with that key.

5. You can publish any number of messages this way. Each distinct id value will create a distinct record in the topic.

Next, retrieve the current contents of the topic:

1. Open a new terminal in your Linux environment.

2. Use the following command (with AMPS_DIR set to the directory where you installed AMPS) to retrieve the contents of the topic:

   $ $AMPS_DIR/bin/spark sow -server localhost:9007 \
     -type json -topic test-sow

3. spark automatically connects to AMPS and sends a logon command with the default credentials (the current username and an empty password). spark then sends the sow command to AMPS. This command requests the current contents of the test-sow topic. Since the command is finished once the query is complete, spark will exit when the query results are complete.

4. spark shows the current contents of the topic. Notice that the output is strictly the message data, separated by newline characters. spark does not show any of the metadata for a message.