Skip to content

Acceleration Hit Rules

1. Basic Principles for Acceleration Hits

A query can hit result acceleration only when all of the following conditions are met:

Check Item Core Rule
Metrics All metrics used by the query must be included in the acceleration plan.
Dimensions Dimensions used by the query must be a subset of the dimensions configured in the acceleration plan.
Time Constraint The query time range must be within the available time range of the acceleration plan.
Filters Filters must match the filters in the materialization plan, or the filtered dimensions must be included in the materialization plan.

If any condition is not met, the query cannot hit the acceleration plan.

2. Hit Matching Details

Step 1: Check Whether Metrics Match

Rule:

All metrics used in the query must be included in the metric list of the acceleration plan.

  • Querying fewer metrics is allowed when roll-up is supported.

  • Querying additional metrics is not allowed.

If the query uses only part of the metric list, and the metrics can roll up across all dimensions, the query can still hit the plan.

When metrics in an acceleration plan include filters or time constraints, define the metrics by using metricDefinitions.

Recommended example:

{
  "metrics": [
    "count_order_id_p_rq1gidwb23dvbxneadglx"
  ],
  "metricDefinitions": {
    "count_order_id_p_rq1gidwb23dvbxneadglx": {
      "refMetric": "count_order_id_p",
      "filters": [
        "IN([sex],\"Shanghai\")"
      ],
      "period": "relative_date 0 day of 0 day",
      "metricGrain": "day",
      "indirections": [
        "sameperiod__year__value"
      ]
    }
  }
}

Step 2: Check Whether Dimensions Match

Rule:

Dimensions used by the query must be a subset of the dimensions in the acceleration plan.

  • Querying fewer dimensions is allowed.

  • Querying additional dimensions is not allowed.

Special Notes for Date Dimensions

When an acceleration plan includes a date dimension:

  • Query dimensions must use the standard format:

date_dimension__granularity

Example:

"dimensions": [
  "dt__month"
]

Query Example (Can Hit)

{
  "metrics": [
    "count_order_id_p_rq1gidwb23dvbxneadglx"
  ],
  "metricDefinitions": {
    "count_order_id_p_rq1gidwb23dvbxneadglx": {
      "refMetric": "count_order_id_p",
      "filters": [
        "IN([sex],\"Shanghai\")"
      ],
      "period": "relative_date 0 day of 0 day",
      "metricGrain": "day"
    }
  },
  "dimensions": [
    "dt__month"
  ],
  "filter": [
    "DateTrunc([dt],\"day\") = \"2025-02-02\"",
    "IN([shop_name],\"Pepsi\")"
  ]
}

Cannot Hit

{
  "metrics": [
    "count_order_id_p_rq1gidwb23dvbxneadglx"
  ],
  "metricDefinitions": {
    "count_order_id_p_rq1gidwb23dvbxneadglx": {
      "refMetric": "count_order_id_p",
      "filters": [
        "IN([sex],\"Shanghai\")"
      ],
      "period": "relative_date 0 day of 0 day",
      "metricGrain": "day"
    }
  },
  "dimensions": [
    "dt"
  ],
  "filter": [
    "DateTrunc([dt],\"day\") = \"2025-02-02\"",
    "IN([shop_name],\"Pepsi\")"
  ]
}

Step 3: Check Whether Filters Are Supported by Acceleration

Any of the following cases prevents the query from hitting acceleration:

  • The filter uses a dimension field that is not included in the acceleration plan.

  • The filter applies a function or expression to a dimension field before filtering.

  • The filter uses a dimension that does not appear in dimensions.

Examples

Example 1

The acceleration plan uses dt__day as the date dimension:

"dimensions": [
  "dt__day"
  "metric_time__day"
]

Use the date dimension from dimensions in the filter. Recommended syntax:

"filter": [
  "DateTrunc([dt],\"day\") = DateTrunc(\"2025-02-02\","day")"
]

"filter": [
  "DateTrunc([metric_time],\"day\") = DateTrunc(\"2025-02-02\","day")"
]

Example 2

Dimension match:

API syntax:

Query example (can hit)

Use the following format exactly and pay attention to letter case.

"filters": [
    "(DATETRUNC(['metric_time'], \"DAY\")) = (DATETRUNC(['open_date'], \"DAY\"))"
  ]

Query example (cannot hit)

"filters": [
    "DATETRUNC(['metric_time'], \"day\") = DATETRUNC(['open_date'], \"DAY\")"
  ]

Example 3

The acceleration plan already includes the following filter when it is created:

Query example (hit)

"filter": [
  "IN([shop_name],\"Pepsi\")"
]

Query example (miss)

"filter": [
  "[shop_name]=\"Pepsi\""
]

Step 4: Check Whether the Time Range Is Within the Latest Available Dates

Assume that:

The backfilled data range for the acceleration plan is 2025-01-01 to 2025-12-10.

Query Time Range Hit Result
2025-12-01 to 2025-12-10 Hit
2025-12-11 Miss, because it is outside the available range.
2025-12-01 to 2025-12-11 Hit, because the lower bound is satisfied.
2024-12-12 Miss