Method: legacy.legacyFetchUdmSearchView

Full name: projects.locations.instances.legacy.legacyFetchUdmSearchView

Legacy endpoint for fetching events, filters, and histograms matching UDM search.

HTTP request

POST https://chronicle.googleapis.com/v1alpha/{instance}/legacy:legacyFetchUdmSearchView

Path parameters

Parameters
instance

string

Required. Chronicle instance this request is sent to. Format: projects/{project}/locations/{location}/instances/{instance}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "baseline_query": string,
  "snapshot_query": string,
  "baseline_time_range": {
    object (Interval)
  },
  "snapshot_time_range": {
    object (Interval)
  },
  "event_list": {
    object (UdmEventListOptions)
  },
  "timeline": {
    object (EventCountTimelineOptions)
  },
  "field_aggregations": {
    object (UdmFieldAggregationsOptions)
  },
  "case_insensitive": boolean,
  "generate_ai_overview": boolean,
  "return_operation_id_only": boolean,
  "detection_options": {
    object (DetectionOptions)
  },
  "stats_function_parameter": {
    object (FunctionParameter)
  },
  "draft_data_access_scope": {
    object (DataAccessScope)
  },
  "prevalence": {
    object (UdmPrevalenceOptions)
  },
  "enable_poc_fast_path": boolean,
  "federation_metadata": {
    object (FederationMetadata)
  }
}
Fields
baseline_query

string

Required. Boolean query to search for events. You can refer to https://cloud.google.com/chronicle/docs/investigation/udm-search for the query syntax. Example: 'ip=/172.*/ AND metadata.event_type!="NETWORK_CONNECTION" AND ( target.ip = "3.225.179.73" OR target.ip = "23.47.48.70")'
snapshot_query

string

Query applied to the baseline query's events. In other words, this query is applied to the Snapshot produced from the baseline query. The snapshot_query has the same syntax as baseline_query and is implicitly ANDed with baseline_query to produce events.
baseline_time_range

object (Interval)

Required. Required, the time range to search for [inclusive start time, exclusive end time).
snapshot_time_range

object (Interval)

The time range to filter for [inclusive start time, exclusive end time). This time range must be completely within baseline_time_range. If not set, it is assumed to match baseline_time_range.
event_list

object (UdmEventListOptions)

Parameters for the Events that will be streamed back.
timeline

object (EventCountTimelineOptions)

Parameters for the EventCountTimeline that will be streamed back.
field_aggregations

object (UdmFieldAggregationsOptions)

Parameters for the Aggregated UDM fields that will be streamed back.
case_insensitive

boolean

If true, the search should be performed in a case-insensitive manner.
generate_ai_overview

boolean

Optional. If true, generate AI overview for the search results.
return_operation_id_only

boolean

Optional. If this field is set to true, the response will only contain the operation resource name. The actual search results (events) will be streamed back when the client invokes the streamSearchOperation method using this operation resource name.
detection_options

object (DetectionOptions)

Fetch alerts/detections relevant to the search result.
stats_function_parameter

object (FunctionParameter)

The request to apply statistical function on filtered data.
draft_data_access_scope

object (DataAccessScope)

Data access scope used to filter events. This is intended to be used by admins to preview in-development scopes. Should only be called by users with global access. If the caller does not have global access, the request will fail.
prevalence

object (UdmPrevalenceOptions)

Parameters to get prevalence counts on Events returned by UDM Search
enable_poc_fast_path

boolean

If true, search will limit max_baseline_results to 30K events and remove time-order guarantee (i.e., results may not be the most-recent events in baseline query time range). In this mode, replayed search queries are not guaranteed to yield the same results each time. This option is for poc use-cases only.
federation_metadata

object (FederationMetadata)

Optional. Federation metadata for the request. If this field is populated, it implied this is a federated search.

Response body

Depending on the parameters in ListUdmEventsV3Request, stream back some combination of UDM Events, EventCountTimeline, and UdmFieldAggregations.

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

JSON representation 
{
  "operation": string,
  "progress": number,
  "too_many_events": boolean,
  "too_large_response": boolean,
  "complete": boolean,
  "valid_baseline_query": boolean,
  "baseline_events_count": integer,
  "valid_snapshot_query": boolean,
  "query_validation_errors": [
    {
      object (ErrorMessage)
    }
  ],
  "runtime_errors": [
    {
      object (RuntimeError)
    }
  ],
  "filtered_events_count": integer,
  "stats_function_parameter_validation_error_message": string,
  "prevalence": {
    object (UdmPrevalenceResponse)
  },
  "stats": {
    object (Stats)
  },
  "data_sources": [
    enum (SearchDataSource)
  ],
  "ai_overview": {
    object (AIOverview)
  },
  "events": {
    object (UdmEventList)
  },
  "timeline": {
    object (EventCountTimeline)
  },
  "field_aggregations": {
    object (UdmFieldAggregations)
  },
  "grouped_field_aggregations": {
    object (UdmFieldAggregations)
  },
  "detections": {
    object (Detections)
  },
  "stats_function_response": {
    object (FunctionResponse)
  },
  "activity_timeline": {
    object (EventCountTimeline)
  }
}
Fields
operation

string

The name of the operation resource representing the UDM Search operation. This can be passed to StreamSearchOperation to fetch stored results or stream the results of an in-progress operation.

The metadata type of the operation is UdmSearchMetadata. The response type is LegacyFetchUdmSearchViewResponse.

Format: projects/{project}/locations/{location}/instances/{instance}/operations/{operation}
progress

number

Progress of the query represented as a double between 0 and 1.
too_many_events

boolean

If true, there are too many events to return and some have been omitted.
too_large_response

boolean

If true, the response to be returned to the UI is too large and some events have been omitted.
complete

boolean

Streaming for this response is done. There will be no additional updates.
valid_baseline_query

boolean

Indicates whether the request baseline_query is a valid structured query or not. If not, query_validation_errors will include the parse error.
baseline_events_count

integer

The number of events in the baseline query.
valid_snapshot_query

boolean

Indicates whether the request baseline and snapshot queries are valid. If not, query_validation_errors will include the parse error.
query_validation_errors[]

object (ErrorMessage)

Parse error for the baseline_query and/or the snapshot_query.
runtime_errors[]

object (RuntimeError)

Runtime errors.
filtered_events_count

integer

The number of events in the snapshot that match the snapshot_query. This is <= baseline_events_count. If the snapshot query is empty this will be equivalent to baseline_events_count.
stats_function_parameter_validation_error_message

string

If the request's stats_function_parameter` is invalid, this field will contain the detailed error message.
prevalence

object (UdmPrevalenceResponse)

Prevalence results on Events returned by UDM Search
stats

object (Stats)

Stats results when the query is for statistics
data_sources[]

enum (SearchDataSource)

Datasource of the query and results in case of a statistics query
ai_overview

object (AIOverview)

AI generated overview for the search results. Only populated if the AI features are enabled for the customer and generate_ai_overview is set to true in the request.
events

object (UdmEventList)

List of UDM events. NOTE: After complete is set to true, the UdmEventList message will be omitted from the response. The latest message should be used as reference. If the UdmEventList message is returned again, then it should replace the previous value.
timeline

object (EventCountTimeline)

Timeline of event counts broken into buckets.
field_aggregations

object (UdmFieldAggregations)

List of UDM fields with aggregated values.
grouped_field_aggregations

object (UdmFieldAggregations)

List of grouped fields with aggregated values.
detections

object (Detections)

List of relevant detections, if detection_list.max_returned_detections was set.
stats_function_response

object (FunctionResponse)

Result for statistical function.
activity_timeline

object (EventCountTimeline)

Timeline of event counts broken into hourly/daily buckets to identify activity.

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the instance resource:

  • chronicle.legacies.legacyFetchUdmSearchView

For more information, see the IAM documentation.

UdmEventListOptions

JSON representation 
{
  "max_returned_events": integer
}
Fields
max_returned_events

integer

EventCountTimelineOptions

This type has no fields.

UdmFieldAggregationsOptions

JSON representation 
{
  "max_values_per_field": integer
}
Fields
max_values_per_field

integer

DetectionOptions

JSON representation 
{
  "snapshot_query": string,
  "detection_list": {
    object (DetectionListOptions)
  },
  "field_aggregations": {
    object (UdmFieldAggregationsOptions)
  }
}
Fields
snapshot_query

string
detection_list

object (DetectionListOptions)
field_aggregations

object (UdmFieldAggregationsOptions)

DetectionListOptions

JSON representation 
{
  "max_returned_detections": integer
}
Fields
max_returned_detections

integer

FunctionParameter

JSON representation 
{
  "grouped_fields": [
    {
      object (GroupByField)
    }
  ],
  "selected_fields": [
    {
      object (SelectedField)
    }
  ],
  "orders": [
    {
      object (OrderBy)
    }
  ],
  "max_returned_rows": integer
}
Fields
grouped_fields[]

object (GroupByField)
selected_fields[]

object (SelectedField)
orders[]

object (OrderBy)
max_returned_rows

integer (uint32 format)

GroupByField

JSON representation 
{
  "udm_field_path": string,
  "to_lower_case": boolean,

  // Union field transformation can be only one of the following:
  "resolution_in_nano_seconds": string,
  "cidr_prefix_length_in_bits": integer,
  "top_n_level_domain": integer,
  "get_registered_domain": boolean
  // End of list of possible types for union field transformation.
}
Fields
udm_field_path

string
to_lower_case

boolean

Union field transformation.

transformation can be only one of the following:
resolution_in_nano_seconds

string
cidr_prefix_length_in_bits

integer (uint32 format)
top_n_level_domain

integer (uint32 format)
get_registered_domain

boolean

SelectedField

JSON representation 
{
  "udm_field_path": string,
  "function_type": enum (FunctionType),
  "percentile": number
}
Fields
udm_field_path

string
function_type

enum (FunctionType)
percentile

number

FunctionType

Enums
FUNCTION_TYPE_UNSPECIFIED
FUNCTION_TYPE_SUM
FUNCTION_TYPE_COUNT
FUNCTION_TYPE_COUNT_DISTINCT
FUNCTION_TYPE_AVERAGE
FUNCTION_TYPE_STDDEV
FUNCTION_TYPE_MIN
FUNCTION_TYPE_MAX

OrderBy

JSON representation 
{
  "field_index": integer,
  "is_descending_order": boolean
}
Fields
field_index

integer (uint32 format)
is_descending_order

boolean

UdmPrevalenceOptions

JSON representation 
{
  "get_prevalence": boolean,
  "bucket_size": {
    object (UdmSearchAggregationBucketFunction)
  }
}
Fields
get_prevalence

boolean
bucket_size

object (UdmSearchAggregationBucketFunction)

UdmSearchAggregationBucketFunction

JSON representation 
{
  "resolution_in_seconds": integer
}
Fields
resolution_in_seconds

integer

FederationMetadata

Federation metadata definition. UI will use this to provide information about the instance and instance groups on which federated search is to be performed.

JSON representation 
{
  "instances": [
    {
      object (InstanceSelection)
    }
  ],
  "federation_groups": [
    {
      object (FederationGroupSelection)
    }
  ]
}
Fields
instances[]

object (InstanceSelection)

Optional. List of instances on which federated search request is being made.
federation_groups[]

object (FederationGroupSelection)

Optional. List of instance groups on which federated search request is being made.

InstanceSelection

Chronicle instance on which federated search request is being made.

JSON representation 
{
  "instance": string
}
Fields
instance

string

Required. Chronicle instance name on which federated search request is being made. Format: projects/{project}/locations/{location}/instances/{instance}

FederationGroupSelection

Chronicle federation group on which federated search request is being made.

JSON representation 
{
  "federation_group": string
}
Fields
federation_group

string

Optional. Resource name of the Federation Group. Format: projects/{project}/locations/{location}/instances/{instance}/federationGroups/{federation_group}

Stats

LINT.IfChange(stats_data) Stats results when the query is for statistics NEXT TAG = 6;

JSON representation 
{
  "results": [
    {
      object (ColumnData)
    }
  ],
  "data_query_expression": string,
  "too_many_results": boolean,
  "total_results": integer,
  "sort_order": [
    {
      object (ColumnSort)
    }
  ]
}
Fields
results[]

object (ColumnData)

Result rows that are queried.
data_query_expression

string

Expression that represent the subset of the requested query used to filter data. The expression will be used to enable features such as drill-down from stats results to UDM events. In that case, the new query will be composed by this expression and the expression related to a stats result.
too_many_results

boolean

If true, there are too many results to return and some have been omitted.
total_results

integer

The total number of results returned.
sort_order[]

object (ColumnSort)

Indicates the columns used for sorting and the order in which they are sorted. If no ORDER section is specified in the query, this will be empty.

ColumnData

Represents a single column in the set of columns returned as the stats query result.

JSON representation 
{
  "column": string,
  "values": [
    {
      object (ColumnType)
    }
  ],
  "filterable": boolean,
  "filter_expression": string,
  "column_metadata": {
    object (ColumnMetadata)
  }
}
Fields
column

string

Used to store column names.
values[]

object (ColumnType)

To store store column data.
filterable

boolean

To identify if the column can be used for filtering/drill-downs.
filter_expression

string

Expression used to compose a query for filtering/drill-downs related to the data in this column.
column_metadata

object (ColumnMetadata)

Metadata for the column.

ColumnType

Singular vs list of values in a column.

JSON representation 
{

  // Union field type can be only one of the following:
  "value": {
    object (ColumnValue)
  },
  "list": {
    object (List)
  }
  // End of list of possible types for union field type.
}
Fields

Union field type.

type can be only one of the following:
value

object (ColumnValue)

Single value in a column.
list

object (List)

List of values in a column e.g. IPs

ColumnValue

Value of the column based on data type

JSON representation 
{

  // Union field value can be only one of the following:
  "null_val": boolean,
  "bool_val": boolean,
  "bytes_val": string,
  "double_val": number,
  "int64_val": string,
  "uint64_val": string,
  "string_val": string,
  "timestamp_val": string,
  "date_val": {
    object (Date)
  },
  "proto_val": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field value.
}
Fields

Union field value.

value can be only one of the following:
null_val

boolean

True if the value is NULL.
bool_val

boolean

Boolean value.
bytes_val

string (bytes format)

Bytes value.

A base64-encoded string.
double_val

number

Double value.
int64_val

string (int64 format)

Integer value (signed).
uint64_val

string

Un-signed integer value.
string_val

string

String value. Enum values are returned as strings.
timestamp_val

string (Timestamp format)

Timestamp values.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
date_val

object (Date)

Date values.
proto_val

object

For any proto values that are not any of the above.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

List

Store list of values in a column.

JSON representation 
{
  "values": [
    {
      object (ColumnValue)
    }
  ]
}
Fields
values[]

object (ColumnValue)

List of values in one cell of the column.

ColumnMetadata

LINT.IfChange(column_metadata) Metadata for a column.

JSON representation 
{
  "column": string,
  "field_path": string,
  "function_name_used": string,
  "function_module": string
}
Fields
column

string

Name of the column.
field_path

string

Field path of the column. eg: "udm.principal.hostname"
function_name_used

string

Function name of the column. eg: "ARRAY_IGNORE_NULLS_LIMIT", this corresponds to array function.
function_module

string

Module name of the column.

ColumnSort

Contains the column name and which direction the column is sorted (ascending or descenging).

JSON representation 
{
  "name": string,
  "descending": boolean
}
Fields
name

string

Name of the column.
descending

boolean

Whether the column is sorted in descending order (ascending by default);

SearchDataSource

Data source for stats results in LegacyFetchUdmSearchViewResponse Equivalent to dashboard API LINT.IfChange(data_sources)

Enums
SEARCH_DATA_SOURCE_UNSPECIFIED Unspecified data source.
SEARCH_UDM Events
SEARCH_ENTITY Entities
SEARCH_RULE_DETECTIONS To be used for detections data source.
SEARCH_RULESETS To be used for ruleset with detections datasource.