CREATE EXTERNAL LIBRARY (Transact-SQL)

Применимо к: SQL Server 2017 (14.x) и более поздних версий Управляемого экземпляра SQL Azure

Отправляет файлы пакетов R, Python или Java в базу данных из указанного байтового потока или пути к файлу. Эта инструкция служит универсальным механизмом для администратора базы данных для отправки артефактов, необходимых для всех новых внешних языковых сред и платформ ОС, поддерживаемых SQL Server.

Примечание.

В SQL Server 2017 (14.x) поддерживается язык R и платформа Windows. R, Python и внешние языки на платформах Windows и Linux поддерживаются в SQL Server 2019 (15.x) и более поздних версиях.

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

Синтаксис для SQL Server 2019

CREATE EXTERNAL LIBRARY library_name
[ AUTHORIZATION owner_name ]
FROM <file_spec> [ ,...2 ]
WITH ( LANGUAGE = <language> )
[ ; ]

<file_spec> ::=
{
    (CONTENT = { <client_library_specifier> | <library_bits> }
    [, PLATFORM = <platform> ])
}

<client_library_specifier> :: =
{
    '[file_path\]manifest_file_name'
}

<library_bits> :: =
{
      varbinary_literal
    | varbinary_expression
}

<platform> :: =
{
      WINDOWS
    | LINUX
}

<language> :: =
{
      'R'
    | 'Python'
    | <external_language>
}

Синтаксис для SQL Server 2017

CREATE EXTERNAL LIBRARY library_name
[ AUTHORIZATION owner_name ]
FROM <file_spec> [ ,...2 ]
WITH ( LANGUAGE = 'R' )
[ ; ]

<file_spec> ::=
{
    (CONTENT = { <client_library_specifier> | <library_bits> })
}

<client_library_specifier> :: =
{
    '[file_path\]manifest_file_name'
}

<library_bits> :: =
{
      varbinary_literal
    | varbinary_expression
}

Синтаксис для Управляемого экземпляра SQL Azure

CREATE EXTERNAL LIBRARY library_name
[ AUTHORIZATION owner_name ]
FROM <file_spec> [ ,...2 ]
WITH ( LANGUAGE = <language> )
[ ; ]

<file_spec> ::=
{
    (CONTENT = <library_bits>)
}

<library_bits> :: =
{
      varbinary_literal
    | varbinary_expression
}

<language> :: =
{
      'R'
    | 'Python'
}

Аргументы

LIBRARY_NAME

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

Имена библиотек должны быть уникальными в контексте определенного пользователя или владельца. Например, два пользователя RUser1 и RUser2 могут одновременно и отдельно отправлять ggplot2 библиотеки R. Однако если RUser1 требуется отправить более новую версию ggplot2, второй экземпляр должен называться по-другому или заменить существующую библиотеку.

Имена библиотек не могут быть произвольно назначены; Имя библиотеки должно совпадать с именем, необходимым для загрузки библиотеки во внешний скрипт.

OWNER_NAME

Указывает имя пользователя или роли, которой принадлежит внешняя библиотека. Если атрибут не указан, владельцем становится текущий пользователь.

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

Когда пользователь RUser1 выполняет внешний скрипт, значение libPath может содержать несколько путей. Первый путь всегда является путем к общей библиотеке, созданной владельцем базы данных. Вторая часть libPath определяет путь, содержащий пакеты, отправленные по отдельности RUser1.

FILE_SPEC

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

Файл можно указать в виде локального или сетевого пути.

При попытке доступа к файлу, указанному в <client_library_specifier>, SQL Server олицетворяет контекст безопасности текущего имени входа Windows. Если <client_library_specifier> указывает сетевое расположение (UNC-путь), олицетворение текущего имени входа не переносится в сетевое расположение из-за ограничений делегирования. В этом случае доступ осуществляется при помощи контекста безопасности учетной записи службы SQL Server. Дополнительные сведения см. в статье Учетные данные (компонент Database Engine).

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

LIBRARY_BITS

Задает содержимое пакета как шестнадцатеричный литерал, аналогично сборкам.

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

ПЛАТФОРМЫ

Указывает платформу для содержимого библиотеки. Является значением по умолчанию для платформы узла, на которой выполняется SQL Server. Поэтому пользователю не нужно указывать это значение. Это необходимо в случае, если поддерживаются несколько платформ или пользователь должен указать другую платформу. В SQL Server 2019 (15.x) Windows и Linux являются поддерживаемыми платформами.

LANGUAGE = "R"

Задает язык пакета. R поддерживается в SQL Server 2017 (14.x).

LANGUAGE

Задает язык пакета. Значение может быть R или Python в Управляемом экземпляре SQL Azure.

LANGUAGE

Задает язык пакета. Значением может быть R, Python или название внешнего языка (см. раздел CREATE EXTERNAL LANGUAGE).

Замечания

Для языка R при использовании файла пакеты должны быть подготовлены в виде архивных файлов с расширением .zip для Windows. В SQL Server 2017 (14.x) поддерживается только платформа Windows.

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

Для языка Python пакет в .whl файле или .zip файле должен быть подготовлен в виде архивного файла. Если пакет уже является файлом .zip , он должен быть включен в новый .zip файл. Отправка пакета как .whl или .zip файла напрямую не поддерживается.

Инструкция CREATE EXTERNAL LIBRARY загружает биты библиотеки в базу данных. Библиотека устанавливается, когда пользователь запускает внешний скрипт с помощью sp_execute_external_script и вызывает пакет или библиотеку.

Несколько пакетов, называемых системными пакетами, предварительно установлены в экземпляре SQL. Нельзя добавлять, обновлять или удалять системные пакеты.

Разрешения

Требуется разрешение CREATE EXTERNAL LIBRARY. По умолчанию любой пользователь с учетной записью dbo, являющийся членом роли db_owner, имеет разрешения на создание внешней библиотеки. Для всех остальных пользователей необходимо явно предоставить им разрешение с помощью инструкции GRANT , указывая CREATE EXTERNAL LIBRARY в качестве привилегии.

В SQL Server 2019 (15.x), помимо CREATE EXTERNAL LIBRARY разрешения, пользователь также должен ссылаться на внешний язык, чтобы создать внешние библиотеки для этого внешнего языка.

GRANT REFERENCES ON EXTERNAL LANGUAGE::Java to user
GRANT CREATE EXTERNAL LIBRARY to user

Для изменения любой библиотеки требуется отдельное разрешение ALTER ANY EXTERNAL LIBRARY.

Чтобы создать внешнюю библиотеку с помощью пути к файлу, пользователь должен быть именем входа, прошедшим проверку подлинности Windows, или членом предопределенных ролей сервера sysadmin .

Примеры

Добавление внешней библиотеки в базу данных

В следующем примере внешняя библиотека customPackage добавляется в базу данных.

CREATE EXTERNAL LIBRARY customPackage
    FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\customPackage.zip')
    WITH (LANGUAGE = 'R');

После успешной отправки библиотеки в экземпляр пользователь выполняет sp_execute_external_script процедуру, чтобы установить библиотеку.

EXECUTE sp_execute_external_script
    @language = N'R',
    @script = N'library(customPackage)';

Для языка Python в SQL Server 2019 (15.x) пример также работает путем замены 'R''Python'на .

Установка пакетов с зависимостями

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

Предположим, вы хотите установить новый пакет packageA:

packageA имеет зависимость от packageB
packageB имеет зависимость от packageC

Для успешной установки packageA необходимо создать библиотеки для packageB и packageC одновременно с добавлением packageA в SQL Server. Не забудьте проверить версии необходимых пакетов.

На практике зависимости пакетов для популярных пакетов сложнее, чем в этом примере. Например, ggplot2 может потребовать более 30 пакетов, и для этих пакетов могут потребоваться дополнительные пакеты, недоступные на сервере. Отсутствие пакета или наличие пакета неправильной версии могут привести к сбою установки.

Так как определить все зависимости можно только от просмотра манифеста пакета, используйте пакет, например miniCRAN , чтобы определить все пакеты, необходимые для успешной установки.

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

CREATE EXTERNAL LIBRARY packageA
FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\packageA.zip')
WITH (LANGUAGE = 'R');
GO

CREATE EXTERNAL LIBRARY packageB FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\packageB.zip')
WITH (LANGUAGE = 'R');
GO

CREATE EXTERNAL LIBRARY packageC FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\packageC.zip')
WITH (LANGUAGE = 'R');
GO

Сначала установите необходимые пакеты.

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

Необходимые пакеты packageC и packageB установлены в правильном порядке, когда sp_execute_external_script впервые запускается для установки пакета packageA.

Однако если какой-либо обязательный пакет недоступен, установка целевого пакета packageA завершается ошибкой.
```
EXECUTE sp_execute_external_script
    @language = N'R',
    @script = N'
    # load the desired package packageA
    library(packageA)
    ';
```

Для языка Python в SQL Server 2019 (15.x) пример также работает путем замены 'R''Python'на .

Создание библиотеки из потока байтов

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

CREATE EXTERNAL LIBRARY customLibrary FROM (CONTENT = 0xABC123...) WITH (LANGUAGE = 'R');

Для языка Python в SQL Server 2019 (15.x) пример также работает путем замены RPythonна .

Примечание.

Этот пример кода демонстрирует только синтаксис; двоичное значение CONTENT = усечено для удобства чтения и не создает рабочую библиотеку. Фактическое содержимое двоичной переменной длиннее.

Изменение существующей библиотеки пакета

Можно использовать инструкцию DDL ALTER EXTERNAL LIBRARY для добавления нового содержимого библиотеки или изменения существующего содержимого библиотеки. Для изменения существующей библиотеки требуется разрешение ALTER ANY EXTERNAL LIBRARY.

Дополнительные сведения см. в разделе ALTER EXTERNAL LIBRARY.

Добавьте JAR-файл Java к базе данных

В следующем примере в базу данных добавляется customJar внешний .jar файл.

CREATE EXTERNAL LIBRARY customJar
    FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\customJar.jar')
    WITH (LANGUAGE = 'Java');

EXECUTE sp_execute_external_script
    @language = N'Java',
    @script = N'customJar.MyCLass.myMethod',
    @input_data_1 = N'SELECT * FROM dbo.MyTable'
    WITH RESULT SETS
(
        (column1 INT)
);

Добавление внешнего пакета одновременно для Windows и Linux

Вы можете указать два параметра <file_spec>: один для Windows, а другой для Linux.

CREATE EXTERNAL LIBRARY lazyeval
    FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\packageA.zip', PLATFORM = WINDOWS),(CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\packageA.tar.gz', PLATFORM = LINUX)
    WITH (LANGUAGE = 'R');

sp_execute_external_script При установке пакета в зависимости от платформы, на которую выполняется экземпляр SQL Server, используется содержимое библиотеки для этой платформы.

EXECUTE sp_execute_external_script
    @LANGUAGE = N'R',
    @SCRIPT = N'
library(packageA)';

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

Были ли сведения на этой странице полезными?

Last updated on 2026-01-28

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

CREATE EXTERNAL LIBRARY (Transact-SQL)

Синтаксис для SQL Server 2019

Синтаксис для SQL Server 2017

Синтаксис для Управляемого экземпляра SQL Azure

Аргументы

LIBRARY_NAME

OWNER_NAME

FILE_SPEC

LIBRARY_BITS

ПЛАТФОРМЫ

LANGUAGE = "R"

LANGUAGE

LANGUAGE

Замечания

Разрешения

Примеры

Добавление внешней библиотеки в базу данных

Установка пакетов с зависимостями

Создание библиотеки из потока байтов

Изменение существующей библиотеки пакета

Добавьте JAR-файл Java к базе данных

Добавление внешнего пакета одновременно для Windows и Linux

Связанный контент

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

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