DBMS_TELEMETRY_QUERY

The DBMS_TELEMETRY_QUERY package provides a collection of user functions to query metrics from Oracle AI Database Telemetry Streaming.

This chapter contains the following topics:

DBMS_TELEMETRY_QUERY Overview

The query APIs that are implemented using the DBMS_TELEMETRY_QUERY package enable the users in a workspace to query metrics from Oracle AI Database Telemetry Streaming. It allows the query users to run different types of queries and return the result in SQL or JSON.

See Also:

DBMS_TELEMETRY_QUERY Security Model

The DBMS_TELEMETRY_QUERY package is an invoker’s right package that enables a Telemetry workspace query user to query metrics from an Oracle AI Database Telemetry Streaming workspace.

A Telemetry workspace user is an existing database user who has been explicitly granted access and the required privileges by the Telemetry workspace administrator using the DBMS_TELEMETRY_ADMIN.ENABLE_WORKSPACE_USER procedure with user_role set to ‘QUERY’.

A user can be an ingest user, a query user, or both to only one workspace.

Summary of DBMS_TELEMETRY_QUERY Subprograms

This table lists and briefly describes the DBMS_TELEMETRY_QUERY package subprograms.

Table 1 DBMS_TELEMETRY_QUERY Package

Subprogram Description
PROMQL_RANGE Function Returns a CLOB for queries based on a time range
PROMQL_LABELS Function Fetches all the distinct values that a key can take
PROMQL_INSTANT Function Returns time series for a particular timestamp
PROMQL_SERIES Function Fetches time series metadata (metric name and tags)

PROMQL_RANGE Function

This function enables users to query data from Oracle AI Database Telemetry Streaming based on a time range.

The PROMQL_RANGE function returns a CLOB for range queries, which are queries that span over a time range.

Syntax

promql_range(
   promql_query      IN VARCHAR2,
   start_time_epoch  IN NUMBER,
   end_time_epoch    IN NUMBER,
   step_size_seconds IN NUMBER DEFAULT 10,
   fetch_sql         IN NUMBER DEFAULT 0) return clob;

Parameters

Table 2 PROMQL_RANGE Function

Parameter Description
promql_query The PromQL query from the user
start_time_epoch The start time of the time range in which the query is interested
end_time_epoch The end time of the query
step_size_seconds Resolution size of the query. The output data points are (usually) step_size apart (by time).
fetch_sql Result desired by the client. (set it to 1 if you want SQL, 2 for JSON)

PROMQL_LABELS Function

This function enables users to query data from an Oracle AI Database Telemetry Streaming workspace to fetch all the labels (key-value pairs) from a metric key or metric name.

The PROMQL_LABELS function returns a CLOB for distinct values that a particular metric key or metric name can take.

Syntax

PROMQL_LABELS(
   promql_query     IN VARCHAR2,
   start_time_epoch IN NUMBER,
   end_time_epoch   IN NUMBER,
   fetch_sql        IN NUMBER DEFAULT 0)
return clob;

Parameters

Table 3 PROMQL_LABELS Function

Parameter Description
promql_query The PromQL query from the user
start_time_epoch The start time of the time range in which the query is interested
end_time_epoch The end time of the query
step_size_seconds Resolution size of the query. The output data points are (usually) step_size apart (by time).
fetch_sql Result desired by the client. (set it to 1 if you want SQL, and set it to 2 for JSON)

Note: The start_time_epoch and end_time_epoch can be set to zero(0), in which case the data from the last-hour time series table is fetched.

PROMQL_INSTANT Function

This function is for queries that request time series for a particular time-stamp.

The PROMQL_INSTANT function returns a CLOB of time series for a particular time-stamp.

Syntax

promql_instant(
       promql_query       IN VARCHAR2,
       instant_time_epoch IN NUMBER,
       fetch_sql          IN NUMBER DEFAULT 0)
return clob;

Parameters

Table 4 PROMQL_INSTANT Function

Parameter Description
promql_query The PromQL query from the user
instant_time_epoch The time-stamp at which the time series data is requested
fetch_sql Result desired by the client. (set it to 1 if you want SQL, 2 for JSON)

PROMQL_SERIES Function

This function enables users to fetch time series metadata (metric name and tags).

The PROMQL_SERIES function returns a CLOB for time series metadata.

Syntax

promql_series(
       promql_query     IN VARCHAR2,
       start_time_epoch IN NUMBER,
       end_time_epoch   IN NUMBER,
       fetch_sql        IN NUMBER DEFAULT 0)
return clob;

Parameters

Table 5 PROMQL_SERIES Function

Parameter Description
promql_query The PromQL query from the user
start_time_epoch The start time of the query
end_time_epoch The end time of the query
fetch_sql Result desired by the client (set it to 1 if you want SQL, 2 for JSON)