CREATE EXTERNAL LIBRARY (Transact-SQL)

[アーティクル]
05/30/2023

適用対象: SQL Server 2017 (14.x) 以降 Azure SQL Managed Instance

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

注意

SQL Server 2017 では、R 言語と Windows プラットフォームがサポートされています。 Windows および Linux プラットフォームの R、Python、外部言語は SQL Server 2019 以降でサポートされています。

指定したバイトストリームまたはファイルパスから R または Python パッケージファイルをデータベースにアップロードします。このステートメントは、データベース管理者が必要な成果物をアップロードするための一般的なメカニズムとして機能します。

注意

Azure SQL Managed Instance では、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 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'
}

引数

library_name

インスタンスにアップロードされたライブラリは、パブリックまたはプライベートのいずれかにすることができます。 dbo のメンバーによってライブラリが作成された場合、そのライブラリはパブリックで、すべてのユーザーと共有することができます。それ以外の場合、ライブラリはそのユーザーのみのプライベートになります。

ライブラリ名は、特定のユーザーまたは所有者のコンテキスト内で一意と見なされる必要があります。たとえば、RUser1 と RUser2 の 2 人のユーザーは、どちらも個別に R ライブラリ ggplot2 をアップロードできます。ただし、RUser1 が新しいバージョンの ggplot2 をアップロードする場合は、2 番目のインスタンスの名前を別のものにするか、既存のライブラリを置き換える必要があります。

ライブラリ名は任意に割り当てることはできません。ライブラリ名は外部スクリプトからライブラリを読み込むために必要な名前と同じにする必要があります。

owner_name

外部ライブラリを所有しているユーザーまたはロールの名前を指定します。このオプションを指定しない場合は、所有権は現在のユーザーに与えられます。

データベース所有者が所有するライブラリは、データベースとランタイムに対してグローバルと見なされます。つまり、データベース所有者は、多くのユーザーによって共有されているライブラリまたはパッケージの共通セットが含まれているライブラリを作成できます。 dbo ユーザー以外のユーザーによって外部ライブラリが作成されると、その外部ライブラリは、そのユーザーに対してのみプライベートになります。

ユーザー RUser1 が外部スクリプトを実行するときに、libPath の値に複数のパスを含めることができます。最初のパスは常に、データベースの所有者によって作成された共有のライブラリへのパスになります。 libPath の 2 番目の部分では、RUser1 によって個別にアップロードされたパッケージを含むパスを指定します。

file_spec

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

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

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

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

library_bits

アセンブリと同様に、パッケージのコンテンツを 16 進数のリテラルとして指定します。

このオプションは、ライブラリを作成または既存のライブラリを変更する (およびそれを行うために必要なアクセス許可を持つ) 必要があるが、サーバー上のファイルシステムが制限されていて、サーバーがアクセスできる場所にライブラリファイルをコピーできない場合に役立ちます。

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 ファイルとしてパッケージを直接アップロードすることはできません。

CREATE EXTERNAL LIBRARY ステートメントは、ライブラリビットをデータベースにアップロードします。ユーザーが sp_execute_external_script を使用して外部スクリプトを実行し、パッケージまたはライブラリを呼び出すと、ライブラリがインストールされます。

SQL インスタンスには、"システムパッケージ" という多数のパッケージが事前にインストールされています。ユーザーがシステムパッケージを追加、更新、または削除することはできません。

アクセス許可

CREATE EXTERNAL LIBRARY アクセス許可が必要です。既定では、db_owner ロールのメンバーである dbo を持つすべてのユーザーに、外部ライブラリを作成する権限があります。その他のすべてのユーザーには、特権として CREATE EXTERNAL LIBRARY を指定して、GRANT ステートメントを使用する権限を明示的に付与する必要があります。

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

依存関係を持つパッケージをインストールする

インストールするパッケージに依存関係がある場合は、ターゲットのパッケージをインストールする前に、最 1 レベルと第 2 レベルの両方の依存関係を分析し、必要なすべてのパッケージが利用できることを確認することが非常に重要です。

たとえば、新しいパッケージ 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' に替えてもこの例は機能します。

バイトストリームからライブラリを作成する

パッケージファイルをサーバー上の場所に保存できない場合は、パッケージのコンテンツを変数で渡すことができます。次の例では、ビットを 16 進数リテラルとして渡して、ライブラリを作成します。

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

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

Note

このコードサンプルは構文のみを示しています。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');

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

次の方法で共有

CREATE EXTERNAL LIBRARY (Transact-SQL)

SQL Server 2019 の構文

SQL Server 2017 の構文

Azure SQL Managed Instance の構文

引数

解説

アクセス許可

例

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

依存関係を持つパッケージをインストールする

バイトストリームからライブラリを作成する

既存のパッケージライブラリを変更する

Java .jar ファイルをデータベースに追加する

Windows と Linux の両方の外部のパッケージを追加する

関連項目

フィードバック

その他のリソース

次の方法で共有

CREATE EXTERNAL LIBRARY (Transact-SQL)

SQL Server 2019 の構文

SQL Server 2017 の構文

Azure SQL Managed Instance の構文

引数

解説

アクセス許可

例

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

依存関係を持つパッケージをインストールする

バイト ストリームからライブラリを作成する

既存のパッケージ ライブラリを変更する

Java .jar ファイルをデータベースに追加する

Windows と Linux の両方の外部のパッケージを追加する

関連項目

フィードバック

その他のリソース

バイトストリームからライブラリを作成する

既存のパッケージライブラリを変更する