Cisco Observability Platform Query Service API

Parameterized Queries

You can specify parameters in your query instead of providing their actual values. The actual values of the parameters are specified separately from the query. When the query is executed, the parameters take their actual values.

The parameterized query provides the following benefits:

  • Protection against UQL injection: The query and the parameter values are sent separately. This prevents an attacker to enter malicious executable code and get unauthorized access.

  • Escaping special characters: If you use a string with special characters, the query does not get compiled. Instead, you can use parameters to represent strings that contain special characters. For example, service.name = 'My 'special' service.

Parameter Types

The following parameter types are supported:

Parameter Type Description
string Indicates an arbitrary text.
long Indicates integer numbers.
double Indicates floating point numbers.
boolean Indicates whether true or false.
timestamp Indicates the timestamp in the ISO format.
duration Indicates the time duration in the ISO format. For example, PT5M indicates a duration of five minutes.
typeId Indicates the ID of an entity type.
objectId Indicates the ID of an entity.
any Indicates an arbitrary value.
wildcard Indicates wildcard pattern. Currently supported parameter value is "*" or ["*"]

How to Use Parameterized Queries

In your query, you can replace a scalar value and a list of values with parameters.

To add a parameter in your query, you must prefix $ to the parameter name. For example, $statusCode.

When you use the REST API, you must provide the values of a parameter in the queryParameters field of the JSON object.

Scalar value Parameters

You can use a parameter to represent a single value. For example:

Code Snippet
Copy
{
  "query": "FETCH id, spans[statusCode = $staßtusCode] FROM entities($entityType)[attributes(\"health.status\") = $healthStatus]",
  "queryParameters": [{
    "name": "statusCode",
    "type": "string",
    "value": "UNSET"
  },{
    "name": "entityType",
    "type": "typeId",
    "value": "apm:service_instance"
  },{
    "name": "healthStatus",
    "type": "long",
    "value": 0
  }]
}

List-values Parameters

You can use a parameter to represent a list of values. For example:

Code Snippet
Copy
{
  "query": "FETCH events(logs:generic_record)[source IN $sourceName]",
  "queryParameters": [{
    "name": "sourceName",
    "type": "string",
    "value": ["opentelemetry", "log-agent"]
  }]
}
Next