菜单

Event Analysis Request Generation Guide

Event Analysis Request Generation Guide

Use this guide to generate minimal event analysis request parameters. Requests should be compact, stable, and name-driven.

Core Rule

Generate requests with stable names:

  • Use eventName for events.
  • Use analysis[0] or property names inside customEvents for event properties.
  • Use columnName for filter and group properties.
  • Use customEvents for formula metrics.

Do not generate:

  • eventID
  • property id
  • frontend-only display or interaction metadata
  • empty frontend metadata fields

Top-Level Shape

Minimal shape:

json 复制代码 
{
  "eventsSelect": [],
  "eventsFilter": {
    "relation": "and",
    "filterType": "SIMPLE",
    "filters": []
  },
  "eventsGroup": {
    "globalization": []
  },
  "eventsView": {
    "timeParticleSize": "day",
    "recentDay": "0$$6",
    "dynamicDate": ""
  },
  "timeZoneOffset": 0,
  "dataBase": "dt_xxx"
}

dataBase is required and must use the dt_xxx format.

Default Event Metric

Event count:

json 复制代码 
{
  "eventType": "default",
  "eventName": "$app_install",
  "eventDisplayName": "App Install Count",
  "analysis": ["A100"],
  "relation": "and",
  "filterType": "SIMPLE",
  "filters": []
}

Event property aggregation:

json 复制代码 
{
  "eventType": "default",
  "eventName": "#ad_paid",
  "eventDisplayName": "Ad Revenue",
  "analysis": ["#ad_value", "A103"],
  "relation": "and",
  "filterType": "SIMPLE",
  "filters": []
}

Formula Metric

Use customEvents for formula metrics.

json 复制代码 
{
  "eventType": "customized",
  "eventDisplayName": "ROAS",
  "customEvents": "#ad_paid.#ad_value.A103 / DT@first_install.vep$cac.A103",
  "format": "PERCENTAGE",
  "relation": "and",
  "filterType": "SIMPLE",
  "filters": [],
  "customFilters": [
    {
      "relation": "and",
      "filterType": "SIMPLE",
      "filters": []
    },
    {
      "relation": "and",
      "filterType": "SIMPLE",
      "filters": []
    }
  ]
}

Rules:

  • Each event factor in customEvents must have one matching item in customFilters.
  • The order of customFilters must match the order of event factors in customEvents.
  • Use format to control formula result formatting.
  • If formula factors participate in event splitting, add eventSplitIndex to the formula metric.

Example:

json 复制代码 
{
  "eventSplitIndex": [0, 1]
}

Filters

Empty filter container:

json 复制代码 
{
  "relation": "and",
  "filterType": "SIMPLE",
  "filters": []
}

Simple filter:

json 复制代码 
{
  "relation": "and",
  "filterType": "SIMPLE",
  "filters": [
    {
      "columnName": "$uid",
      "columnDesc": "DT User ID",
      "columnType": "string",
      "tableType": "event",
      "type": 0,
      "comparator": "C06",
      "filterValue": [],
      "extra": {
        "parent_column_type": null
      }
    }
  ]
}

Nested filter:

json 复制代码 
{
  "relation": "and",
  "filterType": "SIMPLE",
  "filters": [
    {
      "relation": "and",
      "filterType": "SIMPLE",
      "filters": [
        {
          "columnName": "#active_device_brand",
          "columnDesc": "Device Brand",
          "columnType": "string",
          "tableType": "user",
          "type": 1,
          "comparator": "C01",
          "filterValue": ["WIKO", "FCNT"],
          "extra": {
            "parent_column_type": null
          }
        }
      ]
    }
  ]
}

Dimension Property Filter

A dimension property uses type: 4 and requires a minimal extra object.

json 复制代码 
{
  "columnName": "$active_country_code@full_name@zh-CN",
  "columnDesc": "Country/Region",
  "columnType": "string",
  "tableType": "user",
  "type": 4,
  "comparator": "C00",
  "filterValue": ["美国（US）"],
  "extra": {
    "bound_prop": "$active_country_code",
    "dimension_app_id": "conf",
    "dimension_table_type_code": 1
  }
}

Do not generate dimension_id or bound_prop_id for dimension properties.

Object And ObjectArray Properties

Object child properties must include extra.parent_column_type.

Object child property:

json 复制代码 
{
  "columnName": "item.price",
  "columnDesc": "Item Price",
  "columnType": "number",
  "tableType": "event",
  "type": 2,
  "comparator": "C04",
  "filterValue": ["10"],
  "extra": {
    "parent_column_type": "object"
  }
}

ObjectArray child property:

json 复制代码 
{
  "columnName": "items.price",
  "columnDesc": "Item Price",
  "columnType": "number",
  "tableType": "event",
  "type": 2,
  "comparator": "C04",
  "filterValue": ["10"],
  "extra": {
    "parent_column_type": "objectArray"
  }
}

ObjectArray matching uses C25, C26, or C27, and must include a nested filter:

  • C25: the objectArray contains at least one object matching the nested filter.
  • C26: the objectArray contains no object matching the nested filter.
  • C27: all objects in the objectArray match the nested filter.
json 复制代码 
{
  "columnName": "items",
  "columnDesc": "Items",
  "columnType": "objectArray",
  "tableType": "event",
  "type": 2,
  "comparator": "C25",
  "filterValue": [],
  "extra": {
    "parent_column_type": null
  },
  "filter": {
    "relation": "and",
    "filterType": "SIMPLE",
    "filters": [
      {
        "columnName": "items.price",
        "columnDesc": "Item Price",
        "columnType": "number",
        "tableType": "event",
        "type": 2,
        "comparator": "C04",
        "filterValue": ["10"],
        "extra": {
          "parent_column_type": "objectArray"
        }
      }
    ]
  }
}

When a dimension property is bound to an object or objectArray child, keep parent property metadata:

json 复制代码 
{
  "columnName": "items.country@full_name@zh-CN",
  "columnDesc": "Item Country",
  "columnType": "string",
  "tableType": "event",
  "type": 4,
  "comparator": "C00",
  "filterValue": ["美国（US）"],
  "extra": {
    "bound_prop": "country",
    "dimension_app_id": "conf",
    "dimension_table_type_code": 0,
    "bound_parent_prop": "items",
    "bound_parent_prop_type": "objectArray"
  }
}

If an object or objectArray child property is used in event property aggregation, also include boundProp:

json 复制代码 
{
  "eventType": "default",
  "eventName": "#purchase",
  "eventDisplayName": "Item Revenue",
  "analysis": ["items.price", "A103"],
  "relation": "and",
  "filterType": "SIMPLE",
  "filters": [],
  "boundProp": [
    {
      "name": "items.price",
      "parent_column_type": "objectArray"
    }
  ]
}

Grouping

No grouping:

json 复制代码 
{
  "eventsGroup": {
    "globalization": []
  }
}

Simple grouping:

json 复制代码 
{
  "columnName": "#active_screen_height",
  "columnType": "number",
  "tableType": "user",
  "type": 1,
  "displayName": "Screen Height",
  "propertyRangeType": 2,
  "propertyRange": [800],
  "timeGroupType": "daily",
  "extra": {
    "parent_column_type": null
  }
}

Rules:

  • Group properties require displayName.
  • Numeric grouping requires propertyRangeType and propertyRange.
  • For tag properties, keep tagVersion and tagHistoryDate when needed.

Time Range

Dynamic time range:

json 复制代码 
{
  "eventsView": {
    "timeParticleSize": "day",
    "recentDay": "0$$6",
    "dynamicDate": ""
  }
}

Static time range:

json 复制代码 
{
  "eventsView": {
    "timeParticleSize": "day",
    "recentDay": "",
    "dateList": ["2026-06-18", "2026-06-24"],
    "dynamicDate": ""
  }
}

Comparison time range:

json 复制代码 
{
  "eventsView": {
    "timeParticleSize": "day",
    "recentDay": "0$$6",
    "dynamicDate": "",
    "comparedDate": [
      {
        "recentDay": "4$$7",
        "dynamicDate": ""
      }
    ]
  }
}

Rules:

  • Prefer recentDay for dynamic time ranges.
  • Use dateList only for static time ranges.
  • Do not generate comparedDate[].key.

Event Splitting

json 复制代码 
{
  "eventsSpliter": {
    "eventsToSplit": [
      {
        "eventName": "$app_install"
      },
      {
        "eventName": "#session_start"
      }
    ],
    "splitPriority": "first",
    "propertyGroup": [
      {
        "columnName": "#event_name",
        "columnType": "string",
        "tableType": "event",
        "type": 1,
        "displayName": "Event Name",
        "propertyRangeType": 1,
        "propertyRange": [0],
        "timeGroupType": "daily",
        "extra": {
          "parent_column_type": null
        }
      }
    ]
  }
}

Rules:

  • eventsToSplit only needs eventName.
  • Do not generate eventsToSplit[].eventID.
  • If a formula metric participates in splitting, add eventSplitIndex to the formula metric.

Fields To Avoid

When generating minimal requests, do not include:

text 复制代码 
key
eventID
id
has_dimension
name
display_name
describe
data_type
table_type_code
table_type
calcu_symbol
defaultOpen
presetEventDisplayName
boundProp when empty
retention_metrics when empty
update_time
debugQuery
eventsGroup.individuality
comparedDate[].key
empty filter.filter
dimension_id
bound_prop_id
eventsToSplit[].eventID

Final Checklist

Before returning a request, verify:

  • Every event has eventType.
  • Default events have eventName, eventDisplayName, analysis, relation, filterType, and filters.
  • Formula events have customEvents, eventDisplayName, format, and customFilters.
  • The number of customFilters items matches the number of event factors in customEvents.
  • Filters use columnName, columnType, tableType, type, comparator, filterValue, and extra.
  • Groups use columnName, columnType, tableType, type, and displayName.
  • The request does not include eventID or property id.
上一个
事件分析请求参数生成指南
下一个
留存分析模型API
最近修改: 2026-06-24