Функция `ai_forecast`

Статья
09/18/2024

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

Внимание

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

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

Требования

Доступно только в хранилищах SQL Pro под управлением Databricks SQL версии 2024.35 и выше.

Синтаксис


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, перед вызовом функции прогнозирования эти значения должны быть объединены. Если значения действительно отсутствуют или неизвестны, их можно оставить как NULL.

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

Наконец, мы покажем пример, в котором различные параметры прогноза применяются к разным группам в входной таблице:

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

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

Ограничения

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

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

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

Функция `ai_forecast`

Требования

Синтаксис

Аргументы

Возвраты

Примеры

Ограничения

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

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

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

Функция ai_forecast

Требования

Синтаксис

Аргументы

Возвраты

Примеры

Ограничения

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

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

Функция `ai_forecast`