The AMPS State-of-the-World (SOW) depends on being able to identify distinct updates to a message. AMPS does this by creating a SOW key for each message: subsequent updates that have the same key are updates to the same message. In many cases, it’s convenient to have AMPS determine the SOW key for a message based on the contents of the message.

That’s not the only way to get a SOW key, though. An explicit SOW key allows a publisher to specify the SOW key of a message at the time the message is published. AMPS does not try to interpret the data within the message to generate a SOW key, or to determine if the message is unique. Instead, AMPS relies only on the provided SOW key to determine the identity and uniqueness of the message. This can be useful for a variety of different purposes.

Common Uses

There are two common uses for explicitly defining your own SOW keys that I would like to mention.

The first common use is for binary message types. Explicit SOW keys are necessary for binary messages because AMPS will not attempt to parse a binary message, and therefore cannot obtain a SOW key from within the message. With that in mind, explicit SOW keys are the only way to build a SOW topic that contains binary messages.

The second common use of explicit SOW keys is situations where a message does not contain a unique key, and you aren’t able to add one to the message itself. In this situation, you would give AMPS a different key for each unique message published.

Though these may not be the only situation that an explicit SOW key could be used, they are the most common.

Considerations When Generating SOW Keys

There are a few things to keep in mind when generating your SOW keys:

1. All publishers should use a consistent method for generating SOW keys. This is to guarantee that all publishers can update the proper message in the SOW.
2. SOW keys must contain only characters that are valid in Base64 encoding.
3. The application must ensure that messages intended to be logically different do not have the same SOW key.

As long as you are able to meet this criteria, your keys can be anything that you want.

Configuring AMPS

Configuring AMPS to use explicit SOW keys is quite similar to configuring any other topic in the SOW, with one important difference. The Key option will not be provided. Here is an example a SOW configured to use explicit keys:

<SOW>
    <TopicDefinition>
        <Topic>Foo</Topic>
        <FileName>path/to/sow/Foo.sow</FileName>
        <MessageType>json</MessageType>
    </TopicDefinition>
</SOW>

If you provide a Key in the configuration, any explicit SOW key set on a publish message will be ignored and the configured Key will be applied.

Publishing the SOW Key

Explicit SOW keys are set on a publish message using the Command Interface. This is done by creating a publish Command object, then calling set_sow_key on that object. A python example of this would be as follows.

# Let's build a simple publish Command
cmd = AMPS.Command("publish").set_topic(topic).set_data(data)

# Now let's set the SOW key
cmd.set_sow_key(key)

# and finally send it, using
# execute_async with no handler
# for efficiency
client.execute_async(cmd, None)

That’s all there is to it! Once the message is published, AMPS will handle the rest.

SOW Queries

Data published with an explicit SOW key can be queried with a content filter just like any other non-explicit SOW topic. You can also query this data using the SOW key that you provided. In order to issue a query by the explicit SOW key, you build a SOW Command and set the SOW key on that Command. Here is an example of this:

cmd = AMPS.Command("sow")
cmd.set_sow_key(key).set_topic(topic)
for m in client1.execute(cmd):
    print "%s: %s" % (m.get_sow_key(), m.get_data())

Though this might not be useful in every case, the query will be faster for those applications that need it. If your application only needs to store and retrieve values using a single key, using an explicit SOW key is the most efficient approach.

Further Reading

For more details, see How Does the State of the World Work? and the section on SOW Keys in the AMPS User Guide.

Closing Thoughts

Using an explicit SOW key can be useful when you have no way of identifying a key within the message itself. This is particularly the case with Binary messages, but it may have many other uses. As long as your application has a way of consistently generating a unique SOW key for each unique message, then setting an explicit SOW key might be for you!