Method: projects.datasets.query

Execute a Timeseries Insights query over a loaded DataSet.

HTTP request

POST https://{endpoint}/v1/{name=projects/*/datasets/*}:query

Where {endpoint} is one of the supported service endpoints.

The URLs use gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. Loaded DataSet to be queried in the format of "projects/{project}/datasets/{dataset}"

Request body

The request body contains data with the following structure:

JSON representation 
{
  "detectionTime": string,
  "slicingParams": {
    object (SlicingParams)
  },
  "timeseriesParams": {
    object (TimeseriesParams)
  },
  "forecastParams": {
    object (ForecastParams)
  },
  "returnNonAnomalies": boolean,
  "returnTimeseries": boolean
}
Fields
detectionTime

string (Timestamp format)

Required. This is the point in time which we want to probe for anomalies.

The corresponding TimeseriesPoint is referred to as the detection point.

NOTE: As with any other time series point, the value is given by aggregating all events in the slice that are in the [detectionTime, detectionTime + granularity) time interval, where the granularity is specified in the timeseriesParams.granularity field.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
slicingParams

object (SlicingParams)

Parameters controlling how we will split the data set into the slices that we will analyze.
timeseriesParams

object (TimeseriesParams)

Parameters controlling how we will build the time series used to predict the detectionTime value for each slice.
forecastParams

object (ForecastParams)

Parameters that control the time series forecasting models, such as the sensitivity of the anomaly detection.
returnNonAnomalies

boolean

If we should return slices that we evaluated, but were not marked as anomalies. This is useful for debugging purposes or to simply see what was the evaluation status for slices that were not anomalies.
returnTimeseries

boolean

If specified, returns the actual and forecasted time series for slices marked as anomalies. The time series are returned in the ForecastResult.history and ForecastResult.forecast fields.

Response body

If successful, the response body contains data with the following structure:

Response for a query executed by the system.

JSON representation 
{
  "name": string,
  "anomalyDetectionResult": {
    object (AnomalyDetectionResult)
  }
}
Fields
name

string

Loaded DataSet that was queried.
anomalyDetectionResult

object (AnomalyDetectionResult)

Filled if we ran anomaly detection as part of the query.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

SlicingParams

Parameters that control how we slice the data set and, optionally, filter slices that have some specific values on some dimensions (pinned dimensions).

JSON representation 
{
  "dimensionNames": [
    string
  ],
  "pinnedDimensions": [
    {
      object (PinnedDimension)
    }
  ]
}
Fields
dimensionNames[]

string

Required. Dimensions over which we will group the events in slices. The names specified here come from the EventDimension.name field. At least one dimension name must be specified. All dimension names that do not exist in the queried DataSet will be ignored.

Currently only dimensions that hold string values can be specified here.
pinnedDimensions[]

object (PinnedDimension)

Optional. We will only analyze slices for which ForecastSlice.dimensions contain all of the following pinned dimensions. A query with a pinned dimension { name: "d3" stringVal: "v3" } will only analyze events which contain the dimension { name: "d3" stringVal: "v3" }. The pinnedDimensions and dimensionNames fields can not share the same dimension names.

Example a valid specification:

{
  dimensionNames: ["d1", "d2"],
  pinnedDimensions: [
    { name: "d3" stringVal: "v3" },
    { name: "d4" stringVal: "v4" }
  ]
}

In the previous example we will slice the data set by dimensions "d1", "d2", "d3" and "d4", but we will only analyze slices for which "d3=v3" and "d4=v4".

The following example is invalid as "d2" is present in both dimensionNames and pinnedDimensions:

{
  dimensionNames: ["d1", "d2"],
  pinnedDimensions: [
    { name: "d2" stringVal: "v2" },
    { name: "d4" stringVal: "v4" }
  ]
}

AnomalyDetectionResult

Result of running anomaly detection over the input time series.

JSON representation 
{
  "anomalies": [
    {
      object (ForecastSlice)
    }
  ],
  "nonAnomalies": [
    {
      object (ForecastSlice)
    }
  ]
}
Fields
anomalies[]

object (ForecastSlice)

Anomalies detected.
nonAnomalies[]

object (ForecastSlice)

Slices we evaluated, but which were not marked as anomalies. Only returned if QueryDataSetRequest.returnNonAnomalies is set to true.

ForecastSlice

Event forecast.

JSON representation 
{
  "dimensions": [
    {
      object (EventDimension)
    }
  ],
  "result": {
    object (ForecastResult)
  },
  "status": {
    object (Status)
  }
}
Fields
dimensions[]

object (EventDimension)

Event dimensions. The number of dimensions here is equal to the size of the dimensionNames field specified in the request.
result

object (ForecastResult)

Filled if we ran forecasting for this slice.
status

object (Status)

Slice processing status.