Integrating NATS Subjects with AMPS

This page assumes a bridge, adapter, or application republishes NATS messages into AMPS while preserving the original NATS subject in the AMPS topic name or in a message field. That approach preserves familiar NATS subject hierarchies while using AMPS as the queryable, stateful layer for dashboards, operational tooling, and interactive applications. The same conventions also keep a straightforward path for applications that later publish directly into AMPS.

Where NATS and AMPS Overlap

NATS and AMPS both work well with dot-delimited subject names. AMPS can preserve NATS wildcard patterns by using TopicMatchingPolicy set to nats as the instance default or as a local override on the imported NATS namespace. Subscriptions and SOW queries can also use topic_matching_policy=nats, and any TOPIC_MATCH predicate in the same command filter uses NATS wildcard rules.

That overlap is useful when a team wants to preserve NATS subjects such as time.us.east or orders.eu.priority while adding:

• Persistent current state through the State of the World (SOW)
• Atomic initial load plus live updates through sow_and_subscribe
• Lower-bandwidth browser updates through sow_and_delta_subscribe
• Server-managed rollups with Views and Unions
• UI-friendly refresh rates with ConflatedTopics

NATS Patterns Compared to Default AMPS PCRE

The default AMPS topic matching policy is pcre, which uses full regular expressions. NATS syntax is simpler and maps directly to subject semantics.

NATS Pattern	Meaning	Representative PCRE Equivalent
time.*.east	Match exactly one token between time and east	^time\.[^.]+\.east$
time.us.>	Match one or more trailing tokens below time.us	^time\.us\.[^.]+(\.[^.]+)*$
>	Match every subject	.+

Under nats, * matches exactly one token and > matches one or more trailing tokens. The > wildcard must appear as the last token in the pattern. Constructs such as ^, $, and .* are PCRE syntax, not NATS syntax.

Recommended AMPS Design

For most NATS integrations, the cleanest AMPS design looks like this:

1. Preserve the original NATS subject when the bridge publishes into AMPS.
2. Keep the instance default at pcre unless most of the instance uses NATS semantics. For imported subject spaces, add TopicMatchingPolicy set to nats beside each Pattern or UnderlyingTopic that should use NATS rules.
3. Capture the relevant subject space into a Pattern topic so AMPS maintains current state per logical subject without a separate SOW topic definition for each subject.
4. Build a Union whose UnderlyingTopic repeats that same pattern expression when dashboards or downstream services need one consolidated SOW topic.
5. Build Views and ConflatedTopics on top of that union for operator dashboards and UI refresh.

This layout works well for phased coexistence and for direct AMPS adoption later because the subject model presented to applications stays stable.

info

A Pattern topic cannot be used directly as the underlying source for a View. Use a Union first, with the same pattern expression in the Union UnderlyingTopic, then place the View or ConflatedTopic on top of the Union.

Sample Configuration

The following example keeps the instance default at pcre, preserves a NATS telemetry namespace inside AMPS with local NATS overrides, rolls it into a single SOW topic for analytics, and then produces a dashboard-oriented topic:

<AMPSConfig>
  <Name>nats-observability</Name>
  <TopicMatchingPolicy>pcre</TopicMatchingPolicy>

  <SOW>
    <Topic>
      <Name>nats-telemetry-space</Name>
      <Pattern>time.us.></Pattern>
      <TopicMatchingPolicy>nats</TopicMatchingPolicy>
      <MessageType>json</MessageType>
      <Key>/sensorId</Key>
      <FileName>./sow/%n.sow</FileName>
    </Topic>

    <Union>
      <Name>nats-telemetry-union</Name>
      <MessageType>json</MessageType>
      <UnderlyingTopic>time.us.></UnderlyingTopic>
      <TopicMatchingPolicy>nats</TopicMatchingPolicy>
    </Union>

    <View>
      <Name>nats-telemetry-by-region</Name>
      <MessageType>json</MessageType>
      <UnderlyingTopic>nats-telemetry-union</UnderlyingTopic>
      <Projection>
        <Field>/region</Field>
        <Field>COUNT(/sensorId) AS /sensorCount</Field>
      </Projection>
      <Grouping>
        <Field>/region</Field>
      </Grouping>
    </View>

    <ConflatedTopic>
      <Name>nats-telemetry-by-region-ui</Name>
      <MessageType>json</MessageType>
      <UnderlyingTopic>nats-telemetry-by-region</UnderlyingTopic>
      <Interval>1s</Interval>
    </ConflatedTopic>
  </SOW>
</AMPSConfig>

If you truly want to capture the entire NATS subject space, use > as the Pattern. In practice, most teams use a bounded namespace such as time.us.> or orders.> so entitlements, monitoring, and disk planning stay predictable.

Usage Tips

• Use TOPIC_MATCH when a field stores the original NATS subject. For example, /subject TOPIC_MATCH 'time.us.>' applies NATS wildcard rules to the field value.
• Remember that > must be the final token in a NATS pattern.
• Migrating clients can keep NATS wildcard syntax on a per-request basis with topic_matching_policy=nats on commands such as subscribe, sow, and sow_and_subscribe.
• Use LIKE only when you intentionally want PCRE behavior regardless of the resolved topic policy.
• Choose the SOW key from the business entity, not from the subject alone, when one NATS subject can carry repeated updates for the same object.
• Use sow_and_subscribe against the Union or View to hydrate an operator screen atomically, then keep it up to date without a query gap.
• Use sow_and_delta_subscribe or a ConflatedTopic for browser-based dashboards that do not need every intermediate update.