Работа с функциями tables в Unity Catalog

Статья
12/27/2024

На этой странице описывается создание и работа с функциями tables в Unity Catalog.

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

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

Требования

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

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

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

%pip install databricks-feature-engineering

dbutils.library.restartPython()

Создайте объект catalog и объект schema для функции tables в Unity Catalog

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

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

CREATE CATALOG IF NOT EXISTS <catalog-name>

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

USE CATALOG <catalog-name>

Компонент tables в Unity Catalog должен храниться в schema. Чтобы создать новый schema в catalog, необходимо иметь права CREATE SCHEMA на catalog.

CREATE SCHEMA IF NOT EXISTS <schema-name>

Создание функции table в Unity Catalog

Примечание.

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

Однако добавление первичного ключа в потоковый table или материализованное представление, опубликованное в Unity Catalog конвейером Delta Live Live Tables, требует изменения schema потоковой table или материализованного определения представления, чтобы включить первичный ключ, а затем обновить table потоковой передачи или материализованное представление. См. статью Использование потоковой table или материализованного представления, созданного конвейером Delta Live Tables в качестве компонента table.

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

Вы можете использовать Databricks SQL, Python FeatureEngineeringClientили конвейер Delta Live Tables для создания tables в Unity Catalog.

Databricks SQL

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

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

Чтобы создать функцию временных рядов table, добавьте время column в качестве первичного ключа column и укажите ключевое слово 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)
);

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

Python

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

Напишите функции Python для вычисления признаков. Выходные данные каждой функции должны представлять собой объект DataFrame Apache Spark с уникальным первичным ключом. Первичный ключ может состоять из одного или нескольких columns.
Создайте функцию table, создав экземпляр FeatureEngineeringClient и используя create_table.
Заполните функцию 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',
#   ...
# )

Создание компонента table в Unity Catalog с помощью конвейера Delta Live Tables

Примечание.

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

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

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

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

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

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

Использование существующего Delta table в Unity Catalog как функции table

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

Примечание.

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

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

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

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

использование потокового table или материализованного представления, созданного конвейером Delta Live Tables в качестве признака table

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

Примечание.

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

Чтобы set первичные ключи для существующего table на потоковой платформе или материализованного представления, используйте updateschema потоковой платформы table или материализованного представления в блокноте, управляющем объектом. Затем refreshtableupdate объекте Unity Catalog.

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

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 Catalog в качестве функции table

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

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

Примечание.

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

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

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;

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

Update особенность table в Unity Catalog

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

Не следует обновлять следующие метаданные table.

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

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

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

Вы можете добавить новые функции в существующий компонент table одним из двух способов:

Update существующую функцию вычисления признаков и запустите write_table с возвращенной таблицей данных. Это обновляет функцию tableschema и объединяет новую функцию values на основе первичного ключа.
Создайте новую функцию вычисления признаков для вычисления новой функции values. Кадр данных, возвращаемый этой новой вычислительной функцией, должен содержать признак tables' первичный и ключи partition (если определены). Запустите write_table с фреймом данных, чтобы записать новые признаки в существующие table, используя тот же первичный ключ.

Update только определенные строки в компоненте 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'
)

Запланировать работу для update по функции table

Чтобы характеристики в feature tables всегда содержали самые последние values, Databricks рекомендует создать задание, которое регулярно запускает ноутбук для выполнения update над feature table, например, каждый день. Если у вас уже создано незапланированное задание, вы можете преобразовать его в запланированное задание, чтобы гарантировать, что функция values всегда up-to-date. См . инструкции по расписанию и оркестрации рабочих процессов.

Код функции update, table использует 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'
)

Хранение последних values ежедневных функций

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

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

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

Затем вы можете создать код для чтения из компонента table фильтрации date для интересующего вас периода времени.

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

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

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

Чтобы создать конвейер для потокового вычисления признаков, передайте потоковый объект 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'
)

Чтение данных из фичи table в Unity Catalog

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

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

Функция поиска и просмотра tables в Unity Catalog

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

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

Get метаданные компонента tables в Unity Catalog

Используйте get_table, чтобы выделить get свойства table метаданных.

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

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

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

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

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

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

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

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

Удаление функции table в Unity Catalog

Вы можете удалить функцию table в Unity Catalog, напрямую удалив Delta table в Unity Catalog с помощью Catalog Explorer или с помощью API Python для Feature Engineering.

Примечание.

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

Вы можете использовать Databricks SQL или FeatureEngineeringClient.drop_table для удаления функции table в Unity Catalog:

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

Функция table в Unity Catalog доступна всем рабочим областям, назначенным хранилищу метаданных tableUnity Catalog.

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

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

Работа с функциями tables в Unity Catalog

Требования

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

Создайте объект catalog и объект schema для функции tables в Unity Catalog

Создание функции table в Unity Catalog

Databricks SQL

Python

Создание компонента table в Unity Catalog с помощью конвейера Delta Live Tables

Databricks SQL

Python

Databricks SQL

Python

Использование существующего Delta table в Unity Catalog как функции table

использование потокового table или материализованного представления, созданного конвейером Delta Live Tables в качестве признака table

Databricks SQL

Python

Использовать существующее представление в Unity Catalog в качестве функции table

Update особенность table в Unity Catalog

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

Update только определенные строки в компоненте table

Запланировать работу для update по функции table

Хранение последних values ежедневных функций

Databricks SQL

Python

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

Чтение данных из фичи table в Unity Catalog

Функция поиска и просмотра tables в Unity Catalog

Get метаданные компонента tables в Unity Catalog

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

Удаление функции table в Unity Catalog

Databricks SQL

Python

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

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

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

Работа с функциями tables в Unity Catalog

Требования

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

Создайте объект catalog и объект schema для функции tables в Unity Catalog

Создание функции table в Unity Catalog

Databricks SQL

Python

Создание компонента table в Unity Catalog с помощью конвейера Delta Live Tables

Databricks SQL

Python

Databricks SQL

Python

Использование существующего Delta table в Unity Catalog как функции table

использование потокового table или материализованного представления, созданного конвейером Delta Live Tables в качестве признака table

Databricks SQL

Python

Использовать существующее представление в Unity Catalog в качестве функции table

Update особенность table в Unity Catalog

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

Update только определенные строки в компоненте table

Запланировать работу для update по функции table

Хранение последних values ежедневных функций

Databricks SQL

Python

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

Чтение данных из фичи table в Unity Catalog

Функция поиска и просмотра tables в Unity Catalog

Get метаданные компонента tables в Unity Catalog

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

Удаление функции table в Unity Catalog

Databricks SQL

Python

Разделите функцию table в Unity Catalog между рабочими областями или учетными записями

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

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