Cisco Observability Platform Query Service API

OPTIONS

The OPTIONS clause allows customization of various parts of the Unified Query Language (UQL) query processing. It is a block of options and each option is one argument function.

Code Snippet
CopyOPTIONS
   option1(arg1),
   option2(arg2),
   option3(arg3)
   …

Note

OPTIONS specified in the UQL query affect only the processed query. It does not affect the consecutive queries.

Result Timestamps Formatting

The timestamp is one of the data types returned in the query response. For example:

Code Snippet
CopyFETCH createdAt
FROM entities()
SINCE -5m

Examples of fields with timestamp value:

  • Entity createdAt and updatedAt.

  • Timestamps related to metrics, events, logs, and traces. For example, metric and event timestamp.

  • Some attributes.

The supported options that affect the result timestamps are:

  • resultTimestampFormat(pattern) - returned timestamps are formatted using the specified pattern.

  • resultTimestampToEpoch(units) - returned timestamps are converted to the number of specified time units since the beginning of the Unix epoch.

  • resultTimestampOffset(offset) - returned timestamps are shifted using the specified offset.

Note

Only timestamps in data response chunks are affected by these options, metadata in the response remain unchanged.

Default Behavior

When the timestamp formatting option is not specified, timestamps in the response are formatted according to ISO-8601. For example 2023-10-31T13:47:00Z or 2023-10-31T13:47:00+03:00.

Customize Timestamp Format

Using the resulTimestampFormat(pattern) option, it’s possible to format result timestamps with a custom format. The string argument pattern uses date and time symbols recognized by DateTimeFormatter.

The following table lists the most common symbols. For a complete list of symbols, see the Oracle documentation.

Symbol Meaning Presentation Examples
y year-of-era year 2004; 04
M/L month-of-year number/text 7; 07; Jul; July; J
d day-of-month number 10
E day-of-week text Tue; Tuesday; T
H hour-of-day (0-23) number 0
m minute-of-hour number 30
s second-of-minute number 55
S fraction-of-second fraction 978
X zone-offset ‘Z’ for zero offset-X Z; -08; -0830; -08:30; -083015; -08:30:15;

Example: Customized format of result timestamps.

Code Snippet
Copy
FETCH createdAt
FROM entities()
SINCE -5m
OPTIONS resultTimestampFormat("dd.MM.yyyy HH:mm")

Convert Timestamps To Unix Epoch Time

When the resultTimestampToEpoch(units) option is used, result timestamps are converted to the number of specified time units since the beginning of the Unix epoch.

The enum argument units support the following values:

  • SECONDS - number of seconds

  • MILLIS - number of milliseconds

  • MICROS - number of microseconds

  • NANOS - number of nanoseconds

Example: Result timestamps as milliseconds since the Unix epoch.

Code Snippet
CopyFETCH createdAt
FROM entities()
SINCE -5m
OPTIONS resultTimestampToEpoch(MILLIS)

Shift Timestamps By Offset

If there is a need to have the result timestamps in a different timezone than UTC, it is possible to use the resultTimestampOffset(offset) option. This option adds the specified offset to all timestamps in the result. The string argument offset is expected to contain ISO-8601 formatted offset value such as, +03:00 or -11:12:13.

For example, if we specify offset +02:00 by using this option, instead of 2023-10-31T13:32:00Z, the resulting timestamp will be 2023-10-31T15:32:00+02:00.

Example: Result timestamps shifted by 2 hours offset.

Code Snippet
CopyFETCH createdAt
FROM entities()
SINCE -5m
OPTIONS resultTimestampOffset("+02:00")

Note

You can not use the resultTimestampOffset option with the resultTimestampToEpoch option.

Next