Функция `ai_forecast`

Статья
01/23/2025

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

Внимание

Эта функция доступна в общедоступной предварительной версии и соответствует требованиям HIPAA. Обратитесь к группе учетной записи Databricks, чтобы принять участие в предварительной версии.

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

Требование

Хранилище Sql Pro или Бессерверное хранилище SQL

Синтаксис


ai_forecast(
  observed TABLE,
  horizon DATE | TIMESTAMP | STRING,
  time_col STRING,
  value_col STRING | ARRAY<STRING>,
  group_col STRING | ARRAY<STRING> | NULL DEFAULT NULL,
  prediction_interval_width DOUBLE DEFAULT 0.95,
  frequency STRING DEFAULT 'auto',
  seed INTEGER | NULL DEFAULT NULL,
  parameters STRING DEFAULT '{}'
)

Аргументы

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

Ниже приведены доступные аргументы для этой функции:

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 задают порядок Фурье для компонентов сезонности с ежедневной и еженедельной периодичностью.

Возвраты

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

См. некоторые примеры вывода схемы, выполненные AI_FORECAST ниже:

Входная таблица	Аргументы	Выходная таблица
`ts: TIMESTAMP` `val: DOUBLE`	`time_col => 'ts'` `value_col => 'val'`	`ts: TIMESTAMP` `val_forecast: DOUBLE` `val_upper: DOUBLE` `val_lower: DOUBLE`
`ds: DATE` `val BIGINT`	`time_col => 'ds'` `value_col => 'val'`	`ds: DATE` `val_forecast: DOUBLE` `val_upper: DOUBLE` `val_lower: DOUBLE`
`ts: TIMESTAMP` `dim1: STRING` `dollars: DECIMAL(10, 2)`	`time_col => 'ts'` `value_col => 'dollars'` `group_col => 'dim1'`	`ts: TIMESTAMP` `dim1: STRING` `dollars_forecast: DOUBLE` `dollars_upper: DOUBLE` `dollars_lower: DOUBLE`
`ts: TIMESTAMP` `dim1: STRING` `dim2: BIGINT` `dollars: DECIMAL(10, 2)` `users: BIGINT`	`time_col => 'ts'` `value_col => ARRAY('dollars', 'users')` `group_col => ARRAY('dim1', 'dim2')`	`ts: TIMESTAMP` `dim1: STRING` `dim2: BIGINT` `dollars_forecast: DOUBLE` `dollars_upper: DOUBLE` `dollars_lower: DOUBLE` `users_forecast: DOUBLE` `users_upper: DOUBLE` `users_lower: DOUBLE`

Примеры

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


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}'
)

Заметка

Таблицы постоянно не показывают 0 или пустые записи. Если значения отсутствующих записей можно вывести, например 0, то сначала объедините эти значения, а затем вызовите функцию ai_forecast. Если значения действительно отсутствуют или неизвестны, их можно оставить как NULL.

Для очень разреженных данных рекомендуется замещать отсутствующие значения или явно указывать значение частоты, чтобы избежать непредвиденных результатов от использования автоматического определения частоты. Например, "автоматическое" вывод частоты двух записей в течение 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'
)

Ограничения

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

Процедура прогнозирования по умолчанию — это модель прогнозирования, похожая на пророка, а также модель сезонности. Это единственная поддерживаемая процедура прогнозирования.
Сообщения об ошибках доставляются через обработчик UDTF Python и содержат сведения о обратной трассировке Python. Конец трассировки содержит фактическое сообщение об ошибке.

Поделиться через

Функция `ai_forecast`

Требование

Синтаксис

Аргументы

Возвраты

Примеры

Ограничения

Обратная связь

Дополнительные ресурсы

Поделиться через

Функция ai_forecast

Требование

Синтаксис

Аргументы

Возвраты

Примеры

Ограничения

Обратная связь

Дополнительные ресурсы

Функция `ai_forecast`