Unified Query Language (UQL)

The Cisco Observability Platform provides a domain-specific query language that allows you to retrieve MELT (metrics, events, logs, traces) observation data and entity-related data. You can fetch observability data across all the solution domains currently available and subscribed by a tenant. You can use UQL to integrate observation data of your solution with other systems. Experts can use UQL to delve deeper into the observed data.

Some of the UQL features are:

• It is a domain-specific language
• It is a declarative language
• It is a data query language
• It is read-only
• It presents MELT data and State in the scope of monitored topology
• Queries are executed for a specific time range

For more information, see the Unified Query Language User Guide.

Query Blocks

The UQL query consists of blocks. The query can contain blocks in any order. Each block starts with a keyword and defines a selection
of some query aspect. You can type the keyword in upper or lower case, do not use mixed case. UQL supports the following blocks:

• FETCH (mandatory block) - Defines the response observation data.

  You must specify the MELT data along with the exact fields (attributes, tags, and so on) within the data to fetch.

• SINCE - Defines the start of a queried time interval.

• UNTIL - Defines the end of a queried time interval.
  SINCE and UNTIL help you define the time range used to retrieve MELT data.

• FROM - Defines the topology of the query (entities and relationships).

• NAMESPACES - Defines default namespaces for types used in the query.

  MELT types are organized as Types in the schema. Types consist of two parts: namespace and type name.

  Types are often used in UQL queries. The syntax to use Type is <namespace>:<type name>. For example apm:service, where apm is the namespace and service is the type name.

• LIMITS - Defines limits for array MELT data.

• ORDER - Defines the order for array MELT data.

Use fsoc to Fetch Available Data

To build a UQL query, you need to know the available elements in the solution data model. Use the fsoc command to determine the available elements for an entity or a solution.

Fetch Elements of a Data Model

The following example determines the elements of the starship entity in the spacefleet solution:

Copy  ./fsoc objstore get --type=fmm:entity --layer-type=SOLUTION --layer-id=spacefleet --filter='data.name eq "starship"' --fields="data" --output="yaml"

  items:
  - data:
  associationTypes:
  common:consists_of:
  - spacefleet:room
  - spacefleet:torpedo_tube
  common:has:
  - spacefleet:warp_drive
  attributeDefinitions:
  attributes:
  spacefleet.starship.name:
  description: Name of the spaceship
  type: string
  spacefleet.starship.registry:
  description: Spaceship registry used to identify the spaceship
  type: string
  optimized:
  - spacefleet.starship.name
  - spacefleet.starship.registry
  required:
  - spacefleet.starship.name
  - spacefleet.starship.registry
  description: Represents a starship
  displayName: Starship
  kind: entity
  lifecycleConfiguration:
  purgeTtlInMinutes: 525600
  retentionTtlInMinutes: 180
  metricTypes:
  - spacefleet:torpedo_count
  - spacefleet:shield_level
  - spacefleet:speed
  - spacefleet:earth_day
  name: starship
  namespace:
  name: spacefleet
  version: 1
  total: 1

Output

Successful execution of the preceding command provides the following output:

fsoc uql Command

Use the fsoc uql command to execute UQL queries to fetch data:

Copyfsoc uql [flags]

For example:

Copyfsoc uql "fetch id, attributes from entities(spacefleet:starship)"

Successful execution of the command provides the following output:

FROM Block

The query defines the selection and transformation of observed data from a single tenant. UQL is built as a form (or questionnaire). The query consists of answers to specific questions or form fields.

• Each answer starts with a reserved word.
• Answers can be in any order.
• Some questions are distinct, the query can contain answers only for one of these questions.
• Some questions provide default answers.
• Specific questions define specific syntax: it still shares generic principles (such as escaping and reserved characters)

A From block or the UQL questionnaire comprises objects that are specified using conditions. These conditions are based on associated MELT data, state data, topology data, or a combination of data, including attributes of primary objects and relationships. Primary topology objects are Entities, Transactions, and Interactions.

Examples:

• MELT data: "Entities with more than 100 error log messages in last hour"
• State data: "Entities with tag 'region' equal to 'FRA'"
• Topology attributes: "Entities with type 'Pod'" or "Interactions starting from Service 123"
• Relationships: "All pods associated with Application 123"

FETCH Block

FETCH is the only mandatory block to fetch events. FETCH and FROM are the mandatory blocks for all other cases. All other blocks are optional and have a default value. The FETCH block contains a comma-separated list of observation fields. UQL supports functions to retrieve particular fields and syntax to filter them. Functions are executed on topology objects (entities) defined in the FROM block.

Example:

Copyfetch
  id,
  attributes("service.name")
  metrics(calls_per_minute)
from
  entities(apm:service)

In this example:

• fetch block defines MELT or state data expected as part of the return
  • ID of selected entities
  • attribute service.name of selected entities
  • metric calls\_per\_minute associated with the selected entities
• from block defines topology context of the query - entities and associations
  • data for entities of the type apm:service

Filter Data

You can filter objects such as entities, metrics, and events by comparing their scalar fields or facts with constants. The scalar-type fields can be used for filtering the data. Facts are fields indirectly associated with the filtered object—for example, the attribute or tag of a given name. Filtering allows you to express your intent as a UQL payload.

You may include filter expressions after any function that returns a set of objects. Include the filter in a square bracket []:
For example: <identify set of objects>[<expression>]

The following operations are supported in a filter expression:

• && Logical and - <expression> && <expression>
• = equals - <field_identifier> = <constant>
• != not equals - <field_identifier> != <constant>
• < less then - <field_identifier> < <constant>
• > greater then - <field_identifier> > <constant>
• <= less or equals - <field_identifier> <= <constant>
• >= greater or equals - <field_identifier> >= <constant>
• in or IN equals to one of alternative values - <field_identifier> in [<constant1>, <constant2>, ..., <constantN>]
• ~ like (wildcard filtering) - <field_identifier> ~ <wildcard pattern>