CREATE EXTERNAL LIBRARY(Transact-SQL)

아티클
07/05/2024

적용 대상: 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는 모두 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

패키지의 콘텐츠를 어셈블리와 유사한 16진수 리터럴로 지정합니다.

이 옵션은 라이브러리를 만들거나 기존 라이브러리를 변경해야 하지만(필요한 사용 권한이 있음) 서버의 파일 시스템이 제한되며 라이브러리 파일을 서버에서 액세스할 수 있는 위치에 복사할 수 없는 경우에 유용합니다.

플랫폼

라이브러리의 콘텐츠에 대한 플랫폼을 지정합니다. 이 값은 기본적으로 SQL Server가 실행 중인 호스트 플랫폼으로 설정됩니다. 따라서 사용자는 값을 지정할 필요가 없습니다. 여러 플랫폼이 지원되거나 사용자가 다른 플랫폼을 지정해야 하는 경우 필요합니다. SQL Server 2019에서 Windows 및 Linux는 지원되는 플랫폼입니다.

LANGUAGE = 'R'

패키지의 언어를 지정합니다. R은 SQL Server 2017에서 지원됩니다.

language

패키지의 언어를 지정합니다. 값은 Azure SQL Managed Instance일 수 R Python 있습니다.

language

패키지의 언어를 지정합니다. 값은 외부 언어의 이름일 수 있습니다RPython(CREATE EXTERNAL LANGUAGE 참조).

설명

R 언어의 경우 파일을 사용하는 경우 패키지는 Windows용 .ZIP 확장이 있는 압축된 보관 파일 형식으로 준비해야 합니다. SQL Server 2017에서는 Windows 플랫폼만 지원됩니다.

R 언어의 경우 파일을 사용할 때 패키지를 .ZIP 확장명의 압축된 보관 파일 형태로 준비해야 합니다.

Python 언어의 경우 .whl 또는 .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에서 '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에 성공하려면 SQL Server에 추가하는 packageA 동시에 라이브러리를 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

먼저 필요한 패키지를 설치합니다.

필요한 패키지가 인스턴스에 이미 업로드된 경우 다시 추가할 필요는 없습니다. 기존 패키지가 올바른 버전인지 확인해야 합니다.

필수 패키지 packageC 이며 packageB 패키지를 설치하기 위해 처음 실행되는 경우 sp_execute_external_script 올바른 순서로 설치 packageA됩니다.

그러나 필요한 패키지를 사용할 수 없는 경우 대상 패키지 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'으로 대체하여 작동합니다.

참고 항목

이 코드 샘플은 구문만 보여 줍니다. 가독성을 위해 이진 값 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 모두에 대한 외부 패키지 추가

Windows용 하나와 Linux용 하나로 최대 두 개의 <file_spec>를 지정할 수 있습니다.

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

참고 항목

ALTER EXTERNAL LIBRARY(Transact-SQL)
DROP EXTERNAL LIBRARY(Transact-SQL)
sys.external_library_files
sys.external_libraries

다음을 통해 공유

CREATE EXTERNAL LIBRARY(Transact-SQL)

SQL Server 2019용 구문

SQL Server 2017용 구문

Azure SQL Managed Instance용 구문

인수

설명

사용 권한

예제

데이터베이스에 외부 라이브러리 추가

종속성이 있는 패키지 설치

바이트 스트림에서 라이브러리 만들기

기존 패키지 라이브러리 변경

데이터베이스에 Java .jar 파일 추가

Windows 및 Linux 모두에 대한 외부 패키지 추가

참고 항목

피드백

추가 리소스