CREATE EXTERNAL LIBRARY (Transact-SQL)

Dotyczy: SQL Server 2017 (14.x) i nowsze wersje usługi Azure SQL Managed Instance

Przekazuje pliki pakietów R, Python lub Java do bazy danych z określonego strumienia bajtów lub ścieżki pliku. Ta instrukcja służy jako ogólny mechanizm umożliwiający administratorowi bazy danych przekazywanie artefaktów wymaganych dla wszystkich nowych środowisk uruchomieniowych języka zewnętrznego i platform systemu operacyjnego obsługiwanych przez program SQL Server.

Uwaga / Notatka

W programie SQL Server 2017 obsługiwane są języki R i platforma Windows. Języki R, Python i zewnętrzne na platformach Windows i Linux są obsługiwane w programie SQL Server 2019 i nowszych wersjach.

Składnia dla programu 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>
}

Arguments

library_name

Biblioteki przekazane do wystąpienia mogą być publiczne lub prywatne. Jeśli biblioteka jest tworzona przez członka dboprogramu , biblioteka jest publiczna i może być udostępniona wszystkim użytkownikom. W przeciwnym razie biblioteka jest prywatna tylko dla tego użytkownika.

Nazwy bibliotek muszą być unikatowe w kontekście określonego użytkownika lub właściciela. Na przykład dwaj użytkownicy RUser1 i RUser2 mogą indywidualnie i oddzielnie przekazać bibliotekę ggplot2języka R. Jeśli jednak użytkownik RUser1 chciał przekazać nowszą wersję ggplot2programu , drugie wystąpienie musi mieć inną nazwę lub musi zastąpić istniejącą bibliotekę.

Nazwy bibliotek nie mogą być przypisane dowolnie; nazwa biblioteki powinna być taka sama jak nazwa wymagana do załadowania biblioteki w skry skryptzie zewnętrznym.

owner_name

Określa nazwę użytkownika lub roli, która jest właścicielem biblioteki zewnętrznej. Jeśli nie zostanie określony, własność zostanie nadana bieżącemu użytkownikowi.

Biblioteki należące do właściciela bazy danych są uznawane za globalne dla bazy danych i środowiska uruchomieniowego. Innymi słowy, właściciele baz danych mogą tworzyć biblioteki zawierające wspólny zestaw bibliotek lub pakietów, które są współużytkowane przez wielu użytkowników. Gdy biblioteka zewnętrzna jest tworzona przez użytkownika innego niż dbo użytkownik, zewnętrzna biblioteka jest prywatna tylko dla tego użytkownika.

Gdy użytkownik RUser1 wykonuje skrypt zewnętrzny, wartość libPath może zawierać wiele ścieżek. Pierwsza ścieżka jest zawsze ścieżką do biblioteki udostępnionej utworzonej przez właściciela bazy danych. Druga część libPath elementu określa ścieżkę zawierającą pakiety przekazane indywidualnie przez użytkownika RUser1.

file_spec

Określa zawartość pakietu dla określonej platformy. Obsługiwany jest tylko jeden artefakt pliku na platformę.

Plik można określić w postaci ścieżki lokalnej lub ścieżki sieciowej.

Podczas próby uzyskania dostępu do pliku określonego w <client_library_specifier> program SQL Server personifikuje kontekst zabezpieczeń bieżącego logowania systemu Windows. Jeśli <client_library_specifier> określa lokalizację sieciową (ścieżkę UNC), personifikacja bieżącego logowania nie jest przenoszona do lokalizacji sieciowej z powodu ograniczeń delegowania. W takim przypadku dostęp jest uzyskiwany przy użyciu kontekstu zabezpieczeń konta usługi programu SQL Server. Aby uzyskać więcej informacji, zobacz Credentials (Aparat bazy danych).

Opcjonalnie można określić platformę systemu operacyjnego dla pliku. Tylko jeden artefakt lub zawartość pliku jest dozwolony dla każdej platformy systemu operacyjnego dla określonego języka lub środowiska uruchomieniowego.

library_bits

Określa zawartość pakietu jako literał szesnastkowy, podobny do zestawów.

Ta opcja jest przydatna, jeśli musisz utworzyć bibliotekę lub zmienić istniejącą bibliotekę (i mieć wymagane uprawnienia do tego), ale system plików na serwerze jest ograniczony i nie można skopiować plików biblioteki do lokalizacji, do której serwer może uzyskać dostęp.

PODEST

Określa platformę zawartości biblioteki. Wartość domyślna dla platformy hosta, na której działa program SQL Server. W związku z tym użytkownik nie musi określać wartości. Jest to wymagane w przypadku, gdy jest obsługiwanych wiele platform lub użytkownik musi określić inną platformę. W programie SQL Server 2019 obsługiwane są systemy Windows i Linux.

Język

Określa język pakietu. Wartość może mieć Rwartość , Pythonlub nazwę języka zewnętrznego (zobacz CREATE EXTERNAL LANGUAGE).

Uwagi

W przypadku języka R podczas korzystania z pliku pakiety muszą być przygotowane w postaci spakowanego pliku archiwum z rozszerzeniem .ZIP.

W przypadku języka Python pakiet w pliku .whl lub .zip musi być przygotowany w postaci spakowanego pliku archiwum. Jeśli pakiet jest już plikiem .zip, musi zostać uwzględniony w nowym pliku .zip. Przekazywanie pakietu jako pliku whl lub .zip bezpośrednio nie jest obsługiwane.

Instrukcja CREATE EXTERNAL LIBRARY przekazuje bity biblioteki do bazy danych. Biblioteka jest instalowana, gdy użytkownik uruchamia skrypt zewnętrzny przy użyciu sp_execute_external_script i wywołuje pakiet lub bibliotekę.

Biblioteki przekazane do wystąpienia mogą być publiczne lub prywatne. Jeśli biblioteka jest tworzona przez członka dboprogramu , biblioteka jest publiczna i może być udostępniona wszystkim użytkownikom. W przeciwnym razie biblioteka jest prywatna tylko dla tego użytkownika.

Wiele pakietów, nazywanych pakietami systemowym, jest wstępnie zainstalowanych w wystąpieniu SQL. Nie można dodawać, aktualizować ani usuwać pakietów systemowych przez użytkownika.

Permissions

CREATE EXTERNAL LIBRARY Wymaga uprawnienia. Domyślnie każdy użytkownik z bazą danych , który jest członkiem roli db_owner , ma uprawnienia do tworzenia biblioteki zewnętrznej. Dla wszystkich innych użytkowników musisz jawnie nadać im uprawnienia przy użyciu instrukcji GRANT , określając opcję CREATE EXTERNAL LIBRARY jako uprawnienie.

Oprócz uprawnień "CREATE EXTERNAL LIBRARY" w programie SQL Server 2019 użytkownik potrzebuje również uprawnień odwołania do języka zewnętrznego w celu utworzenia bibliotek zewnętrznych dla tego języka zewnętrznego.

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

Aby zmodyfikować dowolną bibliotekę, wymagane jest oddzielne uprawnienie. ALTER ANY EXTERNAL LIBRARY

Aby utworzyć bibliotekę zewnętrzną przy użyciu ścieżki pliku, użytkownik musi być uwierzytelnionymi identyfikatorami logowania systemu Windows lub członkiem stałej roli serwera sysadmin.

Przykłady

Dodawanie biblioteki zewnętrznej do bazy danych

Poniższy przykład dodaje bibliotekę zewnętrzną o nazwie customPackage do bazy danych.

CREATE EXTERNAL LIBRARY customPackage
FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\customPackage.zip') WITH (LANGUAGE = 'R');

Po pomyślnym przekazaniu biblioteki do wystąpienia użytkownik wykonuje sp_execute_external_script procedurę w celu zainstalowania biblioteki.

EXEC sp_execute_external_script 
@language =N'R', 
@script=N'library(customPackage)'

W przypadku języka Python w programie SQL Server 2019 przykład działa również przez zastąpienie elementem 'R''Python'.

Instalowanie pakietów z zależnościami

Jeśli pakiet, który chcesz zainstalować, ma jakiekolwiek zależności, należy przeanalizować zarówno zależności pierwszego poziomu, jak i drugiego poziomu i upewnić się, że wszystkie wymagane pakiety są dostępne przed podjęciem próby zainstalowania pakietu docelowego.

Załóżmy na przykład, że chcesz zainstalować nowy pakiet: packageA

• packageA ma zależność od packageB
• packageB ma zależność od packageC

Aby pomyślnie zainstalować packageAprogram , należy utworzyć biblioteki programu packageB i packageC jednocześnie dodać packageA je do programu SQL Server. Należy również sprawdzić wymagane wersje pakietów.

W praktyce zależności pakietów dla popularnych pakietów są zwykle znacznie bardziej skomplikowane niż w tym prostym przykładzie. Na przykład ggplot2 może wymagać ponad 30 pakietów, a te pakiety mogą wymagać dodatkowych pakietów, które nie są dostępne na serwerze. Brak pakietu lub nieprawidłowa wersja pakietu może spowodować niepowodzenie instalacji.

Ponieważ może być trudne do określenia wszystkich zależności tylko od przyjrzenia się manifestowi pakietu, zalecamy użycie pakietu, takiego jak miniCRAN , aby zidentyfikować wszystkie pakiety, które mogą być wymagane do pomyślnego ukończenia instalacji.

• Przekaż pakiet docelowy i jego zależności. Wszystkie pliki muszą znajdować się w folderze dostępnym dla serwera.

  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
  

• Najpierw zainstaluj wymagane pakiety.

  Jeśli wymagany pakiet został już przekazany do wystąpienia, nie musisz go ponownie dodawać. Pamiętaj, aby sprawdzić, czy istniejący pakiet jest poprawną wersją.

  Wymagane pakiety packageC i packageB są instalowane w prawidłowej kolejności po sp_execute_external_script pierwszym uruchomieniu w celu zainstalowania pakietu packageA.

  Jeśli jednak jakikolwiek wymagany pakiet nie jest dostępny, instalacja pakietu packageA docelowego zakończy się niepowodzeniem.

  EXEC sp_execute_external_script 
  @language =N'R', 
  @script=N'
  # load the desired package packageA
  library(packageA)
  '
  

W przypadku języka Python w programie SQL Server 2019 przykład działa również przez zastąpienie elementem 'R''Python'.

Tworzenie biblioteki na podstawie strumienia bajtów

Jeśli nie masz możliwości zapisania plików pakietu w lokalizacji na serwerze, możesz przekazać zawartość pakietu w zmiennej. Poniższy przykład tworzy bibliotekę, przekazując bity jako literał szesnastkowy.

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

W przypadku języka Python w programie SQL Server 2019 przykład działa również przez zastąpienie ciągu "R" ciągiem "Python".

Uwaga / Notatka

Ten przykładowy kod demonstruje tylko składnię; wartość binarna w pliku CONTENT = została obcięta pod kątem czytelności i nie tworzy działającej biblioteki. Rzeczywista zawartość zmiennej binarnej byłaby znacznie dłuższa.

Zmienianie istniejącej biblioteki pakietów

Instrukcja ALTER EXTERNAL LIBRARY DDL może służyć do dodawania nowej zawartości biblioteki lub modyfikowania istniejącej zawartości biblioteki. Aby zmodyfikować istniejącą bibliotekę ALTER ANY EXTERNAL LIBRARY , wymagane jest uprawnienie.

Aby uzyskać więcej informacji, zobacz ALTER EXTERNAL LIBRARY (ALTER EXTERNAL LIBRARY).

Dodawanie pliku .jar Java do bazy danych

Poniższy przykład dodaje zewnętrzny plik jar o nazwie customJar do bazy danych.

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

Po pomyślnym przekazaniu biblioteki do wystąpienia użytkownik wykonuje sp_execute_external_script procedurę w celu zainstalowania biblioteki.

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

Dodawanie pakietu zewnętrznego dla systemów Windows i Linux

Można określić maksymalnie dwa <file_spec>, jeden dla systemu Windows i jeden dla systemu 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')

Jeśli używasz sp_execute_external_script polecenia do zainstalowania pakietu, w zależności od platformy, na której jest uruchomione wystąpienie programu SQL Server, będzie używana zawartość biblioteki dla tej platformy.

EXECUTE sp_execute_external_script 
    @LANGUAGE = N'R',
    @SCRIPT = N'
library(packageA)'

Zobacz także

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