Тип FILE и неструктурированные данные

Important

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

Тип FILE хранит регулируемую ссылку на неструктурированный файл с метаданными, такими как путь и размер. Используйте FILE столбцы в Unity Catalog для хранения документов, изображений и аудио вместе со структурированными данными.

С FILE MANAGED столбцами Unity Catalog хранит копии файлов и управляет ими с помощью таблицы: удаление строк делает ссылающиеся файлы подходящими для сборки мусора, чтобы таблица и её файлы оставались синхронизированы.

Для справочника типа см.FILE тип.

Следующая диаграмма показывает FILE столбец с названием video , который ссылается на клипы вождения рядом со структурированными столбцами, такими как маршрут, описание сцены и метка опасности:

Метаданные и хранение FILE

Для каждой строки FILE тип хранит метаданные и регулируемую ссылку на файл в хранилище. Значение FILE включает uriполя , size, content_type, и checksum метаданные. Запросы к метаданным не требуют полного чтения файлов, что повышает производительность запросов.

Вы можете передавать FILE значения функциям ИИ, таким как ai_parse_document функциям, и пользовательским функциям (UDF).

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

Почему использовать FILE вместо BINARY или STRING?

В следующей таблице описаны трудности при работе с большими неструктурированными файлами с BINARY типами или STRING типами:

Тип столбца	Description	Diagram
BINARY	Материализует полный объект для каждого чтения, даже если нужны только метаданные, такие как размер файла или путь. Это приводит к ненужным вычислениям и медленным запросам.
STRING	Сохраняет путь файла без метаданных, таких как размер или информация о версии, и без регулируемой связи между таблицей и файлом. Если другая нагрузка удаляет файл, таблица сохраняет устаревшую информацию. Если удалить строку таблицы, ссылка на которую ссылается на файл до ручного удаления.

Контрольные суммы

Поле checksum является токеном целостности для байтов файла вида <prefix>:<digest>. Используйте его для сравнения файлов или проверки, что файл не изменился. Читатели игнорируют контрольную сумму с нераспознанным префиксом.

Контрольная сумма не всегда доступна. to_file функция, create_file функция и copy_file функция заполняют контрольную сумму, когда хранилище объектов возвращает ETAG. list_files Функция с таблицным значением и read_files функция с таблицьным значением не заполняют контрольную сумму.

Поле использует один из следующих префиксов:checksum

Префикс	Кодирование дайджеста	Description
ETAG	Opaque	eTag объектного хранилища для всего файла. Предоставляется дословно магазином, используется только для сравнения равенств и не поддается повторному вычислению.
MD5	Строчные шестигранники	MD5 дайджест (RFC 1321), 32 шестигранных символа.
CRC32	Строчные шестигранники	Контрольная сумма CRC32 (RFC 2083), 8 шестнадцатеричных символов.
CRC32C	Строчные шестигранники	Контрольная сумма CRC32C (RFC 3385), 8 шестнадцатеричных символов.
SHA-256	Строчные шестигранники	Дайджест SHA-256 (RFC 6234), 64 шестигранных символа.

Например, контрольная сумма MD5 выглядит как MD5:d41d8cd98f00b204e9800998ecf8427e, а eTag объектного хранилища — как ETAG:"686897696a7c876b7e", включая окружающие двойные кавычки, возвращаемые хранилищем объектов.

Выбирайте между FILE и BINARY

В следующей таблице сравниваются варианты работы с неструктурированными файлами:

Тип столбца	Ценности	Сценарий использования
FILE	Регулируемая ссылка на файл плюс метаданные (uri, size, content_type, checksum).	Используется для управления и обработки неструктурированных файлов вместе со структурированными данными, а также передачи файлов встроенным и AI-функциям.
BINARY	Необработанные байты файла, встроенные в колонку.	Используйте для небольших объектов (до 64 КБ по умолчанию), хранящихся непосредственно в файле данных. Это полезно, когда нужны низкие накладные расходы на метаданные и упрощённое управление файлами. Например, используйте это для хранения миниатюр в строке с данными строк.

УПРАВЛЯЕМЫЙ ФАЙЛ И ВНЕШНИЙ ФАЙЛ

Тип FILE поддерживает два подхода к управлению файлами:

• FILE MANAGED Column Copy файлы в управляемое хранилище. Права разрешений упрощаются и управляются через таблицу. Когда вы удаляете строки или обновляете их для ссылок на разные файлы, нессылки на файлы становятся подходящими для сборки мусора, поэтому таблица и её файлы остаются синхронизированы. Используйте этот подход для рабочих нагрузок, которые получают доступ к файлам через таблицу, например, обучение машинного обучения или генерация с дополненным поиском (RAG), а также для файлов, получаемых из внешних источников. Для паттернов погружения см. Файлы ввода как тип FILE.
• FILE EXTERNAL столбцы ссылаются на существующие файлы в томе Unity Catalog. Файлы защищены разрешениями тома Unity Catalog, но их жизненный цикл не управляется Unity Catalog и не копируется. Используйте этот подход, когда нужно делать ссылки на файлы, не перемещая данные и не мешая инструментам, читающим данные с существующего тома.

Azure Databricks рекомендует FILE MANAGED создавать рабочие нагрузки, которые получают доступ к разрешениям на уровне файлов и встроенную соответствие: доступ к каждому файлу регулируется через таблицу, на которую он ссылается, а удаление строк делает ссылки на файлы подходящими для сбора мусора. Используйте FILE EXTERNAL то, когда файлы должны оставаться на существующих путях тома, для инструментов, которые читают их вне таблицы.

Для запросов нет разницы между управляемыми и внешними файлами.

Следующая схема показывает, как FILE тип связывает ваш код с файлами в облачном объектном хранилище:

FILE MANAGED

FILE MANAGED Столбцы хранят копии файлов в FileSpaceтоме Unity Catalog, который вы объявляете для использования таблицы как управляемого хранилища. Их жизненный цикл связан с таблицами, на которые они ссылаются: удаление строк делает ссылки на файлы подходящими для сборки мусора, поэтому таблица и её файлы остаются синхронизированы.

Следующие поведения применимы к FILE MANAGED:

• Для объявления требуется FileSpace свойство databricks.filespace-preview таблицы.
• Чтение или запись управляемого файла требует доступа как к таблице, так и к тому, поддерживающему файл FileSpace.
• Автоматический сбор мусора из несвязанных файлов не поддерживается в бета-версии.

Неструктурированные файлы, хранящиеся во внешних источниках, таких как SharePoint, Google Drive, OneDrive и SFTP, должны быть введены в управляемые файлы, прежде чем вы сможете использовать их с функциями, такими как ai_parse_document функциональные и пользовательские функции (UDF). Для паттернов погружения см. Файлы ввода как тип FILE.

Чтобы использовать управляемые файлы, создайте таблицу с FILE MANAGED столбцом и объявите том как , FileSpace установив свойство databricks.filespace-preview таблицы на путь к тому:

'databricks.filespace-preview' = '/Volumes/<catalog>/<schema>/<volume_name>/<optional_path>'

Для полных примеров см. следующие FILE MANAGED примеры.

примеры FILE MANAGED

Чтобы создать таблицу со FILE MANAGED столбцом:

CREATE TABLE reports (id BIGINT, file FILE MANAGED)
  TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

Чтобы добавить FILE MANAGED столбец к существующей таблице, задайте свойство databricks.filespace-preview таблицы перед добавлением столбца, как в следующем коде:

ALTER TABLE reports SET TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

ALTER TABLE reports ADD COLUMN attachment FILE MANAGED;

Добавление FILE MANAGED столбца в таблицу без FileSpace ошибок — это ошибки.

Удалить управляемые файлы без ссылки

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

Блокнот для сборки мусора FileType

Получите ноутбук

FILE EXTERNAL

FILE EXTERNAL столбцы — это ссылки на файлы, уже существующие в томе каталога Unity.

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

Внешний файл отображает каждую строку таблицы в файл на его существующем пути в томе Unity Catalog:

примеры FILE EXTERNAL

Чтобы создать таблицу со FILE EXTERNAL столбцом:

CREATE TABLE documents (id BIGINT, file FILE EXTERNAL);

Чтобы добавить FILE EXTERNAL столбец в существующую таблицу:

ALTER TABLE documents ADD COLUMN file FILE EXTERNAL;

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

CREATE TABLE documents AS
  SELECT monotonically_increasing_id() AS id, file
  FROM list_files('/Volumes/samples/sec/contracts/');

Сравнение управления и жизненного цикла

В следующей таблице сравнивается, как FILE MANAGED и FILE EXTERNAL управляется доступ к файлам, а также обработка жизненного цикла файла:

Тип столбца	FILE MANAGED	FILE EXTERNAL
Контроль доступа к файлам	Регулируется разрешениями таблицы и тома, например SELECT , на таблице и READ VOLUME на томе.	Регулируется разрешениями объёма, такими READ VOLUMEкак .
Жизненный цикл и сборка мусора	Файлы привязаны к строкам, которые на них ссылаются. Удаление этих строк делает файлы подходящими для сборки мусора. Автоматический сбор мусора не поддерживается.	Вы сами управляете файлами. Удаление строки таблицы не влияет на базовый файл в томе.

Сценарии использования типа FILE

Как управляемые, так и внешние FILE типы решают следующие задачи при использовании неструктурированных данных:

Задача	Поддерживаемый FILE тип	Benefits
Файлы, слишком большие для хранения в строке как BINARY	FILE MANAGED или FILE EXTERNAL	Столбец FILE хранит ссылку, поэтому файл читается только тогда, когда его обрабатывает функция ИИ или UDF. Это предотвращает материализацию крупных объектов в таблице.
Разрыв жизненного цикла и управления между файловой системой и таблицей	FILE MANAGED	Azure Databricks привязывает жизненный цикл каждого файла к таблице, поэтому удаление строк делает файлы пригодными для очистки, а не оставляют сироты в хранилище.
Параллельные нагрузки, требующие сохранения файлов в одном и том же месте	FILE EXTERNAL	Файлы остаются на своих существующих путях тома, не влияя на жизненный цикл таблицы, поэтому другие инструменты, читающие те же файлы, не нарушаются.

Дальнейшие действия

• типа FILE
• Вводите файлы как тип FILE
• Учебник: Постройте конвейер обработки файлов с типом FILE
• ai_parse_document функция