Configuring Views in a SOW

This section lists the parameters for defining a View within the SOW section of an AMPS configuration file. Expand each item for more details.

For backward compatibility, AMPS accepts ViewDefinition as a synonym for View.

Name (required)

Defines the topic name for this view.

If no Name is provided, AMPS accepts Topic as a synonym for Name to provide compatibility with versions of AMPS previous to 5.0.

MessageType (required)

The message type of the view. This does not need to be the same type as any of the topics in the aggregation, but does need to be a message type that supports views.

The message type must be one of the message types configured for the instance. AMPS includes fix, xml, nvfix, json, bson and bflat message types with full support for views. You can also use any custom message type defined for the configuration file, provided that the message type supports views.

Notice that the binary message type does not specify a fixed format for the message contents, so that message type cannot be used in a view.

Other message types provided with AMPS may have limitations in their support for views. See the Message Types section for a discussion of the limitations.

UnderlyingTopic (required)

Defines the SOW topic or topics on which this view is based.

This element can contain a single topic name, or any number of Join elements.

Projection/Field (required)

Defines what the view will contain.

This element can be specified multiple times to compose a complex view. Complex expressions that use aggregation functions and conditional branching can also be used.

Grouping/Field (required)

Defines how the records in the underlying topic will be grouped.

This is analogous to a SQL GROUP BY clause.

KeyDomain

The seed value for SowKeys used within this topic.

The default is the topic name, but it can be changed to a string value to unify SowKey values between different topics.

Join

Within an UnderlyingTopic, each Join specifies two topics to join together to create the view, as well as the relationship between those topics.

An UnderlyingTopic can have any number of Join specifications. For more information on Join specifications, see the Multiple Topic Aggregation section.

Conflation

Defines whether AMPS will attempt to conflate updates to the view.

This item accepts two values:

• none - No conflation. AMPS fully processes every update to the view, in publication order.

• inline - Conflation is active. AMPS conflates multiple updates to the same underlying record where possible. See the Inline Update Conflation section for details.

Default: none

Filter

Defines a filter for the view. When provided, only messages from the UnderlyingTopic that match this filter will be included in the view.

This option is only valid when the view uses a single UnderlyingTopic. When the view contains a Join specification, this option may not be used.

Default: No filter, which includes all messages from the UnderlyingTopic.

HashIndex

AMPS provides the ability to do fast query lookup for records in a view based on specific fields.

When one or more HashIndex elements are provided, AMPS creates a hash index for the fields specified in the element. These indexes are created on startup, and are kept up to date as records are added, removed, and updated.

The HashIndex element contains a Key element for each field in the hash index.

AMPS uses a hash index when a query uses an exact string match for all of the fields in the index. AMPS does not use hash indexes for range queries or regular expressions, or for numeric comparisons.

AMPS automatically creates a hash index for the fields specified in the Grouping for the view.

JoinNullEquivalency

Specifies whether the Join expressions in this view should consider NULL values to be equivalent.

When this is enabled, missing values, empty strings, and NULL values will be considered to match in a Join expression.

When this is disabled, these values will not match.

Default: disabled

FileName

File location to store view data. Unused in this version of AMPS.

Below is an example of a SOW configuration, that shows different approaches to defining a View.

<SOW>
    <!-- Single topic aggregation. -->
    <Topic>
        <Topic>/ett/order</Topic>
        <MessageType>fix</MessageType>
        <Key>/orderId</Key>
    </Topic>
    <View>
        <MessageType>nvfix</MessageType>
        <Topic>TOTAL_VALUE</Topic>
        <UnderlyingTopic>/ett/order</UnderlyingTopic>
        <Projection>
            <Field>/109</Field>
            <Field>SUM(/14 * /6) AS /71406</Field>
        </Projection>
        <Grouping>
            <Field>/109</Field>
        </Grouping>
    </View>

    <!-- Single topic aggregation with filter. -->
    <Topic>
        <Name>orders</Name>
        <MessageType>json</MessageType>
        <Key>/orderId</Key>
        <FileName>./sow/%n.sow</FileName>
    </Topic>
    <View>
        <Name>CompleteByRegion</Name>
        <UnderlyingTopic>orders</UnderlyingTopic>
        <MessageType>json</MessageType>
        <Projection>
            <Field>COUNT(/orderId) AS /completedOrders</Field>
            <Field>/region AS /region</Field>
        </Projection>
        <Grouping>
            <Field>/region</Field>
        </Grouping>
        <Filter>/status = 'complete'</Filter>
    </View>

  <!-- Single topic aggregation with a hash index
       for faster query. -->
  <Topic>
      <Name>source-for-hash-sample</Name>
      <MessageType>json</MessageType>
      <Key>/id</Key>
      <FileName>./sow/%n.sow</FileName>
  </Topic>
  <View>
      <Name>hash-sample-view</Name>
      <MessageType>json</MessageType>
      <UnderlyingTopic>source-for-hash-sample</UnderlyingTopic>
      <Projection>
         <Field>SUM(/qty) as /quantity</Field>
         <Field>/customerName</Field>
         <Field>/orderType</Field>
       </Projection>
       <Grouping>
         <Field>/customerName</Field>
         <Field>/orderType</Field>
       </Grouping>
       <!-- Provide fast query for exact matches on
            *either* name or orderType. -->
       <HashIndex>
          <Key>/name</Key>
       </HashIndex>
       <HashIndex>
          <Key>/orderType</Key>
       </HashIndex>
   </View>

    <!-- Project from one message type to another. -->
    <Topic>
        <Name>example</Name>
        <MessageType>json</MessageType>
        <Key>/id</Key>
        <FileName>./sow/%n.sow</FileName>
    </Topic>
    <View>
        <!-- Notice that the nvfix topic named 'example' is not the
             same topic as the json topic named 'example'. -->
        <Name>example</Name>
        <MessageType>nvfix</MessageType>
        <UnderlyingTopic>[json].[example]</UnderlyingTopic>
        <Projection>
            <Field>[json].[example]./id AS /id</Field>
        </Projection>
        <Grouping>
            <Field>[json].[example]./id</Field>
        </Grouping>
    </View>

   <!-- JOIN topics -->
   <Topic>
        <Name>ORDERS</Name>
        <MessageType>nvfix</MessageType>
        <Key>/OrderID</Key>
        <FileName>./sow/%n.sow</FileName>
    </Topic>
    <Topic>
        <Name>COMPANIES</Name>
        <MessageType>nvfix</MessageType>
        <Key>/CompanyId</Key>
        <FileName>./sow/%n.sow</FileName>
    </Topic>
    <View>
        <Name>TOTAL_COMPANY_VOLUME</Name>
        <UnderlyingTopic>
            <Join>[ORDERS]./Tick = [COMPANIES]./Tick</Join>
        </UnderlyingTopic>
        <MessageType>nvfix</MessageType>
        <Projection>
            <Field>[COMPANIES]./CompanyId</Field>
            <Field>[COMPANIES]./Tick</Field>
            <Field>[COMPANIES]./Name</Field>
            <Field>SUM([ORDERS]./Shares) AS /TotalVolume</Field>
        </Projection>
        <Grouping>
            <Field>[ORDERS]./Tick</Field>
        </Grouping>
    </View>
</SOW>