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 (14.x), R dili ve Windows platformu desteklenir. Windows ve Linux platformlarındaki R, Python ve dış diller SQL Server 2019 (15.x) 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, iki kullanıcı RUser1 ve RUser2 hem ayrı hem de ayrı olarak R kitaplığı ggplot2'yi karşıya yükleyebilir. Ancak, ggplot2'nin daha yeni bir sürümünü karşıya yüklemek istiyorsanızRUser1, ikinci örneğin farklı şekilde adlandırılması veya mevcut kitaplığın yerini alması gerekir.

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.

Kullanıcı RUser1 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ü tarafından RUser1tek 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.

içinde <client_library_specifier>belirtilen dosyaya erişmeye çalışırken SQL Server, geçerli Windows oturum açma bilgilerinin güvenlik bağlamının kimliğine bürüner. Bir ağ konumu (UNC yolu) belirtirse <client_library_specifier> , temsilci sınırlamaları nedeniyle geçerli oturum açmanın 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 kopyalayamazsanız bu seçenek kullanışlıdır.

PLATFORM

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 (15.x), Desteklenen platformlar Windows ve Linux'tır.

LANGUAGE

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

Açıklamalar

R dili için, dosya kullanılırken paketler uzantılı .zip 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 dosyaysa, yeni .zip bir dosyaya eklenmelidir. Paketin veya dosyanın doğrudan karşıya .whl.zip yüklenmesi ş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ğine sistem paketleri olarak adlandırılan çeşitli paketler önceden yüklenir. Sistem paketlerini ekleyemez, güncelleştiremez veya kaldıramazsınız.

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 belirterek CREATE EXTERNAL LIBRARYgrant deyimini kullanarak onlara açıkça izin vermeniz gerekir.

SQL Server 2019'da (15.x), izinlere CREATE EXTERNAL LIBRARY 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, kullanıcı kitaplığı yüklemek için yordamı yürütür sp_execute_external_script .

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

SQL Server 2019'daki (15.x) Python dili için, örnek ile 'Python'değiştirilerek 'R' de çalışır.

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

Yüklemek istediğiniz paketin bağımlılıkları varsa, hedef paketi yüklemeye çalışmadan önce hem birinci düzey hem de ikinci düzey bağımlılıkları analiz edip 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ı bu örnekten 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 gereken tüm paketleri tanımlamak için miniCRAN gibi bir paket kullanın.

• 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 packageByüklemek için ilk kez çalıştırıldığında sp_execute_external_scriptpackageA doğru sırada yüklenir.

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

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

SQL Server 2019'daki (15.x) Python dili için, örnek ile 'Python'değiştirilerek 'R' de çalışır.

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

Paket dosyalarını sunucudaki bir konuma kaydedemiyorsanız, 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 (15.x) Python dili için, örnek ile Pythondeğiştirilerek R de çalışır.

Uyarı

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

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, customJar adlı bir dış .jar dosyayı veritabanına 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, kullanıcı kitaplığı yüklemek için yordamı yürütür sp_execute_external_script .

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

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

İlgili içerik

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