Работа с таблицами компонентов в каталоге Unity

Статья
03/06/2025

На этой странице описывается создание и работа с таблицами компонентов в каталоге Unity.

Эта страница относится только к рабочим областям, включённым для использования с Unity Catalog. Если рабочая область не включена для каталога Unity, см. статью Работа с таблицами компонентов в хранилище компонентов рабочей области (устаревшая версия).

Дополнительная информация о командах и параметрах, используемых в примерах на этой странице, см. справочник API Python по инженерии функций.

Требования

Для проектирования компонентов в каталоге Unity требуется среда выполнения Databricks 13.2 или более поздней версии. Кроме того, хранилище метаданных каталога Unity должно иметь модель привилегий версии 1.0.

Установка инструментов Feature Engineering в Python-клиенте Unity Catalog

Инженерия компонентов в каталоге Unity имеет клиент FeatureEngineeringClientPython. Класс доступен в PyPI с пакетом databricks-feature-engineering и предварительно установлен в Databricks Runtime 13.3 LTS ML и выше. При использовании среды выполнения Databricks, отличной от машинного обучения, необходимо вручную установить клиент. Используйте матрицу совместимости, чтобы найти правильную версию для вашей версии Databricks Runtime.

%pip install databricks-feature-engineering

dbutils.library.restartPython()

Создание каталога и схемы для таблиц компонентов в каталоге Unity

Необходимо создать новый каталог или использовать существующий каталог для таблиц компонентов.

Чтобы создать новый каталог, необходимо иметь CREATE CATALOG привилегии на метахранилище.

CREATE CATALOG IF NOT EXISTS <catalog-name>

Чтобы использовать существующий каталог, необходимо иметь USE CATALOG привилегии на каталоге.

USE CATALOG <catalog-name>

Таблицы компонентов в каталоге Unity должны храниться в схеме. Чтобы создать новую схему в каталоге, необходимо иметь CREATE SCHEMA привилегии в каталоге.

CREATE SCHEMA IF NOT EXISTS <schema-name>

Создание таблицы компонентов в каталоге Unity

Примечание.

В каталоге Unity можно использовать существующую таблицу Delta, содержащую ограничение первичного ключа в качестве таблицы компонентов. Если в таблице нет первичного ключа, необходимо обновить таблицу с помощью ALTER TABLE инструкций DDL, чтобы добавить ограничение. См Использование существующей Delta таблицы в Unity Catalog в качестве таблицы признаков.

Однако добавление первичного ключа в потоковую таблицу или материализованное представление, опубликованное в каталоге Unity конвейером DLT, требует изменения схемы потоковой таблицы или определения материализованного представления, чтобы включить первичный ключ, а затем обновить таблицу потоковой передачи или материализованное представление. См. Использование потоковой таблицы или материализованного представления, созданного конвейером DLT в качестве таблицы функций.

Таблицы признаков в каталоге Unity — это Delta tables. Таблицы характеристик должны иметь первичный ключ. К таблицам компонентов, таким как и к другим ресурсам данных в каталоге Unity, обращаются с помощью трехуровневого пространства имен: <catalog-name>.<schema-name>.<table-name>

Вы можете использовать Databricks SQL, FeatureEngineeringClientPython или конвейер DLT для создания таблиц компонентов в каталоге Unity.

Databricks SQL

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

CREATE TABLE ml.recommender_system.customer_features (
  customer_id int NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id)
);

Чтобы создать таблицу функций временных рядов, добавьте столбец времени в качестве первичного ключевого столбца и укажите ключевое слово TIMESERIES . Ключевое слово TIMESERIES требует Databricks Runtime 13.3 LTS или более поздней версии.

CREATE TABLE ml.recommender_system.customer_features (
  customer_id int NOT NULL,
  ts timestamp NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id, ts TIMESERIES)
);

После создания таблицы можно записать в нее такие данные, как другие таблицы Delta, и их можно использовать в качестве таблицы компонентов.

Python

Для получения подробной информации о командах и параметрах, используемых в следующих примерах, см. в справочнике по API Python для построения признаков.

Напишите функции Python для вычисления признаков. Выходные данные каждой функции должны представлять собой объект DataFrame Apache Spark с уникальным первичным ключом. Первичный ключ может состоять из одного или нескольких столбцов.
Создайте таблицу признаков, создав экземпляр FeatureEngineeringClient и используя create_table.
Заполните таблицу признаков с помощью write_table.

from databricks.feature_engineering import FeatureEngineeringClient

fe = FeatureEngineeringClient()

# Prepare feature DataFrame
def compute_customer_features(data):
  ''' Feature computation code returns a DataFrame with 'customer_id' as primary key'''
  pass

customer_features_df = compute_customer_features(df)

# Create feature table with `customer_id` as the primary key.
# Take schema from DataFrame output by compute_customer_features
customer_feature_table = fe.create_table(
  name='ml.recommender_system.customer_features',
  primary_keys='customer_id',
  schema=customer_features_df.schema,
  description='Customer features'
)

# An alternative is to use `create_table` and specify the `df` argument.
# This code automatically saves the features to the underlying Delta table.

# customer_feature_table = fe.create_table(
#  ...
#  df=customer_features_df,
#  ...
# )

# To use a composite primary key, pass all primary key columns in the create_table call

# customer_feature_table = fe.create_table(
#   ...
#   primary_keys=['customer_id', 'date'],
#   ...
# )

# To create a time series table, set the timeseries_columns argument

# customer_feature_table = fe.create_table(
#   ...
#   primary_keys=['customer_id', 'date'],
#   timeseries_columns='date',
#   ...
# )

Создание таблицы компонентов в каталоге Unity с помощью конвейера DLT

Примечание.

Поддержка DLT для ограничений таблиц в общедоступной предварительной версии . Следующие примеры кода должны выполняться с помощью канала предварительной версии DLT .

Любая таблица, опубликованная из конвейера DLT, которая включает ограничение первичного ключа, можно использовать в качестве таблицы компонентов. Чтобы создать таблицу в конвейере DLT с первичным ключом, можно использовать Databricks SQL или интерфейс программирования Python DLT.

Чтобы создать таблицу в конвейере DLT с первичным ключом, используйте следующий синтаксис:

Databricks SQL

CREATE LIVE TABLE customer_features (
  customer_id int NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id)
) AS SELECT * FROM ...;

Python

import dlt

@dlt.table(
  schema="""
          customer_id int NOT NULL,
          feat1 long,
          feat2 varchar(100),
          CONSTRAINT customer_features_pk PRIMARY KEY (customer_id)
    """)
def customer_features():
  return ...

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

Databricks SQL

CREATE LIVE TABLE customer_features (
  customer_id int NOT NULL,
  ts timestamp NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id, ts TIMESERIES)
) AS SELECT * FROM ...;

Python

import dlt

@dlt.table(
  schema="""
    customer_id int NOT NULL,
    ts timestamp NOT NULL,
    feat1 long,
    feat2 varchar(100),
    CONSTRAINT customer_features_pk PRIMARY KEY (customer_id, ts TIMESERIES)
    """)
def customer_features():
  return ...

После создания таблицы можно записать в нее такие данные, как другие наборы данных DLT, и его можно использовать в качестве таблицы компонентов.

Использование существующей таблицы Delta в каталоге Unity в качестве таблицы компонентов

Любая таблица Delta в каталоге Unity с первичным ключом может быть таблицей функций в каталоге Unity, и вы можете использовать пользовательский интерфейс компонентов и API с таблицей.

Примечание.

Только владелец таблицы может объявлять ограничения первичного ключа. Имя владельца отображается на странице сведений о таблице обозревателя каталогов.
Убедитесь, что тип данных в таблице Delta поддерживается конструктором компонентов в каталоге Unity. См. статью о поддерживаемых типах данных.
Ключевое слово TIMESERIES требует Databricks Runtime 13.3 LTS или более поздней версии.

Если существующая таблица Delta не имеет ограничения первичного ключа, ее можно создать следующим образом:

Установите столбцы первичного ключа на NOT NULL. Для каждого столбца первичного ключа выполните следующую команду:
```
ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL
```
Измените таблицу, чтобы добавить ограничение первичного ключа:
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1, pk_col2, ...)
```
pk_name — имя ограничения первичного ключа. По соглашению можно использовать имя таблицы (без схемы и каталога) с суффиксом _pk . Например, таблица с именем "ml.recommender_system.customer_features" будет иметь customer_features_pk имя ограничения первичного ключа.

Чтобы сделать таблицу таблицей функций временных рядов, укажите ключевое слово TIMESERIES в одном из столбцов первичного ключа следующим образом:
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1 TIMESERIES, pk_col2, ...)
```
После добавления ограничения первичного ключа в таблицу таблица появится в пользовательском интерфейсе компонентов и ее можно использовать в качестве таблицы компонентов.

Использовать потоковую таблицу или материализованное представление, созданное конвейером DLT в качестве таблицы функций

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

Примечание.

Поддержка DLT для ограничений таблиц доступна в общедоступной предварительной версии. Следующие примеры кода должны выполняться с помощью канала предварительной версии DLT .
Только владелец таблицы может объявлять ограничения первичного ключа. Имя владельца отображается на странице сведений о таблице обозревателя каталогов.
Убедитесь, что конструктор функций в каталоге Unity поддерживает тип данных в таблице Delta. См. статью о поддерживаемых типах данных.

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

Ниже приведен синтаксис для добавления первичного ключа в материализованное представление:

Databricks SQL

CREATE OR REFRESH MATERIALIZED VIEW existing_live_table(
  id int NOT NULL PRIMARY KEY,
  ...
) AS SELECT ...

Python

import dlt

@dlt.table(
  schema="""
    id int NOT NULL PRIMARY KEY,
    ...
    """
)
def existing_live_table():
  return ...

Использование существующего представления в каталоге Unity в качестве таблицы компонентов

Чтобы использовать представление в качестве таблицы функций, необходимо использовать databricks-feature-engineering версии 0.7.0 или более поздней, которая встроена в Databricks Runtime 16.0 ML.

Простое представление SELECT в каталоге Unity может быть таблицей функций в каталоге Unity, и вы можете использовать API функций с таблицей.

Примечание.

Простое SELECT представление определяется как представление, созданное из одной таблицы Delta в каталоге Unity, которая может использоваться в качестве таблицы функций, и чьи первичные ключи выбираются без JOIN, GROUP BYили предложений DISTINCT. Допустимые ключевые слова в инструкции SQL: SELECT, FROM, WHERE, ORDER BY, LIMITи OFFSET.
См. Поддерживаемые типы данных для получения информации о поддерживаемых типах данных.
Таблицы функций, основанные на представлениях, не отображаются в пользовательском интерфейсе функций.
Если столбцы переименованы в исходной таблице Delta, столбцы в инструкции SELECT для определения представления должны быть переименованы, чтобы соответствовать.

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

CREATE OR REPLACE VIEW ml.recommender_system.content_recommendation_subset AS
SELECT
    user_id,
    content_id,
    user_age,
    user_gender,
    content_genre,
    content_release_year,
    user_content_watch_duration,
    user_content_like_dislike_ratio
FROM
    ml.recommender_system.content_recommendations_features
WHERE
    user_age BETWEEN 18 AND 35
    AND content_genre IN ('Drama', 'Comedy', 'Action')
    AND content_release_year >= 2010
    AND user_content_watch_duration > 60;

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

Обновление таблицы компонентов в каталоге Unity

Вы можете обновить таблицу компонентов в каталоге Unity, добавив новые функции или изменив определенные строки на основе первичного ключа.

Не следует обновлять следующие метаданные таблицы компонентов:

Первичный ключ.
Ключ разбиения.
Имя или тип данных существующей функции.

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

Добавление новых функций в существующую таблицу функций в каталоге Unity

Добавить новые признаки в существующую таблицу признаков можно одним из двух способов.

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

Обновление только отдельных строк в таблице признаков

Используйте mode = "merge" в write_table. Строки, первичный ключ которых не существует в объекте DataFrame, переданном в вызове write_table, не изменяются.

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
fe.write_table(
  name='ml.recommender_system.customer_features',
  df = customer_features_df,
  mode = 'merge'
)

Запланировать задание для обновления таблицы атрибутов

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

В коде для обновления таблицы признаков используется mode='merge', как показано в следующем примере.

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()

customer_features_df = compute_customer_features(data)

fe.write_table(
  df=customer_features_df,
  name='ml.recommender_system.customer_features',
  mode='merge'
)

Сохранение прошлых значений ежедневных функций

Определите таблицу признаков с составным первичным ключом. Включите в первичный ключ дату. Например, для таблицы признаков customer_features можно использовать составной первичный ключ (date, customer_id) и ключ секции date для эффективного чтения.

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

Databricks SQL

CREATE TABLE ml.recommender_system.customer_features (
  customer_id int NOT NULL,
  `date` date NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (`date`, customer_id)
)
-- If you are not using liquid clustering, uncomment the following line.
-- PARTITIONED BY (`date`)
COMMENT "Customer features";

Python

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
fe.create_table(
  name='ml.recommender_system.customer_features',
  primary_keys=['date', 'customer_id'],
  # If you are not using liquid clustering, uncomment the following line.
  # partition_columns=['date'],
  schema=customer_features_df.schema,
  description='Customer features'
)

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

Вы также можете создать таблицу функций временных рядов, которая обеспечивает поиск на определенный момент времени при использовании create_training_set илиscore_batch. См. статью "Создание таблицы компонентов" в каталоге Unity.

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

Создание платформы для потокового вычисления признаков и актуализации данных

Чтобы создать конвейер для обработки потоковых данных, передайте поток DataFrame в качестве аргумента в write_table. Этот метод возвращает объект StreamingQuery.

def compute_additional_customer_features(data):
  ''' Returns Streaming DataFrame
  '''
  pass

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()

customer_transactions = spark.readStream.table("prod.events.customer_transactions")
stream_df = compute_additional_customer_features(customer_transactions)

fe.write_table(
  df=stream_df,
  name='ml.recommender_system.customer_features',
  mode='merge'
)

Чтение из таблицы компонентов в каталоге Unity

Для считывания значений признаков используйте метод read_table.

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
customer_features_df = fe.read_table(
  name='ml.recommender_system.customer_features',
)

Поиск и просмотр таблиц компонентов в каталоге Unity

Используйте пользовательский интерфейс компонентов для поиска или просмотра таблиц компонентов в каталоге Unity.

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

Получение метаданных таблиц компонентов в каталоге Unity

Используйте get_table для получения метаданных таблицы признаков.

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
ft = fe.get_table(name="ml.recommender_system.user_feature_table")
print(ft.features)

Использование тегов с таблицами компонентов и функциями в каталоге Unity

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

Для таблиц функций можно создавать, изменять и удалять теги с помощью Каталог Эксплорер, с использованием SQL-инструкций в записной книжке или в редакторе SQL-запросов, или API Python для инженерии признаков.

Для возможностей вы можете создавать, изменять и удалять теги с помощью проводника каталога или инструкций SQL в редакторе запросов записной книжки или SQL-редакторе запросов.

См. "Применение тегов к защищаемым объектам каталога Unity" и Python API для проектирования функций и функции хранения рабочих областей.

В следующем примере показано, как использовать API Python для разработки функций для создания, обновления и удаления тегов таблиц компонентов.

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()

# Create feature table with tags
customer_feature_table = fe.create_table(
  # ...
  tags={"tag_key_1": "tag_value_1", "tag_key_2": "tag_value_2", ...},
  # ...
)

# Upsert a tag
fe.set_feature_table_tag(name="customer_feature_table", key="tag_key_1", value="new_key_value")

# Delete a tag
fe.delete_feature_table_tag(name="customer_feature_table", key="tag_key_2")

Удаление таблицы компонентов в каталоге Unity

Вы можете удалить таблицу компонентов в каталоге Unity, напрямую удалив таблицу Delta в каталоге Unity с помощью обозревателя каталогов или с помощью API Python для проектирования компонентов.

Примечание.

Удаление таблицы признаков может привести к непредвиденным сбоям в вышестоящих производителях и нижестоящих потребителях (модели, конечные точки и запланированные задания). Вам нужно удалить опубликованные интернет-магазины у вашего поставщика облачных услуг.
При удалении таблицы компонентов в каталоге Unity базовая таблица Delta также удаляется.
drop_table не поддерживается в Databricks Runtime 13.1 ML или ниже. Используйте команду SQL для удаления таблицы.

Вы можете использовать Databricks SQL или FeatureEngineeringClient.drop_table, чтобы удалить таблицу признаков в каталоге Unity.

Databricks SQL

DROP TABLE ml.recommender_system.customer_features;

Python

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
fe.drop_table(
  name='ml.recommender_system.customer_features'
)

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

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

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

Работа с таблицами компонентов в каталоге Unity

Требования

Установка инструментов Feature Engineering в Python-клиенте Unity Catalog

Создание каталога и схемы для таблиц компонентов в каталоге Unity

Создание таблицы компонентов в каталоге Unity

Databricks SQL

Python

Создание таблицы компонентов в каталоге Unity с помощью конвейера DLT

Databricks SQL

Python

Databricks SQL

Python

Использование существующей таблицы Delta в каталоге Unity в качестве таблицы компонентов

Использовать потоковую таблицу или материализованное представление, созданное конвейером DLT в качестве таблицы функций

Databricks SQL

Python

Использование существующего представления в каталоге Unity в качестве таблицы компонентов

Обновление таблицы компонентов в каталоге Unity

Добавление новых функций в существующую таблицу функций в каталоге Unity

Обновление только отдельных строк в таблице признаков

Запланировать задание для обновления таблицы атрибутов

Сохранение прошлых значений ежедневных функций

Databricks SQL

Python

Создание платформы для потокового вычисления признаков и актуализации данных

Чтение из таблицы компонентов в каталоге Unity

Поиск и просмотр таблиц компонентов в каталоге Unity

Получение метаданных таблиц компонентов в каталоге Unity

Использование тегов с таблицами компонентов и функциями в каталоге Unity

Удаление таблицы компонентов в каталоге Unity

Databricks SQL

Python

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

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

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

Работа с таблицами компонентов в каталоге Unity

Требования

Установка инструментов Feature Engineering в Python-клиенте Unity Catalog

Создание каталога и схемы для таблиц компонентов в каталоге Unity

Создание таблицы компонентов в каталоге Unity

Databricks SQL

Python

Создание таблицы компонентов в каталоге Unity с помощью конвейера DLT

Databricks SQL

Python

Databricks SQL

Python

Использование существующей таблицы Delta в каталоге Unity в качестве таблицы компонентов

Использовать потоковую таблицу или материализованное представление, созданное конвейером DLT в качестве таблицы функций

Databricks SQL

Python

Использование существующего представления в каталоге Unity в качестве таблицы компонентов

Обновление таблицы компонентов в каталоге Unity

Добавление новых функций в существующую таблицу функций в каталоге Unity

Обновление только отдельных строк в таблице признаков

Запланировать задание для обновления таблицы атрибутов

Сохранение прошлых значений ежедневных функций

Databricks SQL

Python

Создание платформы для потокового вычисления признаков и актуализации данных

Чтение из таблицы компонентов в каталоге Unity

Поиск и просмотр таблиц компонентов в каталоге Unity

Получение метаданных таблиц компонентов в каталоге Unity

Использование тегов с таблицами компонентов и функциями в каталоге Unity

Удаление таблицы компонентов в каталоге Unity

Databricks SQL

Python

Предоставление общего доступа к таблице компонентов в каталоге Unity в рабочих областях или учетных записях

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

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