Функция ai_forecast

Область применения: Databricks SQL

ai_forecast() — это табличное значение функции, которая экстраполирует данные временных рядов в течение времени. Сведения о доступных аргументах см. в разделе "Аргументы " для настройки этой функции.

Функция имеет две версии. Модель фонда временных рядов, оптимизированная для исследований, обеспечивает улучшенную точность вне коробки, а версия 2 добавляет поддержку праздников, внешних ковариатов и не-отрицательных прогнозов. version Используйте аргумент, чтобы выбрать, какая версия выполняется. Дополнительные сведения см. в аргументах .

Требования

• Хранилище SQL Pro или бессерверное хранилище SQL
• Зарегистрируйте рабочую область в предварительной версии прогнозных функций ИИ (обязательно для рекомендуемой версии 2). См. статью "Управление предварительными версиями Azure Databricks".

Синтаксис

Версия 2 (рекомендуется)

ai_forecast(observed, horizon, time_col, value_col
  [, group_col] [, covariate_col] [, prediction_interval_width]
  [, frequency] [, holiday_region] [, positive_only] [, version])

Версия 1

ai_forecast(observed, horizon, time_col, value_col
  [, group_col] [, prediction_interval_width] [, frequency]
  [, seed] [, parameters] [, version])

Аргументы

ai_forecast() может прогнозировать любое количество групп (см group_col. ) и до 100 метрик (см value_col. в каждой группе). Частота прогнозирования одинакова для всех метрик в группе, но может отличаться между группами (см. раздел frequency).

Версия 2 (рекомендуется)

• observed — это табличное значение входных данных, которые используются в качестве обучающих данных для процедуры прогнозирования.
  • Это отношение входных данных должно содержать один столбец time и один или несколько столбцов value. Столбцы Group и covariate являются необязательными. Все дополнительные столбцы во входной связи игнорируются.
• horizon — это величина, подлежащая переводу в метку времени, представляющая время окончания результатов прогнозов, не включая её. В группе (см. group_col) результаты прогноза охватывают время между последним наблюдением и горизонтом. Если горизонт меньше последнего времени наблюдения, то результаты не создаются.
• time_col — это строка, ссылающаяся на "столбец времени" в observed. Столбец, на который ссылается, time_col должен быть столбцом DATE или .TIMESTAMP
• value_col — это строка или массив строк, ссылающихся на столбцы значений в observed. Столбцы, на которые ссылается этот аргумент, должны быть приведения DOUBLE.
• group_col (необязательно) — это строка или массив строк, представляющий столбцы группы в observed. При указании столбцы групп используются в качестве критериев секционирования и прогнозы создаются для каждой группы независимо. Если не указано, полные входные данные обрабатываются как одна группа.
• covariate_col (необязательно) — это строка или массив строк, ссылающихся на внешние ковариатные столбцы в observed. Ковариации — это дополнительные переменные, влияющие на прогноз, такие как цена, маркетинговые расходы или погода. Поддерживаются два типа ковариатов:
  • Будущие ковариации: значения известны для горизонта прогнозирования, например запланированные цены или запланированные кампании. Чтобы использовать ковариат таким образом, включите строки в observed том, что охватывает горизонт прогнозирования (даты после последнего наблюдения, до horizon) с заполненным ковариатом и value_col столбцами слева NULL. ai_forecast прогнозирует эти NULLстроки и условия прогноза по их ковариатным значениям.
  • Только прошлые ковариаты: значения известны только в течение исторического периода, например наблюдаемых погодных или макроэкономических показателей. Заполните ковариат только в исторических строках. Если вы не предоставляете ковариатные значения по горизонту прогнозирования, использует ковариат как только прошлый; ai_forecast это не ошибка.
• prediction_interval_width (необязательно) — это значение от 0 до 1, представляющее ширину интервала прогнозирования. Прогнозируемые значения имеют prediction_interval_width % вероятность падения между {v}_upper и {v}_lower.
• frequency (необязательно) — это строка псевдонима смещения pandas (например, 'D', 'W', , 'ME') 'H'с указанием детализации времени результатов прогнозирования. Если не указано, прогноз детализации автоматически выводится для каждой группы независимо. Если он указан, он должен соответствовать вычисленной детализации входных данных в каждой группе.
  • Выводимая частота в группе — это мода последних наблюдений. Это удобное действие, которое не настраивается пользователем.
  • Например, временный ряд с 99 "понедельниками" и 1 "вторник" приводит к тому, что "неделя" является выводимой частотой.
• holiday_region (необязательно) — это код региона, который позволяет автоматически моделировать эффекты праздников для этого региона, например 'US'. Если не указано, эффекты праздников моделироваются.
• positive_only (необязательно) если задано значение TRUE, ограничивает прогнозируемые значения не отрицательными. Используйте этот аргумент для метрик, которые не могут быть отрицательными, такими как продажи, подсчеты или инвентаризация. По умолчанию — FALSE.
• version (необязательно): переключение версий для поддержки миграции ('1' для поведения '2' версии 1 для поведения версии 2). Если не указано, по умолчанию используется версия 1. Для аргументов версии 2 (covariate_col, holiday_region, positive_only) требуется version => '2'.

Версия 1

• observed — это табличное значение входных данных, которые используются в качестве обучающих данных для процедуры прогнозирования.
  • Это отношение входных данных должно содержать один столбец time и один или несколько столбцов value. Столбцы group и parameters являются необязательными. Все дополнительные столбцы во входной связи игнорируются.
• horizon — это величина, подлежащая переводу в метку времени, представляющая время окончания результатов прогнозов, не включая её. В группе (см. group_col) результаты прогноза охватывают время между последним наблюдением и горизонтом. Если горизонт меньше последнего времени наблюдения, то результаты не создаются.
• time_col — это строка, ссылающаяся на "столбец времени" в observed. Столбец, на который ссылается, time_col должен быть столбцом DATE или .TIMESTAMP
• value_col — это строка или массив строк, ссылающихся на столбцы значений в observed. Столбцы, на которые ссылается этот аргумент, должны быть приведения DOUBLE.
• group_col (необязательно) — это строка или массив строк, представляющий столбцы группы в observed. При указании столбцы групп используются в качестве критериев секционирования и прогнозы создаются для каждой группы независимо. Если не указано, полные входные данные обрабатываются как одна группа.
• prediction_interval_width (необязательно) — это значение от 0 до 1, представляющее ширину интервала прогнозирования. Прогнозируемые значения имеют prediction_interval_width % вероятность падения между {v}_upper и {v}_lower.
• frequency (необязательно) — это строка, служащая псевдонимом смещений в pandas, или единица времени, указывающая временную детализацию результатов прогнозирования. Если не указано, прогноз детализации автоматически выводится для каждой группы независимо. Если задано значение частоты, оно применяется одинаково ко всем группам.
  • Выводимая частота в группе — это мода последних наблюдений. Это удобное действие, которое не настраивается пользователем.
  • Например, временный ряд с 99 "понедельниками" и 1 "вторник" приводит к тому, что "неделя" является выводимой частотой.
• seed (необязательно) — это число, используемое для запуска любых генераторов псевдорандомных чисел, используемых в процедуре прогнозирования.
• parameters (необязательно) — это строковый код JSON или имя идентификатора столбца, представляющего параметризацию процедуры прогнозирования. Любое сочетание параметров можно указать в любом порядке, например {"weekly_order": 10, "global_cap": 1000}. Все неопределенные параметры автоматически определяются на основе атрибутов обучающих данных. Поддерживаются следующие параметры:
  • global_cap и global_floor можно использовать вместе или независимо для определения возможного домена значений метрик. {"global_floor": 0}, например, можно использовать, чтобы ограничить метрики, такие как затраты, чтобы они всегда были положительными. Эти ограничения применяются глобально к данным обучения и прогнозируемым данным и не могут использоваться для обеспечения жестких ограничений только для прогнозируемых значений.
  • daily_order и weekly_order задают порядок Фурье для компонентов сезонности с ежедневной и еженедельной периодичностью.
• version (необязательно): переключение версий для поддержки миграции ('1' для поведения '2' версии 1 для поведения версии 2). Если не указано, по умолчанию используется версия 1. Для аргументов версии 2 (covariate_col, holiday_region, positive_only) требуется version => '2'.

Возвраты

Версия 2 (рекомендуется)

Новый набор строк, содержащих прогнозируемые данные. Схема выходных данных содержит столбцы времени и группы с их типами без изменений. Например, если входной столбец времени имеет тип DATE, то также DATEиспользуется тип выходного столбца времени. Для каждого столбца значений есть три выходных столбца с шаблоном {v}_forecast, {v}_upperи {v}_lower. Независимо от типов входных значений, прогнозируемые значения в столбцах всегда имеют тип DOUBLE. В выходной таблице содержатся только прогнозируемые значения, охватывающие диапазон времени между окончанием наблюдаемых данных до горизонта.

В следующей таблице показаны некоторые примеры вывода схемы, выполняемой AI_FORECAST:

Версия 1

Новый набор строк, содержащих прогнозируемые данные. Схема выходных данных содержит столбцы времени и группы с их типами без изменений. Например, если входной столбец времени имеет тип DATE, то также DATEиспользуется тип выходного столбца времени. Для каждого столбца значений есть три выходных столбца с шаблоном {v}_forecast, {v}_upperи {v}_lower. Независимо от типов входных значений, прогнозируемые значения в столбцах всегда имеют тип DOUBLE. В выходной таблице содержатся только прогнозируемые значения, охватывающие диапазон времени между окончанием наблюдаемых данных до горизонта.

В следующей таблице показаны некоторые примеры вывода схемы, выполняемой AI_FORECAST:

Примеры

Версия 2 (рекомендуется)

В следующем примере прогнозируются до указанной даты с помощью версии 2:

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  version => '2'
)

В следующем примере моделируется эффекты праздников для США и ограничивает прогноз не отрицательными значениями:

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  holiday_region => 'US',
  positive_only => true,
  version => '2'
)

В следующем примере используется внешний ковариат. Таблица observed (daily_sales) включает столбец, заполненный как историческим периодом promotion , так и горизонтом прогнозирования, с revenue левым NULL на строках прогноза горизонта, поэтому promotion используется в качестве будущего ковариации:

SELECT * FROM AI_FORECAST(
  TABLE(daily_sales),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  covariate_col => 'promotion',
  version => '2'
)

Версия 1

В следующем примере прогноз данных выполняется до указанной даты.

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue'
)

Ниже приведен более сложный пример:

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    dropoff_zip,
    SUM(fare_amount) AS revenue,
    COUNT(*) AS n_trips
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1, 2
),
spine AS (
  SELECT all_dates.ds, all_zipcodes.dropoff_zip
  FROM (SELECT DISTINCT ds FROM aggregated) all_dates
  CROSS JOIN (SELECT DISTINCT dropoff_zip FROM aggregated) all_zipcodes
)
SELECT * FROM AI_FORECAST(
  TABLE(
    SELECT
      spine.*,
      COALESCE(aggregated.revenue, 0) AS revenue,
      COALESCE(aggregated.n_trips, 0) AS n_trips
    FROM spine LEFT JOIN aggregated USING (ds, dropoff_zip)
  ),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => ARRAY('revenue', 'n_trips'),
  group_col => 'dropoff_zip',
  prediction_interval_width => 0.9,
  parameters => '{"global_floor": 0}'
)

Для разреженных данных рекомендуется объединять отсутствующие значения или явно предоставлять значение частоты, чтобы избежать непредвиденных выходных данных из вывода "авто" частоты. Например, "автоматическое" вывод частоты на двух записях в 14 дней в разных днях определяет частоту "14D", даже если "реальная" частота может быть еженедельной с 1 отсутствующим значением. Объединение отсутствующих записей удаляет эту неоднозначность.

В следующем примере показано, как различные параметры прогноза применяются к разным группам в входной таблице. В этом примере аргумент parameters используется в качестве идентификатора столбца. Этот подход позволяет пользователям хранить ранее определенные параметры JSON в таблице и повторно использовать их в новых данных.

WITH past AS (
  SELECT
    CASE
      WHEN fare_amount < 30 THEN 'Under $30'
      ELSE '$30 or more'
    END AS revenue_bucket,
    CASE
      WHEN fare_amount < 30 THEN '{"daily_order": 0}'
      ELSE '{"daily_order": "auto"}'
    END AS parameters,
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM samples.nyctaxi.trips
  GROUP BY ALL
)
SELECT * FROM AI_FORECAST(
  TABLE(past),
  horizon => (SELECT MAX(ds) + INTERVAL 30 DAYS FROM past),
  time_col => 'ds',
  value_col => 'revenue',
  group_col => ARRAY('revenue_bucket'),
  parameters => 'parameters'
)

Ограничения

Версия 2 (рекомендуется)

Следующие ограничения применяются во время бета-версии:

• Версия 2 находится в бета-версии и не является стандартной. Чтобы использовать версию 2, войдите по параметру version => '2'. Версия 1, которая находится в общедоступной предварительной версии, остается стандартной.
• Процедура прогнозирования по умолчанию — это модель основы временных рядов. Эта модель является единственной поддерживаемой процедурой прогнозирования.
• Сообщения об ошибках доставляются через обработчик UDTF Python и содержат сведения о обратной трассировке Python. Конец трассировки содержит фактическое сообщение об ошибке.
• Каждый вызов ai_forecast выполняет независимое вывод. При вызове ai_forecast нескольких раз с разными prediction_interval_width значениями для создания вложенных интервалов прогнозирования результирующие интервалы не гарантируют правильное вложение. Чтобы сравнить интервалы прогнозирования, используйте один вызов с одним ai_forecastprediction_interval_width значением.

Версия 1

Следующие ограничения применяются во время общедоступной предварительной версии:

• Версия 1 находится в общедоступной предварительной версии и является версией по умолчанию. Версия 2, которая находится в бета-версии, доступна по параметру version => '2'.
• Версия 1 находится в нерекомендуемом пути. В предстоящем выпуске версия по умолчанию изменяется на версию 2 и версию 1 не рекомендуется. Чтобы сохранить поведение версии 1 после изменений по умолчанию, закрепите его, установив параметр version => '1'.
• Процедура прогнозирования по умолчанию — это модель прогнозирования, похожая на пророка, а также модель сезонности. Эта модель является единственной поддерживаемой процедурой прогнозирования.
• Сообщения об ошибках доставляются через обработчик UDTF Python и содержат сведения о обратной трассировке Python. Конец трассировки содержит фактическое сообщение об ошибке.
• Каждый вызов ai_forecast выполняет независимую регрессию квантиля. При вызове ai_forecast нескольких раз с разными prediction_interval_width значениями для создания вложенных интервалов прогнозирования результирующие интервалы не гарантируются правильно вложенными, так как квантили вычисляются независимо между вызовами, без ограничений для проверки правильного порядка. Чтобы сравнить интервалы прогнозирования, используйте один вызов с одним ai_forecastprediction_interval_width значением.