KÜLSŐ KÓDTÁR LÉTREHOZÁSA (Transact-SQL)

A következőkre vonatkozik: Sql Server 2017 (14.x) és újabb verziók Felügyelt Azure SQL-példány

R-, Python- vagy Java-csomagfájlokat tölt fel egy adatbázisba a megadott bájtstreamből vagy fájlelérési útból. Ez az utasítás általános mechanizmusként szolgál arra, hogy az adatbázis-rendszergazda feltöltse az SQL Server által támogatott új külső nyelvi futtatókörnyezetekhez és operációs rendszerekhez szükséges összetevőket.

Megjegyzés:

Az SQL Server 2017 -ben (14.x) az R nyelv és a Windows platform támogatott. A Windows és Linux platformokon futó R, Python és külső nyelvek támogatottak az SQL Server 2019 (15.x) és újabb verzióiban.

Az SQL Server 2019 szintaxisa

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

A példányra feltöltött kódtárak lehetnek nyilvánosak vagy privátak. Ha a tárat egy tagja dbohozza létre, a tár nyilvános, és az összes felhasználóval megosztható. Ellenkező esetben a tár csak az adott felhasználó számára privát.

A kódtárneveknek egyedinek kell lenniük egy adott felhasználó vagy tulajdonos kontextusában. Például két felhasználó RUser1 , és RUser2 egyenként és külön is feltöltheti az R-kódtár ggplot2-t. Ha RUser1 azonban a ggplot2 újabb verzióját szeretné feltölteni, a második példányt másként kell elnevezni, vagy a meglévő kódtárat kell lecserélni.

A kódtárnevek nem rendelhetők hozzá tetszőlegesen; az erőforrástár nevének meg kell egyeznie a külső szkriptben az erőforrástár betöltéséhez szükséges névvel.

OWNER_NAME

Megadja annak a felhasználónak vagy szerepkörnek a nevét, aki a külső tár tulajdonosa. Ha nincs megadva, a tulajdonjog az aktuális felhasználónak lesz megadva.

Az adatbázis tulajdonosa által birtokolt kódtárak globálisnak minősülnek az adatbázis és a futtatókörnyezet számára. Más szóval az adatbázis-tulajdonosok olyan kódtárakat hozhatnak létre, amelyek sok felhasználó által megosztott kódtárakat vagy csomagokat tartalmaznak. Ha a felhasználótól dbo eltérő felhasználó hoz létre külső tárat, a külső tár csak az adott felhasználó számára privát.

Amikor a felhasználó RUser1 végrehajt egy külső szkriptet, az érték libPath több elérési utat is tartalmazhat. Az első elérési út mindig az adatbázis tulajdonosa által létrehozott megosztott tár elérési útja. A második rész libPath megadja az egyénileg RUser1feltöltött csomagokat tartalmazó elérési utat.

FILE_SPEC

Egy adott platform csomagjának tartalmát adja meg. Platformonként csak egy fájlösszetevő támogatott.

A fájl megadható helyi vagy hálózati elérési út formájában.

A megadott <client_library_specifier>fájl elérésekor az SQL Server megszemélyesíti az aktuális Windows-bejelentkezés biztonsági környezetét. Ha <client_library_specifier> hálózati helyet (UNC-elérési utat) ad meg, az aktuális bejelentkezés megszemélyesítése nem lesz továbbítva a hálózati helyre a delegálási korlátozások miatt. Ebben az esetben a hozzáférés az SQL Server szolgáltatásfiók biztonsági környezetével történik. További információ: Hitelesítő adatok (adatbázismotor).

Opcionálisan meg lehet adni egy operációsrendszer-platformot a fájlhoz. Egy adott nyelvhez vagy futtatókörnyezethez minden operációsrendszer-platformon csak egy fájlösszetevő vagy -tartalom engedélyezett.

LIBRARY_BITS

A csomag tartalmát hexa literálként adja meg, a szerelvényekhez hasonlóan.

Ez a beállítás akkor hasznos, ha tárat kell létrehoznia, vagy módosítania kell egy meglévő tárat (és ehhez rendelkeznie kell a szükséges engedélyekkel), de a kiszolgálón lévő fájlrendszer korlátozott, és nem másolhatja a tárfájlokat olyan helyre, amelyhez a kiszolgáló hozzáférhet.

PLATFORM

Megadja a tár tartalmának platformját. Az érték alapértelmezés szerint azon a gazdagépplatformon van, amelyen az SQL Server fut. Ezért a felhasználónak nem kell megadnia az értéket. Ez akkor szükséges, ha több platform támogatott, vagy ha a felhasználónak másik platformot kell megadnia. Az SQL Server 2019 -ben (15.x) a Windows és a Linux a támogatott platformok.

LANGUAGE

Megadja a csomag nyelvét. Az érték lehet R, Pythonvagy egy külső nyelv neve (lásd: CREATE EXTERNAL LANGUAGE).

Megjegyzések

Az R nyelv esetében a fájl használatakor a csomagokat tömörített archív fájlok formájában kell elkészíteni a .zip kiterjesztéssel.

A Python nyelvhez a csomagot .whl tömörített archív fájl formájában kell előkészíteni egy fájlban vagy .zip fájlban. Ha a csomag már fájl .zip , akkor azt egy új .zip fájlban kell szerepeltetni. A csomagok .whl.zip közvetlen feltöltése jelenleg nem támogatott.

Az CREATE EXTERNAL LIBRARY utasítás feltölti a kódtár biteit az adatbázisba. A kódtár akkor lesz telepítve, ha egy felhasználó egy külső szkriptet futtat sp_execute_external_script használatával, és meghívja a csomagot vagy a tárat.

A példányra feltöltött kódtárak lehetnek nyilvánosak vagy privátak. Ha a tárat egy tagja dbohozza létre, a tár nyilvános, és az összes felhasználóval megosztható. Ellenkező esetben a tár csak az adott felhasználó számára privát.

Egy SQL-példányban számos csomag , más néven rendszercsomagok vannak előre telepítve. Rendszercsomagok nem vehetők fel, nem frissíthetők és nem távolíthatók el.

Permissions

CREATE EXTERNAL LIBRARY Engedélyre van szükség. Alapértelmezés szerint minden olyan felhasználó, aki dbo-tal rendelkezik, aki tagja a db_owner szerepkörnek, jogosult külső tár létrehozására. Minden más felhasználó számára explicit módon engedélyt kell adnia nekik egy GRANT utasítással, amely a jogosultságot adja meg CREATE EXTERNAL LIBRARY .

Az SQL Server 2019 -ben (15.x) az engedélyen kívül CREATE EXTERNAL LIBRARY a felhasználónak külső nyelvre is szüksége van a külső kódtárak létrehozásához.

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

A kódtárak módosításához külön engedély szükséges. ALTER ANY EXTERNAL LIBRARY

Ha egy fájl elérési útján szeretne külső tárat létrehozni, a felhasználónak Windows által hitelesített bejelentkezésnek vagy a sysadmin rögzített kiszolgálói szerepkör tagjának kell lennie.

Példák

Külső tár hozzáadása adatbázishoz

Az alábbi példa egy külső kódtárat ad customPackage hozzá egy adatbázishoz.

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

Miután sikeresen feltöltötte a tárat a példányra, a felhasználó végrehajtja az sp_execute_external_script eljárást a kódtár telepítéséhez.

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

Az SQL Server 2019 Python-nyelve (15.x) esetében a példa a következőre 'Python'való lecseréléssel 'R' is működik: .

Csomagok telepítése függőségekkel

Ha a telepíteni kívánt csomag függőségekkel rendelkezik, fontos, hogy az első és a második szintű függőségeket is elemezze, és győződjön meg arról, hogy az összes szükséges csomag elérhető a célcsomag telepítése előtt .

Tegyük fel például, hogy új csomagot szeretne telepíteni: packageA

• packageA függősége van a packageB
• packageB függősége van a packageC

A sikeres telepítéshez packageAkódtárakat kell létrehoznia az SQL Serverhez packageB való hozzáadáskor packageC és packageA azzal egy időben. Ellenőrizze a szükséges csomagverziókat is.

A gyakorlatban a népszerű csomagok csomagfüggőségei bonyolultabbak, mint ez a példa. Előfordulhat például, hogy a ggplot2 több mint 30 csomagot igényel, és ezekhez a csomagokhoz további csomagokra lehet szükség, amelyek nem érhetők el a kiszolgálón. A hiányzó csomagok vagy a nem megfelelő csomagverziók a telepítés sikertelenségéhez vezethetnek.

Mivel nehéz lehet meghatározni az összes függőséget csak a csomagjegyzék megtekintéséből, használjon egy csomagot, például a miniCRAN-t a sikeres telepítéshez szükséges összes csomag azonosításához.

• Töltse fel a célcsomagot és annak függőségeit. Minden fájlnak a kiszolgáló számára elérhető mappában kell lennie.

  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
  

• Először telepítse a szükséges csomagokat.

  Ha egy szükséges csomag már fel lett töltve a példányra, nem kell újból hozzáadnia. Csak ellenőrizze, hogy a meglévő csomag a megfelelő verzió-e.

  A szükséges csomagok packageC , és packageB a megfelelő sorrendben vannak telepítve, amikor sp_execute_external_script először fut a csomag packageAtelepítéséhez.

  Ha azonban valamelyik szükséges csomag nem érhető el, a célcsomag packageA telepítése meghiúsul.

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

Az SQL Server 2019 Python-nyelve (15.x) esetében a példa a következőre 'Python'való lecseréléssel 'R' is működik: .

Tár létrehozása bájtfolyamból

Ha nem tudja menteni a csomagfájlokat a kiszolgáló egyik helyére, a csomag tartalmát átadhatja egy változóban. Az alábbi példa egy kódtárat hoz létre úgy, hogy hexadecimális literálként adja át a biteket.

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

Az SQL Server 2019 Python-nyelve (15.x) esetében a példa a következőre Pythonvaló lecseréléssel R is működik: .

Megjegyzés:

Ez a kódminta csak a szintaxist mutatja be; a bináris érték csonkolva CONTENT = van az olvashatóság érdekében, és nem hoz létre működő kódtárat. A bináris változó tényleges tartalma hosszabb.

Meglévő csomagtár módosítása

A ALTER EXTERNAL LIBRARY DDL-utasítás használható új tártartalom hozzáadására vagy meglévő tártartalom módosítására. Meglévő kódtár módosításához engedély ALTER ANY EXTERNAL LIBRARY szükséges.

További információ: ALTER EXTERNAL LIBRARY.

Java-.jar-fájl hozzáadása adatbázishoz

Az alábbi példa egy külső .jar , adatbázishoz hívott customJar fájlt ad hozzá.

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

Miután sikeresen feltöltötte a tárat a példányra, a felhasználó végrehajtja az sp_execute_external_script eljárást a kódtár telepítéséhez.

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

Külső csomag hozzáadása Windowshoz és Linuxhoz egyaránt

Legfeljebb két <file_spec>, egy Windows és egy Linux rendszerhez használható lehetőséget adhat meg.

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

A sp_execute_external_script csomag telepítésekor attól függően, hogy az SQL Server-példány melyik platformon fut, a rendszer az adott platform kódtár-tartalmát használja.

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

Kapcsolódó tartalom

• KÜLSŐ KÓDTÁR MÓDOSÍTÁSA (Transact-SQL)
• DROP EXTERNAL LIBRARY (Transact-SQL)
• sys.external_library_files
• sys.external_libraries