CREATE EXTERNAL LIBRARY (Transact-SQL)

项目
05/30/2023

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

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

注意

在 SQL Server 2017 中，支持 R 语言和 Windows 平台。 SQL Server 2019 及更高版本支持 Windows 和 Linux 平台上的 R、Python 和外部语言。

从指定的字节流或文件路径上传 R 或 Python 包文件至数据库。此语句充当数据库管理员上传所需项目的通用机制。

注意

在 Azure SQL 托管实例中，可以使用 sqlmlutils 安装库。有关详细信息，请参阅使用 sqlmlutils 安装 Python 包和使用 sqlmlutils 安装新的 R 包。

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 
}

Azure SQL 托管实例的语法

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 可以分别独立上传 R 库 ggplot2 。不过，如果 RUser1 要上传新版 ggplot2，第二个实例要么必须以不同方式命名，要么必须替换现有库。

不能随意分配库名称；库名称应与在外部脚本中加载库时所需的名称相同。

owner_name

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

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

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

file_spec

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

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

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

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

library_bits

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

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

PLATFORM

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

LANGUAGE = 'R'

指定包的语言。 SQL Server 2017 中支持 R。

language

指定包的语言。在 Azure SQL 托管实例中，该值可以为 R 或 Python。

language

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

备注

对于 R 语言，使用文件时，必须使用 Windows 的 .ZIP 扩展名以压缩存档文件的形式准备包。在 SQL Server 2017 中，仅支持 Windows 平台。

对于 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 中，除了“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 步骤来安装库。

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

对于 SQL Server 2019 中的 Python 语言，可通过将 'R' 替换为 'Python' 使用示例。

安装具有依赖项的包

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

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

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

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

在实践中，常用包的依赖项通常比简单示例复杂得多。例如，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

首先安装所需的包。

如果所需的包已上传到实例，则不需要再次添加。请务必检查现有包的版本是否正确。

第一次运行 sp_execute_external_script 以安装包 packageA 时，所需的包 packageC 和 packageB 也会按照正确的顺序安装。

但是，如果所需的包均不可用，则安装目标包 packageA 时会失败。
```
EXEC sp_execute_external_script 
@language =N'R', 
@script=N'
# load the desired package packageA
library(packageA)
'
```

对于 SQL Server 2019 中的 Python 语言，可通过将 'R' 替换为 'Python' 使用示例。

从字节流创建库

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

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

对于 SQL Server 2019 中的 Python 语言，可通过将 “R” 替换为 “Python” 使用示例。

注意

此代码示例只用于展示语法；为了提高可读性，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 步骤来安装库。

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

根据运行 SQL Server 实例的平台，在使用 sp_execute_external_script 来安装包时，将使用此平台的库内容。

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

通过