FETCH

The FETCH block is the only mandatory clause of the query. It specifies what observations should be returned by the query and how to order (sort) the fields. Many observations are of the complex type, which are the arrays of tuples. The Unified Query Language (UQL) models it as tables where some fields can have another (nested) table as their value.

Supported Field Types

You can use the following field types in the FETCH block:

How to Specify Observations in the FETCH Clause?

The FETCH clause contains a comma-separated list of observations (observation fields). UQL supports functions to retrieve particular fields and syntax to filter them. The functions are executed on topology objects (entities) that are defined in the FROM block. Some functions are also defined on the topology universe, which can be used in the queries without FROM block. You can optionally specify a name or an alias for each observation. If you do not specify any alias, an implicit alias is used.

Notes

• The functions and fields have the same constructs in UQL. If a function has no parameter, you can omit the parentheses. For example, id and id() are the same functions or fields.
• All the keywords in the clauses are valid in upper or lower case but not in mixed-case. For example, the valid variants are from and FROM, but not From.

Example:

FETCH 
  id,
  attributes("service.name"),
  cpm:metrics(calls_per_minute)     // cpm is used as an alias
FROM entities(service)

You can provide an alias for any fetched observation field. The alias is used in the result to identify relevant data and can be used in specific cases such as a column reference. An alias can be any string, but if the string is non-alphanumeric characters, it must be quoted by backticks. For example:

FETCH
   name: attributes(service.name),
   `Calls per minute`: metrics(apm:number_of_calls).value
FROM entities(service)

Fetch Complex Fields

UQL result supports nested complex types - nested tables. The UQL model specifies structure up to the primitive observation fields. To control what observation fields of the complex type are to be included in the response, use the following options:

• Implicit - a predefined set of fields for a given observation type

  If the function maps to a complex type, UQL provides a selected set of its observation fields to return. These are not all the fields, but the most important fields for the most known use cases.

  For example, when you specify metrics("calls_per_minute", "infra-agent"), the query returns the implicit fields: timestamp, value.

• Explicit - specify a single field or use curly brackets to specify selected fields

  If the function maps to a complex type, you can specify the set of observation fields in curly brackets appended to the function call.

  For example, when you specify metrics("calls_per_minute", "infra-agent"){timestamp, min, max}, the query returns the specific fields: timestamp, min, max.

  If you want to fetch a single observation field, specify the field using the period (.) operator.

  For example, when you specify metrics("calls_per_minute", "infra-agent").max, the query returns only the max value.

• Explicit with aliasing - specify an observation set with named or aliased observations

  You can use alias: observation to rename the observations if you don’t like their names or need specific aliases for processing the query result.

  For example, you can rename the fields timestamp, min, and max by using the following:

  metrics("calls_per_minute", "infra-agent"){ts:timestamp, minVal:min, maxVal:max}

Fetch Observations - Topology State

Topology maintains and provides state observations for the MELT model. So, the state observations are accessible only on the specified topology. The query must contain the FROM clause.

In the preceding diagram, you see the following:

• name, value fields are returned by default for the complex type.
• If a function has the type complex, then the diagram contains its specification in the associated object of the same name.

Example: Get ID and two selected attributes

FETCH 
  id,
  attributes("service.name"),
  attributes("service.namespace")
FROM entities(service)

Example: Get ID and all attributes as nested tables

FETCH 
  id,
  attributes
FROM entities(service)

Example: Get the first non-null value from a defined set of attributes

The coalesceAttributes() function returns the first non-null value of the specified attributes. You can use it in the FETCH clause, filters, and, in the ORDER clause. This function is useful when an entity name is represented by different attributes for different entity types.

For example, the following query fetches two types of entities— Kubernetes pods and workloads. The query returns ID and name of each entity. Since the name is stored in different attributes for pod and workload, the coalesceAttributes() function returns the name that has a value.

FETCH id, name: coalesceAttributes(k8s.pod.name, k8s.workload.name)
FROM entities(k8s:pod, k8s:workload)