Материализация представлений функций

Это важно

Эта функция доступна в общедоступной предварительной версии. Администраторы рабочей области могут управлять доступом к этой функции на странице "Предварительные версии ". См. статью "Управление предварительными версиями Azure Databricks".

После создания определений представления функций, хранящихся в каталоге Unity, можно создавать данные компонентов из исходной таблицы с помощью определений компонентов. Этот процесс называется материализацией ваших функций. Azure Databricks создает конвейеры Lakeflow и управляет ими для заполнения таблиц в каталоге Unity для обучения моделей и пакетной оценки или онлайн-обслуживания.

Сведения о обслуживании представлений функций см. в разделе "Обслуживание представлений функций".

Требования

  • Компоненты должны создаваться как представления компонентов и храниться в каталоге Unity.
  • Требования к версии см. в разделе "Требования".
  • ColumnSelection функции можно реализовать в интернет-магазинах. См. материализацию ColumnSelection.
  • RequestSource функции не могут быть материализованы, так как они представляют данные, предоставленные во время вывода.

Разрешения

Материализация взаимодействует с привилегиями MANAGE и READ FEATURE в Unity Catalog для этой функции. Полные описания привилегий см. в разделе READ FEATURE.

  • Для материализации функции требуется MANAGE. Вызов materialize_features или delete_materialized_feature создает базовые конвейеры Lakeflow и таблицы Unity Catalog и управляет ими, поэтому это операция управления. Необходимо иметь MANAGE для компонента, а также READ FEATURE для чтения материализуемого определения компонента.
  • Для чтения материализованных данных требуется READ FEATURE. READ FEATURE функция предоставляет доступ к автономным и онлайн-таблицам, которые его содержат, чтобы можно было использовать материализованные данные для обучения моделей и обслуживания. Для list_materialized_features также требуется READ FEATURE.

Как и для любого объекта Unity Catalog, необходимо также иметь USE CATALOG для родительского каталога и USE SCHEMA для родительской схемы. READ FEATURE и MANAGE, предоставленные для схемы или каталога, применяются ко всем текущим и будущим объектам, содержащимся в них.

Структуры данных API

OfflineStoreConfig

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

OfflineStoreConfig(
    catalog_name: str,        # Catalog name for the offline table where materialized features will be stored
    schema_name: str,         # Schema name for the offline table
    table_name_prefix: str    # Table name prefix for the offline table. The pipeline may create multiple tables with this prefix, each updated at different cadences
)

from databricks.feature_engineering.entities import OfflineStoreConfig

offline_store = OfflineStoreConfig(
    catalog_name="main",
    schema_name="feature_store",
    table_name_prefix="customer_features"
)

OnlineStoreConfig

Конфигурация для интернет-магазина, в котором хранятся функции, используемые службой моделей. Материализация создает Delta-таблицы с помощью catalog.schema.table_name_prefix и передает таблицы в Онлайн-хранилище признаков с тем же именем.

from databricks.feature_engineering.entities import OnlineStoreConfig

online_store = OnlineStoreConfig(
    catalog_name="main",
    schema_name="feature_store",
    table_name_prefix="customer_features_serving",
    online_store_name="customer_features_store"
)

MaterializedFeature

Представляет представление компонентов, которое было материализовано, т. е. имеет предварительно вычисляемое представление, доступное в каталоге Unity. Существуют отдельные материализованные функции для автономной таблицы и интерактивной таблицы. Как правило, пользователи не будут напрямую создавать экземпляры MaterializedFeature.

Вызовы функций API

materialize_features()

Материализует список представлений функций в автономную таблицу Delta или в Интернет-хранилище компонентов. Компоненты должны быть зарегистрированы в каталоге Unity перед вызовом этой функции (например, с помощью create_feature или register_feature). Локально созданные компоненты, которые не были зарегистрированы, не будут работать.

FeatureEngineeringClient.materialize_features(
    features: List[Feature],                                               # List of Feature Views to materialize
    offline_config: Optional[OfflineStoreConfig] = None,                   # Offline store config (aggregation features only)
    online_config: Optional[OnlineStoreConfig] = None,                     # Online store config
    trigger: Union[CronSchedule, TableTrigger, StreamingMode],              # Materialization trigger
) -> List[MaterializedFeature]:

Метод возвращает список материализованных функций, которые содержат метаданные о том, когда обновляются значения компонентов и таблицы каталога Unity, в которых материализуются функции.

Если одновременно предоставлены OnlineStoreConfig и OfflineStoreConfig, то возвращаются два материализованных фичи для каждой предоставленной фичи, по одному для каждого типа хранилища.

Параметр trigger управляет тем, когда работает конвейер материализации:

  • CronSchedule: выполняется по фиксированному расписанию. Поддерживается функции пакетной агрегации (AggregationFunction от DeltaTableSource).
  • TableTrigger: Выполняется, когда входящая таблица Delta получает фиксацию коммита. Поддерживается для функций ColumnSelection и функций агрегирования (AggregationFunction) на базе DeltaTableSource. Для функций агрегации частота запуска конвейера ограничена: он выполняется не чаще одного раза за интервал, равный половине длины окна функции. Например, максимум раз в 30 минут в течение 1 часа, но никогда чаще раз в 5 минут.
  • StreamingMode: работает как непрерывный потоковый конвейер. Требуется для функций, поддерживаемых объектом StreamSource.

Нельзя смешивать функции, требующие разных типов триггеров в одном materialize_features вызове. Вместо этого нужно выдавать отдельные вызовы.

Материализация в автономном хранилище

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    CronSchedule, OfflineStoreConfig,
)

fe = FeatureEngineeringClient()

materialized = fe.materialize_features(
    features=features,
    offline_config=OfflineStoreConfig(
        catalog_name="main",
        schema_name="feature_store",
        table_name_prefix="customer_features"
    ),
    trigger=CronSchedule(
        quartz_cron_expression="0 0 * * * ?",  # Hourly
        timezone_id="UTC",
    ),
)

Преобразование в интернет-магазин

Note

Чтобы реализовать функции агрегирования в интернет-магазине, необходимо также реализовать их в оффлайн-магазине. Оба offline_config и online_config являются обязательными. Должен online_store_name ссылаться на существующее онлайн хранилище функций. Инструкции по созданию функции см. в разделе Databricks Online Feature Store.

ColumnSelection функции не требуют OfflineStoreConfig. См. материализацию ColumnSelection.

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    CronSchedule, OfflineStoreConfig, OnlineStoreConfig,
)

fe = FeatureEngineeringClient()

materialized = fe.materialize_features(
    features=features,
    offline_config=OfflineStoreConfig(
        catalog_name="main",
        schema_name="feature_store",
        table_name_prefix="customer_features"
    ),
    online_config=OnlineStoreConfig(
        catalog_name="main",
        schema_name="feature_store",
        table_name_prefix="customer_features_serving",
        online_store_name="customer_features_store"
    ),
    trigger=CronSchedule(
        quartz_cron_expression="0 0 * * * ?",  # Hourly
        timezone_id="UTC",
    ),
)

Материализация функций потоковой передачи

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

Функции потоковой передачи нельзя смешать с пакетными функциями в одном вызове materialize_features .

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    OnlineStoreConfig, StreamingMode,
)

fe = FeatureEngineeringClient()

materialized = fe.materialize_features(
    features=[streaming_feature],
    online_config=OnlineStoreConfig(
        catalog_name="my_catalog",
        schema_name="my_schema",
        table_name_prefix="streaming_features_serving",
        online_store_name="feature_store_online"
    ),
    trigger=StreamingMode(),
)

list_materialized_features()

Возвращает материализации одной функции, идентифицируемой по полному имени. feature_name — обязательный параметр, задаваемый только по ключевому слову. Чтобы просмотреть материализации во многих функциях, сначала перечислите функции в каталоге или схеме, а затем вызовите list_materialized_features каждую возвращаемую функцию.

По умолчанию возвращается максимум 100 материализаций. Это ограничение можно изменить с помощью max_results параметра.

FeatureEngineeringClient.list_materialized_features(
    *,                                      # Arguments are keyword-only
    feature_name: str,                      # Required: full name of the feature whose materializations to list
    max_results: int = 100,                 # Maximum number of materializations to return
) -> List[MaterializedFeature]:

delete_materialized_feature()

Перед удалением материализованной функции удалите или обновите все модели или спецификации компонентов, ссылающиеся на эту функцию.

Удаляет материализованную функцию. Передаваемая функция зависит от типа компонента:

  • Функции агрегирования: передача автономной материализованной функции. Если существует онлайн материализованная функция для одной и той же функции, обе функции удаляются.
  • ColumnSelection функции: Реализуйте материализованную функцию в сети. ColumnSelection функции материализуются только в интернет-магазине (см. материализацию ColumnSelection), поэтому парных функций для оффлайн-использования не существует.

В рамках материализации функции группируются по источнику данных и окну агрегирования для повышения эффективности. ColumnSelection функции не имеют окна агрегирования, поэтому они группируются только по источнику данных. Конвейер материализации, автономная таблица и интерактивная таблица не удаляются, пока не будут удалены все сгруппированные функции. После удаления последней материализованной функции в группе хранилище компонентов планирует связанные ресурсы для автоматической очистки фоновым процессом. См. раздел "Очистка фоновых ресурсов".

Чтобы очистить материализованные функции, просмотрите таблицу, связанную с материализованной функцией. Перед очисткой вычислительных ресурсов и разностных таблиц необходимо удалить каждую функцию в таблице (по одному на столбец).

Используется list_materialized_features() для получения аргумента materialized_feature .

FeatureEngineeringClient.delete_materialized_feature(
    materialized_feature: MaterializedFeature,  # Required: The materialized feature to delete
) -> None

from databricks.feature_engineering import FeatureEngineeringClient

fe = FeatureEngineeringClient()

feature_names = [
    "main.feature_store.amount_sum_sliding_7d_1d",
    "main.feature_store.amount_sum_sliding_30d_1d",
    "main.feature_store.transaction_count_sliding_7d_1d",
    "main.feature_store.latest_transaction_amount",
    "main.feature_store.latest_user_tier",
]

for name in feature_names:
    mfs = fe.list_materialized_features(feature_name=name)   # required, keyword-only
    offline = [mf for mf in mfs if not mf.is_online]
    for mf in (offline or mfs):
        fe.delete_materialized_feature(materialized_feature=mf)
    fe.delete_feature(full_name=name)

Материализация выбора столбца

ColumnSelection функции выбирают последнее значение одного столбца для каждого ключа сущности без агрегирования. Они могут быть материализованы только в интернет-магазинах. Для автономных вариантов использования (обучение и пакетное вывод) ColumnSelection функции извлекаются непосредственно из исходных данных во время запроса, поэтому автономная материализация не требуется.

Поведение материализации

  • Конвейер записывает последнюю строку для каждого ключа сущности в онлайн таблицу без окна агрегирования.
  • Процесс онлайн-материализации заполняет онлайн-таблицу самым последним значением для ключа сущности.

Пример

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    DeltaTableSource, Feature, ColumnSelection, TableTrigger, OnlineStoreConfig,
)

fe = FeatureEngineeringClient()

delta_source = DeltaTableSource(
    catalog_name="catalog",
    schema_name="schema",
    table_name="transactions",
)

amount_feature = Feature(
    source=delta_source,
    function=ColumnSelection("amount"),
    entity=["user_id"],
    timeseries_column="transaction_time",
    name="latest_transaction_amount",
)

# Register before materializing
amount_feature = fe.register_feature(
    feature=amount_feature,
    catalog_name="catalog",
    schema_name="schema",
)

mfs = fe.materialize_features(
    features=[amount_feature],
    online_config=OnlineStoreConfig(
        catalog_name="catalog",
        schema_name="feats_online",
        table_name_prefix="txn_",
        online_store_name="lb_usw2"
    ),
    trigger=TableTrigger(),
)

Функции ColumnSelection используют TableTrigger, который запускает обработку данных всякий раз, когда исходная таблица Delta получает новую фиксацию. В offline_config нет необходимости, так как ColumnSelection возможности считываются непосредственно из источника для автономных вариантов использования (обучение и пакетное вывод).

Note

RequestSource функции не могут быть материализованы, так как они представляют данные, предоставляемые вызывающим оператором во время вывода (или извлекаются из меточного кадра данных во время обучения). Нет исходной таблицы для чтения. Значения присутствуют только в теле запроса или в обучающем DataFrame.

Очистка фоновых ресурсов

При удалении материализованной функции Databricks немедленно удаляет метаданные компонента. Связанная с этим инфраструктура (таблицы, конвейеры и задания) очищается в асинхронном режиме фоновым процессом.

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

  • Офлайн-таблицы Delta, содержащие материализованные данные признаков
  • Онлайн-таблицы, если функции были материализованы в интернет-магазин
  • Конвейер материализации
  • Задание оркестрации

Этот фоновый процесс использует субъект-службу системы, управляемый Databricks, для выполнения этих действий очистки от вашего имени, включая удаление таблиц, конвейеров и заданий в рабочей области. От вас не требуется никаких действий. Очистка полностью управляется хранилищем компонентов.

Note

Может возникнуть небольшая задержка между удалением последней материализованной функции в группе и удалением связанных таблиц и других ресурсов.

Просмотр состояния материализации

Чтобы просмотреть статус материализации ваших представлений признаков в интерфейсе Databricks и отладить ошибки материализации, см. Изучение представлений признаков в Unity Catalog.

Ограничения

Пакетные функции

  • Конвейеры пакетной материализации выполняются в виде бессерверных конвейеров Lakeflow.
  • Функции пакетного скользящего окна не могут быть материализованы. Из-за высокой временной точности функции скользящего окна для оффлайн-обучения или пакетного вывода создаются на лету для каждой точки данных.
  • ColumnSelection функции могут быть предназначены только для интернет-магазинов.
  • RequestSource компоненты не могут быть материализованы.
  • Материализованные функции можно удалить только в рабочей области, в которой они были созданы.
  • Для материализованных признаков агрегирования невозможно удалить непосредственно онлайн-материализованный признак. Удалите парную автономную материализованную функцию, а изменение распространяется на оба.
  • Для материализованных функций агрегирования, созданных до 20 апреля 2026 г., конвейер материализации продолжает создавать новые значения признаков, пока все материализованные функции в конвейере не будут удалены, что активирует очистку ресурсов. Чтобы создать обновленный конвейер, поддерживающий удаление отдельных функций, удалите и повторно создайте функцию.
  • Для материализованных ColumnSelection функций конвейер материализации продолжает создавать новые значения признаков, пока все материализованные функции в конвейере не будут удалены, что активирует очистку ресурсов.

Функции потоковой передачи

  • Функции потоковой передачи можно материализовать только в интернет-магазинах. Офлайн-материализация не требуется, поскольку потоковые признаки во время обучения рассчитаны на то, чтобы повторно вычисляться на основе исторических событий для каждой точки данных и обеспечивать точность на уровне миллисекунд.
  • Функции потоковой передачи нельзя смешать с пакетными функциями в одном materialize_features вызове.
  • compute_features не поддерживает функции потоковой передачи.
  • Рабочая область должна находиться в регионе, где поддерживаются экземпляры Lakebase.
  • Поддерживаются только сериализованные в ФОРМАТЕ JSON сообщения Kafka. Схемы сообщений должны быть предоставлены непосредственно в формате схемы JSON. Реестры схем (Confluent, Glue) официально не поддерживаются во время предварительной версии, но если вы предоставляете схему напрямую, конвейеры могут читаться из разделов, управляемых реестром схем.
  • Поддерживается только RollingWindow для функций агрегирования потоковой передачи. TumblingWindow и SlidingWindow следует использовать с пакетными функциями.
  • Для стриминговых функций поддерживаются только Count, Avg, Sum, LastNFirstMaxStddevPopLastFirstNMinFirstDistinct, и LastDistinct функции агрегации.
  • Функции выбора столбцов из потоковых источников не обрабатывают сообщения, поступающие не по порядку. Отображается последнее событие в потоке Kafka, даже если значение столбца таймерий выше, чем ранее полученное событие.
  • Конвейеры потоковой передачи перезапускаются дважды в неделю. Каждый перезапуск может вызвать задержки обработки и время запуска до 1 минуты. Без учёта перезапусков показатель свежести на уровне p99 составляет 200 мс.
  • Резервное заполнение компонентов для материализации не поддерживается. Когда элемент материализуется, вычисления выполняются начиная с этого момента. Новые агрегации в интернет-магазине будут неточными, пока не закончится их временное окно.
  • Поддерживается только Хранилище компонентов Databricks Online .
  • Конвейеры потоковой материализации данных работают как бессерверные конвейеры Lakeflow.
  • Только рабочие области уровня предприятия.
  • Last updated on