Retrieving Part of a Message

AMPS has the ability to allow a subscriber to retrieve only the relevant parts of a message, in the same way that a SQL query can retrieve only specified fields from a table. For example, consider a topic that stores an event ID, a short description, and a detailed event record. A UI that presents an overview of the contents of the topic might only need the event ID and short description to present a high-level view of the topic contents, while retrieving the detailed event record when a user explicitly requests the details for a specific record.

With select lists, AMPS allows an individual subscription to control which fields are retrieved from a subscription or query. In the example above, the subscription would include a select list that requests that AMPS provide the event ID and description, while excluding any other field. To do this, the application would include the following option on the command used to retrieve data for the overview: select=[-/,+/event_id,+/description]

When provided by an application as a part of a command to AMPS, a select list is applied after any content filtering is applied. The select list specifies the contents of the subscription, but does not affect the underlying messages, and the contents of the subscription select list do not affect filter evaluation or query results.

To use a select list, the message type format must allow partial serialization of messages. Message formats that require a full message, or that interpret missing fields as having a specific value, cannot be used with select lists, since a partial message would either create an invalid message, or change the way the data in the message is interpreted.

Creating Select Lists

As mentioned above, to provide a select list on a command, add the keyword select and a comma-delimited list of field directives to the options for a subscription or query in AMPS.

Each field directive is a combination of an inclusion specifier and an AMPS identifier.

For example, the field directive +/event_id has an inclusion_specifier of + and the AMPS identifier of /event_id. This field directive specifies that the /event_id field is included in the message returned to the subscriber.

AMPS recognizes the following inclusion specifier values:

Specifier	Meaning
-	Explicitly exclude the field for the identifier immediately following.
+	Explicitly include the field for the identifier immediately following.

Identifiers for individual fields follow the syntax described in the Identifiers section.

For select lists, AMPS also recognizes the special field directive of -/ to specify that all fields should be excluded and the special field directive of +/ to specify that all fields should be included.

If no field directive in the select list applies to a given field in a message, that field is included in the message.

If a field is covered by multiple field directives, AMPS respects the most specific field directive. In other words, a select list that contains the field directives +/,-/details will include all fields except the details field. A select list that contains the field directives -/event,+/event/description will include the /event/description subfield, but no other contents of the /event field. (If an identifier is provided twice in the same select list, AMPS uses the first field specifier that contains the identifier.)

With select lists, AMPS does not create fields that are not in the original message. This means that if the select list requests a field that does not exist in the original message, the message delivered to the subscriber will not contain that field.

Notice that a select list only changes how a message is delivered to the subscriber that the select list applies to. The original message is unaffected, and the complete message is delivered to any subscriber that does not specify a select list.

AMPS contains related functionality that may be more appropriate for some applications:

• To modify a message as it is published to AMPS, use Enrichment and Preprocessing. With those features, the original publish message is modified and the modified message is stored in AMPS and sent to all subscribers.

• AMPS also offers the ability to create a view of a set of messages that aggregates data across a set of messages and produces a result (for example, the total value of all open orders for each customer). See the chapter on Aggregating and Analyzing Data in AMPS for more details.

Select List Examples

For example, consider an original message like the following JSON document:

{ "id": 42,
  "name":"Arthur",
  "day":"Thursday",
  "complaint":"Unannounced construction in neighborhood.",
  "pocket_contents":
        { "left":"twine",
          "right":"towel" }
}

An application might only need to see the id and complaint description. To retrieve just those fields of a message, the application could add the following option to the command that retrieves the message:

select=[-/,+/id,+/complaint]

This select list tells AMPS to remove all fields from the message except for the /id field and the /complaint field. With this select list, the message above will be delivered as:

{ "id": 42,
  "complaint":"Unannounced construction in neighborhood."
}

Likewise, an application could want to know the name of the person making the complaint and the contents of that person's left pocket:

select=[-/,+/name,+/pocket_contents/left]

From the original message, the result of providing this select list would be:

{ "name": "Arthur",
  "pocket_contents":
        { "left":"twine"}
}

Last, consider an application that wants to see everything in the message except the pocket_contents. That application could provide an option such as:

select=[-/pocket_contents]

With that specifier, AMPS provides any field in the message except the pocket_contents, producing the following result:

{ "id": 42,
  "name":"Arthur",
  "day":"Thursday",
  "complaint":"Unannounced construction in neighborhood."
}

Select lists are not available for struct message types, since these types represent a single, contiguous block of memory (and, therefore, cannot meaningfully have omitted fields).