Vertica Analytics Platform Version 9.2.x Documentation

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. UDxs defined in the catalog that reference the updated library automatically start using the new library file.

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) in Extending Vertica for details.

Syntax

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

Parameters

OR REPLACE

Specifies to replace the current library loaded as library‑name. If omitted, library‑name must be unique in the schema, otherwise the statement returns with an error.

[database.]schema

Specifies a schema, by default public. If schema is any schema other than public, you must supply the schema name. For example:

myschema.thisDbObject

If you specify a database, it must be the current database.

library‑name

A name to assign to this library, where library‑name conforms to conventions described in Identifiers. Use this name in a CREATE FUNCTION statement to enable user defined functions stored in the library.

While not required, it is good practice to match library‑name to the library file name.

AS library‑path

The absolute path on the initiator node file system of the library to load.

DEPENDS 'support‑path'

Indicates that the UDx library depends on one or more files or libraries, where support‑path specifies one or more absolute paths to these dependencies on the initiator node.

DEPENDS is ignored for R, as R packages must be installed locally on each node, including external dependencies.

For example, the following statement specifies a single dependency:

=> CREATE LIBRARY mylib AS '/path/to/java_udx' DEPENDS '/path/to/jar/this.jar' LANGUAGE 'Java';

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 asterisk 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 your 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, where language is one of the following:

  • C++ (default)
  • Python
  • Java
  • R

Privileges

Superuser

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 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 library MyFunctions in the home directory of the dbadmin account:

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

Load library MyOtherFunctions 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 support JAR files in the /home/dbamin/mylibs subdirectory:

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