CREATE EXTERNAL LIBRARY （Transact-SQL）

适用于： SQL Server 2017 （14.x） 及更高版本 Azure SQL 托管实例

从指定的字节流或文件路径上传 R、Python 或 Java 包文件至数据库。 此语句充当一种通用机制，可供数据库管理员上传任何新的外部语言运行时和 SQL Server 支持的 OS 平台所需的项目。

注意

在 SQL Server 2017（14.x）、R 语言和 Windows 平台中受支持。 SQL Server 2019 （15.x） 及更高版本支持 Windows 和 Linux 平台上的 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>
}

参数

LIBRARY_NAME

上传到实例的库可以是公共的也可以是私有的。 如果是由 dbo 成员创建的库，则该库是公共的且所有的用户都可以共享。 否则，该库就仅为用户私有。

在特定用户或所有者的上下文中，库名称必须是唯一的。 例如，两个用户 RUser1 可以 RUser2 单独和单独上传 R 库 ggplot2。 但是，如果 RUser1 想要上传较新版本的 ggplot2，则第二个实例必须以不同的方式命名，或者必须替换现有库。

无法任意分配库名称;库名称应与在外部脚本中加载库所需的名称相同。

OWNER_NAME

指定拥有外部库的用户或角色的名称。 如果未指定，则所有权授予当前用户。

对于数据库和运行时，数据库所有者所拥有的库均视为全局性的库。 换言之，数据库所有者可以创建库，而这些库包含一组由许多用户共享的公共库或包。 当由用户而不是 dbo 用户创建外部库时，该外部库便由该用户专用。

当用户 RUser1 执行外部脚本时，值 libPath 可以包含多个路径。 第一个路径始终为数据库所有者创建的共享库的路径。 第二部分 libPath 指定包含单独 RUser1上传的包的路径。

FILE_SPEC

指定特定平台的包的内容。 每个平台仅支持一个文件项目。

可以是以本地路径或网络路径的形式指定的文件。

尝试访问指定 <client_library_specifier>文件时，SQL Server 模拟当前 Windows 登录名的安全上下文。 如果 <client_library_specifier> 指定网络位置（UNC 路径），则由于委派限制，当前登录名的模拟不会转发到网络位置。 在这种情况下，将使用 SQL Server 服务帐户的安全上下文进行访问。 有关详细信息，请参阅凭据（数据库引擎）。

还可以为文件指定一个 OS 平台。 针对特定语言或运行时，每个 OS 平台只允许一个文件项目或内容。

LIBRARY_BITS

将包的内容指定为十六进制文本，类似于程序集。

如果需要创建库或更改现有库（并且具有所需的权限），则此选项非常有用，但服务器上的文件系统受到限制，并且无法将库文件复制到服务器可以访问的位置。

平台

为库的内容指定平台。 该值默认为正在运行 SQL Server 的主机平台。 因此，用户不需要指定该值。 如果支持多个平台，或者用户需要指定不同的平台，则需要它。 在 SQL Server 2019（15.x）中，Windows 和 Linux 是受支持的平台。

LANGUAGE

指定包的语言。 该值可以是 R、Python 或外部语言的名称（请参阅创建外部语言）。

备注

对于 R 语言，在使用文件时，必须以扩展名为压缩的存档文件 .zip 的形式准备包。

对于 Python 语言，必须以压缩的存档文件的形式准备包或文件中的包.whl.zip。 如果包已是文件 .zip ，则必须将其包含在新 .zip 文件中。 目前不支持将包上传为 .whl 或 .zip 直接文件。

CREATE EXTERNAL LIBRARY 语句将库位上载到数据库。 当用户使用 sp_execute_external_script 运行外部脚本并调用包或库时，会安装该库。

上传到实例的库可以是公共的也可以是私有的。 如果是由 dbo 成员创建的库，则该库是公共的且所有的用户都可以共享。 否则，该库就仅为用户私有。

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

对于 SQL Server 2019 （15.x）中的 Python 语言，该示例也可替换为 'R''Python'。

安装具有依赖项的包

如果要安装的包具有任何依赖项，则分析第一级和第二级依赖项至关重要，并确保在尝试安装目标包 之前 ，所有必需的包都可用。

例如，假设想要安装新包 packageA：

• packageA 具有 packageB 上的依赖项
• packageB 具有 packageC 上的依赖项

若要成功安装 packageA，则必须在将 packageB 添加到 SQL Server 的同时为 packageC 和 packageA 创建库。 同时请务必检查所需的包版本。

实际上，常用包的包依赖项比此示例更为复杂。 例如， 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)
      ';
  

对于 SQL Server 2019 （15.x）中的 Python 语言，该示例也可替换为 'R''Python'。

从字节流创建库

如果无法将包文件保存在服务器上的某个位置，则可以在变量中传递包内容。 下面的示例通过将位传递为十六进制文本来创建库。

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

对于 SQL Server 2019 （15.x）中的 Python 语言，该示例也可替换为 RPython。

注意

此代码示例仅演示语法;中的 CONTENT = 二进制值因可读性而截断，不会创建工作库。 二进制变量的实际内容更长。

更改现有包库

ALTER EXTERNAL LIBRARY DDL 语句可用于向新库添加内容或更改现有库的内容。 修改现有库需要 ALTER ANY EXTERNAL LIBRARY 权限。

有关详细信息，请参阅 ALTER EXTERNAL LIBRARY。

向数据库添加 Java .jar 文件

以下示例将调用customJar的外部.jar文件添加到数据库。

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

成功将库上传到实例后，用户执行该过程 sp_execute_external_script 以安装库。

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

相关内容

• ALTER EXTERNAL LIBRARY （Transact-SQL）
• DROP EXTERNAL LIBRARY （Transact-SQL）
• sys.external_library_files
• sys.external_libraries