Skip to main content

Message Functions

AMPS includes functions that can be used to refer to the current message being processed.

When used in view construction or aggregate definition, these functions refer to the incoming message that is prompting the update to the view or aggregate, not to the constructed message that is the result of the update. For example, a Field like this in a view projection:

<Projection>
  ...
  <Field>TOPIC_NAME() AS /theTopic</Field>
  ...
</Projection>

will return the topic name of the topic that prompted the update to the view, not the name of the view itself.

MESSAGE_SIZE​

MESSAGE_SIZE​

MESSAGE_SIZE()

Returns the size of the payload of the current message, in bytes.

Parameters

None.

Returns

The size of the message payload in bytes.

Available For​

All messages.

CORRELATION_ID​

CORRELATION_ID​

CORRELATION_ID()

Returns the correlation ID of the current message as a string.

Parameters

None.

Returns

The correlation ID of the current message, or NULL if there is no correlation ID.

Available For​

All messages.

LAST_UPDATED​

LAST_UPDATED​

LAST_UPDATED()

Returns a timestamp for the last time that a message in the SOW was updated, as a double.

For a subscription (including the subscription part of a sow_and_subscribe command), the LAST_UPDATED value will be the current timestamp. This function is most useful for queries of a topic in the SOW.

Notice that this field is set based on when the local instance has updated the message. For replicated topics, this means that a given message will have different values on different instances.

Parameters

None.

Returns

A timestamp for the last time the message was updated.

Available For​

Queries of a SOW topic.

TOPIC_NAME​

TOPIC_NAME​

TOPIC_NAME()

Returns the topic name for the message currently being processed.

When used in a filter for a message being delivered from a queue that has multiple underlying topics, returns the name of the underlying topic

Parameters

None.

Returns

A string containing the topic name for the message.

Available For​

All messages

BOOKMARK​

BOOKMARK​

BOOKMARK()

Returns the bookmark for the current message, if one is available.

Messages retrieved from a SOW topic using a query return NULL for BOOKMARK, since the SOW does not store the bookmark of a message.

Bookmarks are assigned using a combination of an identifier derived from the client name and a sequence number. When working with bookmarks, 60East recommends treating bookmarks as opaque identifiers. In particular, bookmarks are not guaranteed to sort in any particular order between different publishers.

AMPS only assigns bookmarks when a message is stored in the transaction log. Messages that are not in the transaction log do not have bookmarks assigned.

Parameters

None.

Returns

The bookmark for the current message.

Available For​

  • Subscriptions to a transaction-logged topic
  • Bookmark subscriptions to a transaction-logged topic
  • SOW delete by filter for a transaction-logged topic
LAST_LEASED​

LAST_LEASED​

LAST_LEASED()

For a message in a queue, returns a timestamp for the last time this message was leased from this instance, as a double. Returns NULL for a message that is not in a queue.

Notice that this timestamp is set based on when the local instance leased the message. This counter is reset when the instance restarts.

Parameters

None.

Returns

A timestamp for the last time this message was leased.

Available For​

  • Queries of a message queue
  • Subscription to a message queue
  • SOW delete by filter for a message queue
LEASE_COUNT​

LEASE_COUNT​

LEASE_COUNT()

For a message in a queue, returns the number of times the message has been leased from this instance as a double. Returns NULL for a message that is not in a queue.

Notice that this counter is set based on leases from the local instance. This counter is reset when the instance restarts, and does not track leases from other instances.

Parameters

None.

Returns

The number of times the message has been leased.

Available For​

  • Queries of a message queue
  • Subscription to a message queue
  • SOW delete by filter for a message queue
SOW_KEY​

SOW_KEY​

SOW_KEY()

For a message in a SOW topic, returns the current SOW key of the message. This will typically be the AMPS-generated identifier for the message. For topics that use explicit publisher-provided keys (that is, where the SOW key must be set on the header of the publish command rather than derived from the data), this will be the publisher-provided key.

This function is designed for use in enrichment. In a query, subscription, or delete command, using the SowKeys header with the key or keys of interest is more efficient.

Parameters

None.

Returns

The SOW key that AMPS uses for the message, either as provided by the publisher or as used internally by AMPS, as a string.

Available For​

  • Queries or enrichment of a SOW topic
  • Subscription to a SOW topic
SOW_KEY_HASH​

SOW_KEY_HASH​

SOW_KEY_HASH()

For a message in a SOW topic, returns the AMPS-generated identifier for the message. For topics that do not use explicit publisher-provided keys, this function will return the same value as SOW_KEY. For topics that use explicit publisher-provided keys (that is, where the SOW key must be set on the header of the publish command rather than derived from the data), this will return the hash value AMPS uses internally for the message rather than the publisher-provided key.

This function is designed for use in enrichment. In a query, subscription, or delete command, using the SowKeys header with the key or keys of interest is more efficient.

Parameters

None.

Returns

The SOW key hash that AMPS uses internally for the message, as a string.

Available For​

  • Queries or enrichment of a SOW topic
  • Subscription to a SOW topic
LAST_READ​

LAST_READ​

LAST_READ()

Returns a timestamp for the last time that this message was read from the SOW.

This function only returns a value for messages in a topic in the SOW.

This value is not persisted across restarts or shared across instances.

Parameters

None.

Returns

A double indicating the last time that this message was read from the SOW on the local instance. This value is not persisted across restarts or shared across instances.

Available For​

  • Queries of a SOW topic