CREATE EXTERNAL LIBRARY (Transact-SQL)

適用対象:AZURE SQL Managed Instance SQL Server 2017 (14.x) 以降のバージョン

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

注意

SQL Server 2017 (14.x) では、R 言語と Windows プラットフォームがサポートされています。 Windows および Linux プラットフォーム上の R、Python、および外部言語は、SQL Server 2019 (15.x) 以降のバージョンでサポートされています。

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

引数

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 進数のリテラルとして指定します。

このオプションは、ライブラリを作成したり、既存のライブラリを変更したりする必要がある (必要なアクセス許可を持っている) が、サーバー上のファイルシステムが制限され、サーバーがアクセスできる場所にライブラリファイルをコピーできない場合に便利です。

プラットフォーム

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

LANGUAGE = 'R'

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

LANGUAGE

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

LANGUAGE

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

解説

R 言語の場合、ファイルを使用する場合、パッケージは、windows 用の .zip 拡張子を持つ zip 形式のアーカイブファイルの形式で準備する必要があります。 SQL Server 2017 (14.x) では、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 を持つすべてのユーザーに、外部ライブラリを作成する権限があります。他のすべてのユーザーについては、 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'に置き換えることでも機能します。

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

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

たとえば、新しいパッケージ 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'に置き換えることでも機能します。

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

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

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 ファイルをデータベースに追加する

次の例では、customJarと呼ばれる外部.jar ファイルをデータベースに追加します。

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

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

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-01-28

次の方法で共有

CREATE EXTERNAL LIBRARY (Transact-SQL)

SQL Server 2019 の構文

SQL Server 2017 の構文

Azure SQL Managed Instance の構文

引数

LIBRARY_NAME

OWNER_NAME

FILE_SPEC

LIBRARY_BITS

プラットフォーム

LANGUAGE = 'R'

LANGUAGE

LANGUAGE

解説

アクセス許可

例

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

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

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

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

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

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

関連コンテンツ

フィードバック

その他のリソース

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

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