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

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

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

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

Требования

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

Установка инженерии компонентов в клиенте Python каталога Unity

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

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

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

Для создания таблиц компонентов в каталоге Unity можно использовать databricks SQL, Python FeatureEngineeringClientили конвейер Delta Live Tables.

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 для конструктора компонентов.

1. Напишите функции Python для вычисления признаков. Выходные данные каждой функции должны представлять собой объект DataFrame Apache Spark с уникальным первичным ключом. Первичный ключ может состоять из одного или нескольких столбцов.
2. Создайте таблицу признаков путем создания экземпляра FeatureEngineeringClient и использования create_table.
3. Заполните таблицу признаков с помощью 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 с помощью конвейера Delta Live Table

Примечание.

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

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

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

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 ...

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

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

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

Примечание.

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

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

1. Задайте для столбцов NOT NULLпервичного ключа значение . Для каждого столбца первичного ключа выполните следующую команду:

   ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL
   

2. Измените таблицу, чтобы добавить ограничение первичного ключа:

   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, ...)
   

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

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

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

Примечание.

• Поддержка Delta Live Tables для ограничений таблиц находится в общедоступной предварительной версии. Следующие примеры кода должны выполняться с помощью канала предварительной версии Delta Live Tables.
• Только владелец таблицы может объявлять ограничения первичного ключа. Имя владельца отображается на странице сведений о таблице обозревателя каталогов.
• Убедитесь, что конструктор функций в каталоге 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 с кадром данных, чтобы записать новые функции в существующую таблицу функций с помощью того же первичного ключа.

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

Используйте 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.

1. Щелкните "Компоненты " на боковой панели, чтобы отобразить пользовательский интерфейс компонентов.

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

   

Получение метаданных таблиц компонентов в каталоге 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" и API Api Python "Проектирование компонентов и рабочих областей".

В следующем примере показано, как использовать 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 таблицы.

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