CREATE EXTERNAL LIBRARY (Transact-SQL)

Şunlar için geçerlidir: SQL Server 2017 (14.x) ve sonraki sürümleri Azure SQL Yönetilen Örneği

R, Python veya Java paket dosyalarını belirtilen bayt akışından veya dosya yolundan bir veritabanına yükler. Bu deyim, veritabanı yöneticisinin SQL Server tarafından desteklenen tüm yeni dış dil çalışma zamanları ve işletim sistemi platformları için gereken yapıtları karşıya yüklemesi için genel bir mekanizma görevi görür.

Uyarı

SQL Server 2017'de R dili ve Windows platformu desteklenir. Windows ve Linux platformlarındaki R, Python ve dış diller SQL Server 2019 ve sonraki sürümlerde desteklenir.

SQL Server 2019 söz dizimi

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

Örneğe yüklenen kitaplıklar genel veya özel olabilir. Kitaplık bir üyesi dbotarafından oluşturulduysa, kitaplık geneldir ve tüm kullanıcılarla paylaşılabilir. Aksi takdirde, kitaplık yalnızca bu kullanıcıya özeldir.

Kitaplık adları belirli bir kullanıcı veya sahip bağlamında benzersiz olmalıdır. Örneğin, RUser1 ve RUser2 kullanıcıları R kitaplığını ggplot2tek tek ve ayrı olarak karşıya yükleyebilir. Ancak , RUser1 daha yeni bir sürümünü ggplot2karşıya yüklemek istiyorsa, ikinci örnek farklı adlandırılmalıdır veya mevcut kitaplığın yerini almalıdır.

Kitaplık adları rastgele atanamaz; kitaplık adı, dış betikte kitaplığı yüklemek için gereken adla aynı olmalıdır.

owner_name

Dış kitaplığın sahibi olan kullanıcının veya rolün adını belirtir. Belirtilmezse, sahiplik geçerli kullanıcıya verilir.

Veritabanı sahibine ait kitaplıklar, veritabanı ve çalışma zamanı için genel olarak kabul edilir. Başka bir deyişle, veritabanı sahipleri birçok kullanıcı tarafından paylaşılan ortak kitaplıklar veya paketler içeren kitaplıklar oluşturabilir. Dış kitaplık, kullanıcı dışında dbo bir kullanıcı tarafından oluşturulduğunda, dış kitaplık yalnızca bu kullanıcıya özeldir.

RUser1 kullanıcısı bir dış betik yürüttüğünde değeri libPath birden çok yol içerebilir. İlk yol her zaman veritabanı sahibi tarafından oluşturulan paylaşılan kitaplığın yoludur. öğesinin libPath ikinci bölümü , RUser1 tarafından tek tek karşıya yüklenen paketleri içeren yolu belirtir.

file_spec

Belirli bir platform için paketin içeriğini belirtir. Platform başına yalnızca bir dosya yapıtı desteklenir.

Dosya yerel yol veya ağ yolu biçiminde belirtilebilir.

SQL Server, client_library_specifier'de<> belirtilen dosyaya erişmeye çalışırken geçerli Windows oturum açma bilgilerinin güvenlik bağlamının kimliğine bürüner. client_library_specifier bir ağ konumu (UNC yolu) belirtirse<, temsilci sınırlamaları nedeniyle geçerli oturum açma kimliğine bürünme ağ konumuna taşınmaz.> Bu durumda erişim, SQL Server hizmet hesabının güvenlik bağlamı kullanılarak yapılır. Daha fazla bilgi için bkz. Kimlik Bilgileri (Veritabanı Altyapısı).

İsteğe bağlı olarak, dosya için bir işletim sistemi platformu belirtilebilir. Belirli bir dil veya çalışma zamanı için her işletim sistemi platformu için yalnızca bir dosya yapıtına veya içeriğe izin verilir.

library_bits

Paketin içeriğini derlemelere benzer şekilde onaltılık değişmez değer olarak belirtir.

Bir kitaplık oluşturmanız veya var olan bir kitaplığı değiştirmeniz gerekiyorsa (ve bunu yapmak için gerekli izinlere sahipseniz) ancak sunucudaki dosya sistemi kısıtlanmışsa ve kitaplık dosyalarını sunucunun erişebileceği bir konuma kopyalayamıyorsanız bu seçenek kullanışlıdır.

PERON

Kitaplığın içeriğinin platformunu belirtir. Değeri varsayılan olarak SQL Server'ın üzerinde çalıştığı konak platformudur. Bu nedenle, kullanıcının değeri belirtmesi gerekmez. Birden çok platformun desteklendiği durumlarda veya kullanıcının farklı bir platform belirtmesi gerektiğinde gereklidir. SQL Server 2019'da desteklenen platformlar Windows ve Linux'tır.

Dil

Paketin dilini belirtir. Değer , Pythonveya bir dış dilin adı olabilir R(bkz. HARİÇ Dİl OLUŞTURMA).

Açıklamalar

R dili için, bir dosya kullanılırken paketler .ZIP uzantısıyla sıkıştırılmış arşiv dosyaları biçiminde hazırlanmalıdır.

Python dili için bir .whl veya .zip dosyasındaki paket sıkıştırılmış arşiv dosyası biçiminde hazırlanmalıdır. Paket zaten bir .zip dosyasıysa, yeni bir .zip dosyasına eklenmelidir. Paketi .whl veya .zip dosyası olarak doğrudan karşıya yükleme şu anda desteklenmiyor.

deyimi CREATE EXTERNAL LIBRARY , kitaplık bitlerini veritabanına yükler. Kitaplık, kullanıcı sp_execute_external_script kullanarak bir dış betik çalıştırdığında ve paketi veya kitaplığı çağırdığında yüklenir.

Örneğe yüklenen kitaplıklar genel veya özel olabilir. Kitaplık bir üyesi dbotarafından oluşturulduysa, kitaplık geneldir ve tüm kullanıcılarla paylaşılabilir. Aksi takdirde, kitaplık yalnızca bu kullanıcıya özeldir.

Bir SQL örneğinde sistem paketleri olarak adlandırılan bir dizi paket önceden yüklenir. Sistem paketleri kullanıcı tarafından eklenemez, güncelleştirilemez veya kaldırılamaz.

Permissions

İzin gerektirir CREATE EXTERNAL LIBRARY . Varsayılan olarak, db_owner rolünün üyesi olan dbo'ya sahip tüm kullanıcıların dış kitaplık oluşturma izinleri vardır. Diğer tüm kullanıcılar için, ayrıcalık olarak CREATE EXTERNAL LIBRARY belirterek grant deyimini kullanarak onlara açıkça izin vermeniz gerekir.

SQL Server 2019'da , 'EXTERNAL LIBRARY OLUŞTUR' iznine ek olarak, kullanıcının bu dış dil için dış kitaplıklar oluşturmak için dış dilde başvuru iznine de ihtiyacı vardır.

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

Herhangi bir kitaplığı değiştirmek için ayrı bir izin gerekir. ALTER ANY EXTERNAL LIBRARY

Dosya yolu kullanarak dış kitaplık oluşturmak için, kullanıcının Windows kimliği doğrulanmış bir oturum açma bilgisi veya sysadmin sabit sunucu rolünün üyesi olması gerekir.

Örnekler

Veritabanına dış kitaplık ekleme

Aşağıdaki örnek, customPackage adlı bir dış kitaplığı veritabanına ekler.

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

Kitaplık örneğe başarıyla yüklendikten sonra, bir kullanıcı kitaplığı yüklemek için yordamı yürütür sp_execute_external_script .

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

SQL Server 2019'daki Python dili için, örneği ile 'Python'değiştirerek 'R' de çalışır.

Bağımlılıkları olan paketleri yükleme

Yüklemek istediğiniz paketin bağımlılıkları varsa, hem birinci düzey hem de ikinci düzey bağımlılıkları analiz etmek ve hedef paketi yüklemeye çalışmadan önce tüm gerekli paketlerin kullanılabilir olduğundan emin olmanız kritik önem taşır.

Örneğin, yeni bir paket yüklemek istediğinizi varsayalım: packageA

• packageA bir bağımlılığı var packageB
• packageB bir bağımlılığı var packageC

yükleme packageAişleminin başarılı olması için packageB ve packageC ile aynı zamanda SQL Server'a eklediğiniz packageA kitaplıklar oluşturmanız gerekir. Gerekli paket sürümlerini de denetlemeyi unutmayın.

Uygulamada, popüler paketler için paket bağımlılıkları genellikle bu basit örnekten çok daha karmaşıktır. Örneğin, ggplot2 için 30'un üzerinde paket gerekebilir ve bu paketler sunucuda bulunmayan ek paketler gerektirebilir. Eksik paket veya yanlış paket sürümü yüklemenin başarısız olmasına neden olabilir.

Yalnızca paket bildirimine bakarak tüm bağımlılıkları belirlemek zor olabileceğinden, yüklemeyi başarıyla tamamlamak için gerekli olabilecek tüm paketleri tanımlamak için miniCRAN gibi bir paket kullanmanızı öneririz.

• Hedef paketi ve bağımlılıklarını karşıya yükleyin. Tüm dosyalar, sunucu tarafından erişilebilen bir klasörde olmalıdır.

  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
  

• Önce gerekli paketleri yükleyin.

  Gerekli bir paket örneğe zaten yüklenmişse, yeniden eklemeniz gerekmez. Mevcut paketin doğru sürüm olup olmadığını denetlemeyi unutmayın.

  gerekli paketler packageC ve, paketini packageAyüklemek için ilk kez çalıştırıldığında sp_execute_external_scriptpackageB doğru sırada yüklenir.

  Ancak gerekli paketlerden herhangi biri kullanılamıyorsa hedef paketin packageA yüklenmesi başarısız olur.

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

SQL Server 2019'daki Python dili için, örneği ile 'Python'değiştirerek 'R' de çalışır.

Bayt akışından kitaplık oluşturma

Paket dosyalarını sunucudaki bir konuma kaydetme olanağınız yoksa, paket içeriğini bir değişkene geçirebilirsiniz. Aşağıdaki örnek, bitleri onaltılık değişmez değer olarak geçirerek bir kitaplık oluşturur.

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

SQL Server 2019'daki Python dili için örnek, 'R' yerine 'Python' yazarak da çalışır.

Uyarı

Bu kod örneği yalnızca söz dizimini gösterir; içindeki CONTENT = ikili değeri okunabilirlik için kesilmiştir ve çalışma kitaplığı oluşturmaz. İkili değişkenin gerçek içeriği çok daha uzun olacaktır.

Mevcut paket kitaplığını değiştirme

ALTER EXTERNAL LIBRARY DDL deyimi, yeni kitaplık içeriği eklemek veya mevcut kitaplık içeriğini değiştirmek için kullanılabilir. Varolan bir kitaplığı değiştirmek için izin gerekir ALTER ANY EXTERNAL LIBRARY .

Daha fazla bilgi için bkz. ALTER EXTERNAL LIBRARY.

Veritabanına Java .jar dosyası ekleme

Aşağıdaki örnek, veritabanına adlı customJar bir dış jar dosyası ekler.

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

Kitaplık örneğe başarıyla yüklendikten sonra, bir kullanıcı kitaplığı yüklemek için yordamı yürütür 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))

Hem Windows hem de Linux için dış paket ekleme

Biri Windows, biri Linux için olmak üzere en fazla iki <file_spec>tane belirtebilirsiniz.

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

Paketi yüklemek için kullandığınızda sp_execute_external_script , SQL Server örneğinin çalıştığı platforma bağlı olarak, söz konusu platformun kitaplık içeriği kullanılır.

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

Ayrıca bakınız

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