建立外部程式庫 （Transact-SQL）

適用於：SQL Server 2017 （14.x） 和更新版本Azure SQL 受控執行個體

將 R、Python 或 Java 套件檔案從指定的位元組資料流或檔案路徑上傳到資料庫。 此陳述式是資料庫管理員因 SQL Server 支援任何新外部語言執行階段和 OS 平台而需要上傳成品時常用的方法。

注意

在 SQL Server 2017（14.x）中，支援 R 語言與 Windows 平台。 Windows 和 Linux 平台上的 R、Python 及外部語言在 SQL Server 2019（15.x）及後續版本中均獲得支援。

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。

語言

指定套件的語言。 此值可以是 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 認證的登入者或系統 管理員 固定伺服器角色的成員。

範例

將外部程式庫新增至資料庫

下列範例會將名為 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 語言，範例也可透過替換 R 為 Python來運作。

注意

此程式碼範例僅展示語法;其中 CONTENT = 的二進位值被截斷以提升可讀性，並未建立一個可運作的函式庫。 二元變數的實際內容會比較長。

變更現有的套件程式庫

ALTER EXTERNAL LIBRARY DDL 陳述式可用來新增程式庫內容，或修改現有的程式庫內容。 若要修改現有的程式庫，需要 ALTER ANY EXTERNAL LIBRARY 權限。

如需詳細資訊，請參閱 ALTER EXTERNAL LIBRARY。

將 Java.jar 檔案新增至資料庫

以下範例新增一個 .jar 外部檔案，呼叫 customJar 到資料庫中。

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

相關內容

• 變更外部程式庫 （Transact-SQL）
• 刪除外部庫 （Transact-SQL）
• sys.external_library_files
• sys.external_libraries