CREATE LIBRARY

Loads a library containing user-defined extensions (UDxs) into the Vertica catalog. Vertica automatically distributes copies of the library file and supporting libraries to all cluster nodes.

Because libraries are added to the database catalog, they persist across database restarts.

After loading a library in the catalog, you can use statements such as CREATE FUNCTION to define the extensions contained in the library. See Developing User-Defined Extensions (UDxs) for details.

Syntax

CREATE [OR REPLACE] LIBRARY 
    [[database.]schema.]name 
    AS 'path'
    [ DEPENDS 'depends-path' ]
    [ LANGUAGE 'language' ]

Arguments

`OR REPLACE`	If a library with the same name exists, replace it. UDxs defined in the catalog that reference the updated library automatically start using the new library file. If you do not use this directive and the library already exists, the CREATE statement returns with an error.
`[database.]schema`	Database and schema. The default schema is `public`. If you specify a database, it must be the current database.
name	Name of the library to create. This is the name used when creating functions in the library (see Creating UDx Functions). While not required, it is good practice to match the file name.
`AS path`	The absolute path on the initiator node file system of the library to load.
`DEPENDS 'depends-path'`	Files or libraries on which this library depends. The value is one or more absolute paths to these dependencies on the initiator node. DEPENDS is ignored for libraries written in R, because R packages must be installed locally on each node, including external dependencies. DEPENDS can specify multiple support paths as follows: Separate multiple paths with colons (:). For example: => CREATE LIBRARY mylib AS '/path/to/java_udx' DEPENDS '/path/to/jars/this.jar:/path/to/jars/that.jar' LANGUAGE 'Java'; Specify a directory that contains multiple libraries with a trailing slash (`/`), optionally followed by a wildcard (``). For example, the following DEPENDS clauses are identical: DEPENDS '/home/mydir/mylibs/' DEPENDS '/home/mydir/mylibs/' DEPENDS can specify libraries with multiple directory levels. For details, see Multi-level Library Dependencies. The performance of CREATE LIBRARY is liable to degrade in Eon Mode, in proportion to the number and depth of dependencies specified by the DEPENDS clause. If a Java library depends on native libraries (SO files), use DEPENDS to specify the path and call `System.loadLibrary()` in your UDx to load the native libraries from that path.
`LANGUAGE 'language'`	The programming language used to develop the function, one of the following: `C++` (default) `Python` `Java` `R`

Privileges

Superuser, or UDXDEVELOPER and CREATE on the schema. Non-superusers must explicitly enable the UDXDEVELOPER role, as in the following example:

=> SET ROLE UDXDEVELOPER;
SET

-- Not required, but you can confirm the role as follows:
=> SHOW ENABLED ROLES;
     name      |   setting   
---------------+--------------
 enabled roles | udxdeveloper
(1 row)	
				
=> CREATE LIBRARY MyLib AS '/home/dbadmin/my_lib.so';
CREATE LIBRARY

-- Create functions...

-- UDXDEVELOPER also grants DROP (replace):				
=> CREATE OR REPLACE LIBRARY MyLib AS '/home/dbadmin/my_lib.so';

Requirements

Vertica makes its own copies of the library files. Later modification or deletion of the original files specified in the statement does not affect the library defined in the catalog. To update the library, use ALTER LIBRARY.
Loading a library does not guarantee that it functions correctly. CREATE LIBRARY performs some basic checks on the library file to verify it is compatible with Vertica. The statement fails if it detects that the library was not correctly compiled or it finds other basic incompatibilities. However, CREATE LIBRARY cannot detect many other issues in shared libraries.

Multi-level Library Dependencies

If a DEPENDS clause specifies a library with multiple directory levels, Vertica follows the library path to include all subdirectories of that library. For example, the following CREATE LIBRARY statement enables the UDx library mylib to import all Python packages and modules that it finds in subdirectories of site‑packages:

=> CREATE LIBRARY mylib AS '/path/to/python_udx' DEPENDS '/path/to/python/site-packages' LANGUAGE 'Python';

DEPENDS can specify Java library dependencies that are up to 100 levels deep.

Examples

Load the MyFunctions library in the home directory of the dbadmin account:

=> CREATE LIBRARY MyFunctions AS '/home/dbadmin/my_functions.so';

Load the MyOtherFunctions library located in the directory where you started vsql:

=> \set libfile '\''`pwd`'/MyOtherFunctions.so\'';
=> CREATE LIBRARY MyOtherFunctions AS :libfile;

Load a Java library named JavaLib.jar that depends on multiple JAR files in the /home/dbamin/mylibs subdirectory:

=> CREATE LIBRARY DeleteVowelsLib AS '/home/dbadmin/JavaLib.jar' 
   DEPENDS '/home/dbadmin/mylibs/*' LANGUAGE 'JAVA';