UdmSearch parity mapping

Supported in:

This guide details the request and response mapping specifications and property parity analysis for migrating from the legacy Backstory Search API (UdmSearch) to the modern Chronicle API (UdmSearch).

Protocol and mapping overview

Feature Legacy API (UdmSearch) Modern Chronicle API (UdmSearch)
HTTP method GET GET
Permissions Partner token or legacy API keys chronicle.googleapis.com/events.udmSearch

Request payload field-by-field parity

The modern Chronicle API UdmSearchRequest scopes queries under target instance environments and introduces support for SQL syntax dialects.

Legacy field (UdmSearchRequest) Modern field (UdmSearchRequest) Field type Parity and migration notes
— instance (in HTTP path) string Google Cloud scoping context: Scopes the search query under target instance environments: projects/{project}/locations/{location}/instances/{instance}.
query query string Parity mapped: Boolean structured query string (for example, metadata.event_type = "NETWORK_CONNECTION"). Note: Proto tag number changed from 1 to 2.
time_range time_range Interval Parity mapped: Required time interval [start_time, end_time). Note: Proto tag number changed from 2 to 3. Rename to timeRange in JSON.
limit limit int32 Parity mapped: Maximum returned results (coerced to 10k max). Note: Proto tag number changed from 3 to 4.
— query_dialect enum New parameter: Selects query syntax dialect (QueryDialect enum: YL2 or SQL). Defaults to YL2. Rename to queryDialect in JSON.
— simulated_data_visibility enum New parameter: Controls whether simulated or test telemetry data is included in results (SimulatedDataVisibility). Rename to simulatedDataVisibility in JSON.

Response payload field-by-field parity

Both APIs return matched event arrays and truncation reporting flags, with the modern response adding support for SQL statistics tables.

Legacy field (UdmSearchResponse) Modern field (UdmSearchResponse message) Field type Parity and migration notes
events events repeated Event Parity mapped: Array of matched UDM events. As established under GetEvent guide, the modern Event.name property formats event IDs as URL-encoded Base64.
more_data_available more_data_available bool Parity mapped: Flag indicating result truncation when matches exceed limit. Rename to moreDataAvailable in JSON.
— stats_data StatsData New field: Returns tabular statistical columns and rows when the query is executed as an aggregation or statistical SQL query. Rename to statsData in JSON.

Nested StatsData property mappings

The fields mapping inside statistical data structures is as follows:

Legacy field Modern field (StatsData message) Field type Parity and migration notes
— columns repeated StatsColumn New field: Describes the header schema and data types of returned statistical columns.
— rows repeated StatsRow New field: Tabular rows containing repeated StatsColumnValue items matching column schemas.

Key differences

  • Service consolidation:
    • Legacy UDM searching was housed under SearchService (UdmSearch).
    • Modern Chronicle API standardizes this under EventService (UdmSearch), isolating event lookups from general search tooling.
  • Google Cloud project scoping integration:
    • Scoped natively under parent project instance folder bindings (instance path parameter).
  • SQL query and statistics support:
    • The modern Chronicle API introduces query_dialect (SQL), enabling analytical group-by aggregation queries whose tabular outputs are returned using stats_data.
  • Proto tag number shifts:
    • Within protobuf formatting, tag numbers shifted by +1 across request fields (query moved from tag 1 to 2; time_range from tag 2 to 3; limit from tag 3 to 4).
  • IAM permissions:
    • Request validation maps to standard Cloud IAM permission validation check (chronicle.googleapis.com/events.udmSearch).