CREATE EXTERNAL LIBRARY (Transact-SQL)

指定したバイト ストリームまたはファイル パスから R、Python、Java パッケージ ファイルをデータベースにアップロードします。 このステートメントは、データベース管理者が新しい外部言語ランタイムに必要な成果物および SQL Server でサポートされる OS プラットフォームをアップロードする汎用メカニズムとして機能します。

指定したバイト ストリームまたはファイル パスから 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 
}

Azure SQL Managed Instance の構文

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'
}

file_spec

特定のプラットフォーム用のパッケージのコンテンツを指定します。 プラットフォームごとに 1 つのファイル成果物のみがサポートされます。

ファイルは、ローカル パスまたはネットワーク パスの形式で指定することができます。

<client_library_specifier> で指定したファイルにアクセスしようとすると、SQL Server では現在の Windows ログインのセキュリティ コンテキストの権限が借用されます。 <client_library_specifier> でネットワーク上の場所 (UNC パス) を指定した場合は、委任制限があり、現在のログインの権限借用範囲はネットワーク上の場所まで拡大されません。 この場合、アクセスは SQL Server サービス アカウントのセキュリティ コンテキストを使って行われます。 詳しくは、「資格情報 (データベース エンジン)」をご覧ください。

必要に応じて、ファイルの OS プラットフォームを指定できます。 特定の言語またはランタイムの OS プラットフォームごとに 1 つのファイル成果物またはコンテンツのみが許可されます。

PLATFORM

ライブラリのコンテンツのプラットフォームを指定します。 既定値は、SQL Server が実行されているホスト プラットフォームに設定されます。 そのため、ユーザーが値を指定する必要はありません。 複数のプラットフォームがサポートされている場合、またはユーザーが別のプラットフォームを指定する必要がある場合に必要です。 SQL Server 2019 でサポートされているプラットフォームは、Windows と Linux です。

LANGUAGE = 'R'

パッケージの言語を指定します。 R は SQL Server 2017 でサポートされています。

language

パッケージの言語を指定します。 Azure SQL Managed Instance では、この値を R または Python に指定できます。

language

パッケージの言語を指定します。 値は R、Python、または外部言語の名前にできます (「CREATE EXTERNAL LANGUAGE」を参照してください)。

R 言語の場合、ファイルを使用するときに、Windows の .ZIP 拡張子を使用して、ZIP アーカイブ ファイルの形式でパッケージを準備する必要があります。 SQL Server 2017 では、Windows プラットフォームのみがサポートされています。

R 言語の場合、ファイルを使用するときに .ZIP 拡張子を使用して、ZIP アーカイブ ファイルの形式でパッケージを準備する必要があります。

Python 言語の場合、.whl または .zip ファイルのパッケージは zip アーカイブ ファイルの形式で準備する必要があります。 パッケージが既に .zip ファイルになっている場合、新しい .zip ファイルに含める必要があります。 現在のところ、.whl または .zip ファイルとしてパッケージを直接アップロードすることはできません。

SQL Server 2019 では、ユーザーには 'CREATE EXTERNAL LIBRARY' アクセス許可に加えて、その外部言語の外部ライブラリを作成するために、外部言語に対する参照アクセス許可も必要です。

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

外部ライブラリをデータベースに追加する

次の例では、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' に替えてもこの例は機能します。

• ターゲット パッケージとその依存関係をアップロードします。 すべてのファイルは、サーバーからアクセスできるフォルダー内にある必要があります。

  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' に替えてもこの例は機能します。

SQL Server 2019 の Python 言語の場合、 'R' を 'Python' に替えてもこの例は機能します。

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 の両方の外部のパッケージを追加する

最大 2 つの <file_spec> を指定できます。1 つは Windows 用、1 つは 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)'