CREATE EXTERNAL LIBRARY (Transact-SQL)

Berlaku untuk: SQL Server 2017 (14.x) dan yang lebih baru Azure SQL Managed Instance

Mengunggah file paket R, Python, atau Java ke database dari aliran byte atau jalur file yang ditentukan. Pernyataan ini berfungsi sebagai mekanisme umum bagi administrator database untuk mengunggah artefak yang diperlukan untuk setiap runtime bahasa eksternal dan platform OS baru yang didukung oleh SQL Server.

Catatan

Pada SQL Server 2017, bahasa R dan platform Windows didukung. R, Python, dan bahasa eksternal pada platform Windows dan Linux didukung di SQL Server 2019 dan yang lebih baru.

Sintaks untuk 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>
}

Argumen

library_name

Pustaka yang diunggah ke instans dapat bersifat publik atau privat. Jika pustaka dibuat oleh anggota dbo, pustaka bersifat publik dan dapat dibagikan dengan semua pengguna. Jika tidak, pustaka bersifat privat hanya untuk pengguna tersebut.

Nama pustaka harus unik dalam konteks pengguna atau pemilik tertentu. Misalnya, dua pengguna RUser1 dan RUser2 dapat mengunggah pustaka ggplot2R secara individual dan terpisah. Namun, jika RUser1 ingin mengunggah versi yang lebih baru dari ggplot2, instans kedua harus diberi nama secara berbeda atau harus mengganti pustaka yang ada.

Nama pustaka tidak dapat ditetapkan secara acak; nama pustaka harus sama dengan nama yang diperlukan untuk memuat pustaka di skrip eksternal.

owner_name

Menentukan nama pengguna atau peran yang memiliki pustaka eksternal. Jika tidak ditentukan, kepemilikan diberikan kepada pengguna saat ini.

Pustaka yang dimiliki oleh pemilik database dianggap global untuk database dan runtime. Dengan kata lain, pemilik database dapat membuat pustaka yang berisi sekumpulan pustaka atau paket umum yang dibagikan oleh banyak pengguna. Saat pustaka eksternal dibuat oleh pengguna selain pengguna, pustaka eksternal bersifat privat hanya untuk pengguna tersebut dbo .

Saat pengguna RUser1 menjalankan skrip eksternal, nilai libPath dapat berisi beberapa jalur. Jalur pertama selalu merupakan jalur ke pustaka bersama yang dibuat oleh pemilik database. Bagian kedua menentukan libPath jalur yang berisi paket yang diunggah satu per satu oleh RUser1.

file_spec

Menentukan konten paket untuk platform tertentu. Hanya satu artefak file per platform yang didukung.

File dapat ditentukan dalam bentuk jalur lokal, atau jalur jaringan.

Ketika mencoba mengakses file yang ditentukan dalam <client_library_specifier>, SQL Server meniru konteks keamanan login Windows saat ini. Jika <client_library_specifier> menentukan lokasi jaringan (jalur UNC), peniruan login saat ini tidak dibawa ke lokasi jaringan karena batasan delegasi. Dalam hal ini, akses dibuat menggunakan konteks keamanan akun layanan SQL Server. Untuk informasi selengkapnya, lihat Kredensial (Mesin Database).

Secara opsional, platform OS untuk file dapat ditentukan. Hanya satu artefak atau konten file yang diizinkan untuk setiap platform OS untuk bahasa atau runtime tertentu.

library_bits

Menentukan konten paket sebagai hex literal, mirip dengan rakitan.

Opsi ini berguna jika Anda perlu membuat pustaka atau mengubah pustaka yang ada (dan memiliki izin yang diperlukan untuk melakukannya), tetapi sistem file di server dibatasi dan Anda tidak dapat menyalin file pustaka ke lokasi yang dapat diakses server.

PLATFORM

Menentukan platform untuk konten pustaka. Nilai default ke platform host tempat SQL Server berjalan. Oleh karena itu, pengguna tidak perlu menentukan nilainya. Diperlukan jika beberapa platform didukung, atau pengguna perlu menentukan platform yang berbeda. Pada SQL Server 2019, Windows dan Linux adalah platform yang didukung.

bahasa

Menentukan bahasa paket. Nilainya bisa R, Python, atau nama bahasa eksternal (lihat CREATE EXTERNAL LANGUAGE).

Keterangan

Untuk bahasa R, saat menggunakan file, paket harus disiapkan dalam bentuk file arsip zip dengan ekstensi .ZIP.

Untuk bahasa Python, paket dalam file .whl atau .zip harus disiapkan dalam bentuk file arsip zip. Jika paket sudah merupakan file .zip, paket harus disertakan dalam file .zip baru. Mengunggah paket sebagai file .whl atau .zip secara langsung saat ini tidak didukung.

Pernyataan mengunggah CREATE EXTERNAL LIBRARY bit pustaka ke database. Pustaka diinstal saat pengguna menjalankan skrip eksternal menggunakan sp_execute_external_script dan memanggil paket atau pustaka.

Pustaka yang diunggah ke instans dapat bersifat publik atau privat. Jika pustaka dibuat oleh anggota dbo, pustaka bersifat publik dan dapat dibagikan dengan semua pengguna. Jika tidak, pustaka bersifat privat hanya untuk pengguna tersebut.

Sejumlah paket, yang disebut sebagai paket sistem, telah diinstal sebelumnya dalam instans SQL. Paket sistem tidak dapat ditambahkan, diperbarui, atau dihapus oleh pengguna.

Izin

CREATE EXTERNAL LIBRARY Memerlukan izin. Secara default, setiap pengguna yang memiliki dbo yang merupakan anggota peran db_owner memiliki izin untuk membuat pustaka eksternal. Untuk semua pengguna lain, Anda harus secara eksplisit memberi mereka izin menggunakan pernyataan GRANT , menentukan CREATE EXTERNAL LIBRARY sebagai hak istimewa.

Di SQL Server 2019, selain izin 'CREATE EXTERNAL LIBRARY', pengguna juga memerlukan izin referensi pada bahasa eksternal untuk membuat pustaka eksternal untuk bahasa eksternal tersebut.

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

Untuk mengubah pustaka apa pun memerlukan izin terpisah, ALTER ANY EXTERNAL LIBRARY.

Untuk membuat pustaka eksternal dengan menggunakan jalur file, pengguna harus menjadi login terautentikasi Windows atau anggota peran server tetap sysadmin.

Contoh

Menambahkan pustaka eksternal ke database

Contoh berikut menambahkan pustaka eksternal yang dipanggil customPackage ke database.

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

Setelah pustaka berhasil diunggah ke instans sp_execute_external_script , pengguna menjalankan prosedur, untuk menginstal pustaka.

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

Untuk bahasa Python di SQL Server 2019, contohnya juga berfungsi dengan mengganti 'R' dengan 'Python'.

Menginstal paket dengan dependensi

Jika paket yang ingin Anda instal memiliki dependensi apa pun, sangat penting bagi Anda untuk menganalisis dependensi tingkat pertama dan tingkat kedua, dan memastikan bahwa semua paket yang diperlukan tersedia sebelum Anda mencoba menginstal paket target.

Misalnya, asumsikan Anda ingin menginstal paket baru, packageA:

• packageA memiliki dependensi pada packageB
• packageB memiliki dependensi pada packageC

Agar berhasil menginstal packageA, Anda harus membuat pustaka untuk packageB dan packageC pada saat yang sama dengan yang Anda tambahkan packageA ke SQL Server. Pastikan untuk memeriksa versi paket yang diperlukan juga.

Dalam praktiknya, dependensi paket untuk paket populer biasanya jauh lebih rumit daripada contoh sederhana ini. Misalnya, ggplot2 mungkin memerlukan lebih dari 30 paket, dan paket tersebut mungkin memerlukan paket tambahan yang tidak tersedia di server. Paket yang hilang atau versi paket yang salah dapat menyebabkan penginstalan gagal.

Karena mungkin sulit untuk menentukan semua dependensi hanya dari melihat manifes paket, kami sarankan Anda menggunakan paket seperti miniCRAN untuk mengidentifikasi semua paket yang mungkin diperlukan untuk menyelesaikan penginstalan dengan sukses.

• Unggah paket target dan dependensinya. Semua file harus berada dalam folder yang dapat diakses oleh server.

  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
  

• Instal paket yang diperlukan terlebih dahulu.

  Jika paket yang diperlukan telah diunggah ke instans, Anda tidak perlu menambahkannya lagi. Pastikan untuk memeriksa apakah paket yang ada adalah versi yang benar.

  Paket yang packageC diperlukan dan packageB diinstal, dalam urutan yang benar, ketika sp_execute_external_script pertama kali dijalankan untuk menginstal paket packageA.

  Namun, jika ada paket yang diperlukan tidak tersedia, penginstalan paket packageA target gagal.

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

Untuk bahasa Python di SQL Server 2019, contohnya juga berfungsi dengan mengganti 'R' dengan 'Python'.

Membuat pustaka dari aliran byte

Jika Anda tidak memiliki kemampuan untuk menyimpan file paket di lokasi di server, Anda dapat meneruskan konten paket dalam variabel. Contoh berikut membuat pustaka dengan meneruskan bit sebagai literal heksadesimal.

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

Untuk bahasa Python di SQL Server 2019, contohnya juga berfungsi dengan mengganti 'R' dengan 'Python'.

Catatan

Sampel kode ini hanya menunjukkan sintaks; nilai biner di telah dipotong CONTENT = untuk keterbacaan dan tidak membuat pustaka kerja. Konten aktual dari variabel biner akan lebih lama.

Mengubah pustaka paket yang sudah ada

Pernyataan ALTER EXTERNAL LIBRARY DDL dapat digunakan untuk menambahkan konten pustaka baru atau mengubah konten pustaka yang ada. Untuk mengubah pustaka yang ada, memerlukan ALTER ANY EXTERNAL LIBRARY izin.

Untuk informasi selengkapnya, lihat MENGUBAH PUSTAKA EKSTERNAL.

Menambahkan file .jar Java ke database

Contoh berikut menambahkan file jar eksternal yang dipanggil customJar ke database.

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

Setelah pustaka berhasil diunggah ke instans sp_execute_external_script , pengguna menjalankan prosedur, untuk menginstal pustaka.

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

Menambahkan paket eksternal untuk Windows dan Linux

Anda dapat menentukan hingga dua <file_spec>, satu untuk Windows dan satu untuk 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')

Ketika Anda menggunakan sp_execute_external_script untuk menginstal paket, tergantung pada platform tempat instans SQL Server berjalan, konten pustaka untuk platform tersebut akan digunakan.

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

Lihat juga

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