QueryTimeDimension should be specified for the compare date

Error message

QueryTimeDimension should be specified for the compare date range query.

What it means

get_date_range_value extracts the date range from a query's time dimensions when building a compare-date-range query (period-over-period comparison). A compare query is meaningless without at least one QueryTimeDimension, so the function bails when the time_dimensions parameter is None. Callers include build_compact_plan, VanillaTail::CompareDateRange, and ColumnarColumnPlan in the Rust query orchestrator.

Source

Thrown at rust/cube/cubeorchestrator/src/query_result_transform.rs:231

                        Utc.from_utc_datetime(&dt)
                            .format("%Y-%m-%dT%H:%M:%S%.3f")
                            .to_string()
                    })
                })
                .unwrap_or_else(|_| s.clone());
            DBResponsePrimitive::String(formatted)
        }
        other => other,
    }
}

/// Parse date range value from time dimension.
pub fn get_date_range_value(
    time_dimensions: Option<&Vec<QueryTimeDimension>>,
) -> Result<DBResponsePrimitive> {
    let time_dimensions = match time_dimensions {
        Some(time_dimensions) => time_dimensions,
        None => bail!("QueryTimeDimension should be specified for the compare date range query."),
    };

    let dim = match time_dimensions.first() {
        Some(dim) => dim,
        None => bail!("No time dimension provided."),
    };

    let date_range: &Vec<String> = match &dim.date_range {
        Some(date_range) => date_range,
        None => bail!("Inconsistent QueryTimeDimension configuration: dateRange required."),
    };

    if date_range.len() == 1 {
        bail!(
            "Inconsistent dateRange configuration for the compare date range query: {}",
            date_range[0]
        );
    }

View on GitHub (pinned to 7d981676b3)

Solutions

Add a timeDimensions entry with a dateRange to the query when using compareDateRange
Verify the client SDK serializes timeDimensions for the compare query (not stripped by a transform)
Check the query JSON reaching the orchestrator — compareDateRange requires timeDimensions[0] with dateRange

Example fix

// before: compare without a time dimension
{"compareDateRange": {"compares": [...]}}

// after
{"timeDimensions": [{"dimension": "Events.timestamp", "dateRange": ["2024-01-01", "2024-01-31"]}], "compareDateRange": {"compares": [...]}}

Defensive patterns

Strategy: validation

Validate before calling

fn has_time_dimensions(q: &Query) -> bool {
    q.time_dimensions.as_ref().map_or(false, |t| !t.is_empty())
}
// call before issuing a compareDateRange query
assert!(has_time_dimensions(&query), "compareDateRange requires timeDimensions");

Type guard

fn has_time_dimensions(q: &Query) -> bool {
    q.time_dimensions.as_ref().map_or(false, |t| !t.is_empty())
}

Try / catch

match build_compact_plan(&query) {
    Err(e) if e.to_string().contains("QueryTimeDimension should be specified") => {
        eprintln!("Add a timeDimensions entry with dateRange for compareDateRange queries");
    }
    other => other?,
}

Prevention

Always define timeDimensions with a dateRange when using compareDateRange
Validate query payloads client-side before sending
Check that query transforms do not strip timeDimensions

When it happens

Trigger: Building a compact plan / columnar plan for a compareDateRange query where the query's time_dimensions field is absent (None) — e.g. a query with a compareDateRange flag but no time dimension defined.

Common situations: Client sends compareDateRange without any timeDimensions entry; a query transform drops time dimensions before the compare step; hand-constructed query JSON missing timeDimensions.

Related errors

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/3f138ab72aa95bb0. Report an issue: GitHub.