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::
<Amazon Web Services 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 Modulesin 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 Amazon user that has permission to download the file.
Important
If the Amazon S3 bucket doesn't reside in the same Amazon Region as your Amazon Redshift cluster, you must use the REGION option to specify the Amazon Region in which the data is located. The value for aws_region must match an Amazon 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::
<Amazon Web Services 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 Amazon Region where the Amazon S3 bucket is located. REGION is required when the Amazon S3 bucket isn't in the same Amazon Region as the Amazon Redshift cluster. The value for aws_region must match an Amazon 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 Amazon Region as the Amazon Redshift cluster.
Examples
The following two examples install the urlparseurlparse3-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';