CREATE LIBRARY

Installs a Python library, which is available for users to incorporate when creating a user-defined function (UDF) with the CREATE FUNCTION command. The total size of user-installed libraries can't exceed 100 MB.

CREATE LIBRARY can't be run inside a transaction block (BEGIN … END). For more information about transactions, see Serializable isolation.

Amazon Redshift supports Python version 2.7. For more information, see www.python.org.

For more information, see Example: Importing custom Python library modules.

Required privileges

Following are required privileges for CREATE LIBRARY:

• Superuser

• Users with the CREATE LIBRARY privilege or with the privilege of the specified language

Syntax

CREATE [ OR REPLACE ] LIBRARY library_name LANGUAGE plpythonu
FROM
{ 'https://file_url'
| 's3://bucketname/file_name'
authorization
  [ REGION [AS] 'aws_region']
  IAM_ROLE { default | ‘arn:aws:iam::<AWS account-id>:role/<role-name>’ }
}

Parameters

OR REPLACE

Specifies that if a library with the same name as this one already exists, the existing library is replaced. REPLACE commits immediately. If a UDF that depends on the library is running concurrently, the UDF might fail or return unexpected results, even if the UDF is running within a transaction. You must be the owner or a superuser to replace a library.

library_name

The name of the library to be installed. You can't create a library that contains a module with the same name as a Python Standard Library module or an Amazon Redshift preinstalled Python module. If an existing user-installed library uses the same Python package as the library to be installed, you must drop the existing library before installing the new library. For more information, see Python language support for UDFs.

LANGUAGE plpythonu

The language to use. Python (plpythonu) is the only supported language. Amazon Redshift supports Python version 2.7. For more information, see www.python.org.

FROM

The location of the library file. You can specify an Amazon S3 bucket and object name, or you can specify a URL to download the file from a public website. The library must be packaged in the form of a .zip file. For more information, see Building and Installing Python Modules in the Python documentation.

https://file_url

The URL to download the file from a public website. The URL can contain up to three redirects. The following is an example of a file URL.

'https://www.example.com/pylib.zip'

s3://bucket_name/file_name

The path to a single Amazon S3 object that contains the library file. The following is an example of an Amazon S3 object path.

's3://amzn-s3-demo-bucket/my-pylib.zip'

If you specify an Amazon S3 bucket, you must also provide credentials for an AWS user that has permission to download the file.

Important

If the Amazon S3 bucket doesn't reside in the same AWS Region as your Amazon Redshift cluster, you must use the REGION option to specify the AWS Region in which the data is located. The value for aws_region must match an AWS Region listed in the table in the REGION parameter description for the COPY command.

authorization

A clause that indicates the method your cluster uses for authentication and authorization to access the Amazon S3 bucket that contains the library file. Your cluster must have permission to access the Amazon S3 with the LIST and GET actions.

The syntax for authorization is the same as for the COPY command authorization. For more information, see Authorization parameters.

IAM_ROLE { default | ‘arn:aws:iam::<AWS account-id>:role/<role-name>’

Use the default keyword to have Amazon Redshift use the IAM role that is set as default and associated with the cluster when the CREATE LIBRARY command runs.

Use the Amazon Resource Name (ARN) for an IAM role that your cluster uses for authentication and authorization. If you specify IAM_ROLE, you can't use ACCESS_KEY_ID and SECRET_ACCESS_KEY, SESSION_TOKEN, or CREDENTIALS.

Optionally, if the Amazon S3 bucket uses server-side encryption, provide the encryption key in the credentials-args string. If you use temporary security credentials, provide the temporary token in the credentials-args string.

For more information, see Temporary security credentials.

REGION [AS] aws_region

The AWS Region where the Amazon S3 bucket is located. REGION is required when the Amazon S3 bucket isn't in the same AWS Region as the Amazon Redshift cluster. The value for aws_region must match an AWS Region listed in the table in the REGION parameter description for the COPY command.

By default, CREATE LIBRARY assumes that the Amazon S3 bucket is located in the same AWS Region as the Amazon Redshift cluster.

Examples

The following two examples install the urlparse Python module, which is packaged in a file named urlparse3-1.0.3.zip.

The following command installs a UDF library named f_urlparse from a package that has been uploaded to an Amazon S3 bucket located in the US East Region.

create library f_urlparse
language plpythonu
from 's3://amzn-s3-demo-bucket/urlparse3-1.0.3.zip'
credentials 'aws_iam_role=arn:aws:iam::<aws-account-id>:role/<role-name>'
region as 'us-east-1';  

The following example installs a library named f_urlparse from a library file on a website.

create library f_urlparse
language plpythonu
from 'https://example.com/packages/urlparse3-1.0.3.zip';