Skip to main content

Helper JS Reference

Primary file: includes/core/modules/anomaly_detection/helpers.js

This helper layer centralizes SQL generation, naming conventions, and configuration validation used by:

  • 02_intermediate/time_series.js
  • 02_intermediate/model_training.js
  • 02_intermediate/anomalies.js
  • 03_outputs/report.js

Core responsibilities​

  1. Build reusable SQL fragments.
  2. Normalize and sanitize identifiers.
  3. Resolve and merge case configurations (core + custom).
  4. Validate configuration shape and allowed values.
  5. Standardize model and table naming.

Function groups​

SQL builders for date windows​

  • generateDeclareDatesSQL(config): resolves explicit vs rolling training window and declares start_date / end_date variables. Throws a compile-time error if neither mode is fully defined.
  • generateDeclareDetectionDatesSQL(config): builds detection window date declarations from anomaly_detection_end_days_ago and anomaly_detection_window_days.

SQL builders for series construction​

  • generateBaseQuerySQL(config, tbl): raw date-filtered source extraction from the configured source table.
  • generateFullSeriesQuerySQL(config): full-grain aggregation producing one row per timestamp and dimension combination.
  • generateSingleDimensionsQuerySQL(config): per-dimension stacked variants, generated only when two or more ID columns are configured.
  • generateStackedQuerySQL(config): unions the full series with all single-dimension variants.
  • generateTrainingQuerySQL(config, ref): full training query wrapper (deprecated in favor of in-file generation; retained for compatibility).

SQL builders for IDs and joins​

  • generateSeriesIdConcatSQL(config): builds a stable text series key from the configured dimension columns.
  • generateColumnListSQL(config): sanitized comma-separated ID column list.
  • generateUsingClauseSQL(config): join USING (...) clause built from ID columns.
  • generateTimeSeriesIdArraySQL(config): BQML TIME_SERIES_ID_COL array literal.

Model and training helpers​

  • generateModelNameSQL(config, caseName): fully-qualified BQML model name using project, dataset, and optional model_version.
  • generateSeriesStrengthConditionSQL(config): training-strength filter expression from training_min_series_days and training_min_series_avg.

Top-N series helpers​

  • getTopNTimeSeries(config): returns the numeric value of top_n_time_series, or null if the field is absent, empty, or null.
  • hasTopNTimeSeries(config): returns true when top_n_time_series is set to a valid positive integer.

Configuration loading and validation​

  • getCaseConfig(caseName): merges the core case YAML with an optional custom override file. Custom values override core values field by field.
  • validateCaseConfig(config): validates required fields, normalizes optional fields, and throws a combined error listing all failures.

Validation behavior highlights​

  • Requires case_data_project, case_data_dataset, case_data_table, time_series_timestamp_col, and time_series_data_col.
  • Normalizes time_series_id_cols to [] when absent or null; does not require at least one entry.
  • Normalizes top_n_time_series to null when absent, empty, or null; requires a positive integer when set.
  • Restricts time_series_data_agg to sum, count, or count_distinct.
  • Validates model_cron format when the field is present.
  • Throws a compile-time error if training date configuration is invalid (neither explicit dates nor rolling offsets fully defined).

Why this file matters​

This file is relevant when extending the module or debugging unexpected pipeline output. For most configuration tasks, the Configurable Variables reference is sufficient.

When adding a new case or debugging pipeline output, this helper file is the fastest way to understand how SQL is generated, how naming is derived, and why certain configurations fail validation.