2025年9月25日: PostgreSQL 18 发布!
支持的版本: 当前 (18) / 17 / 16 / 15 / 14 / 13
开发版本: devel
不支持的版本: 12 / 11 / 10 / 9.6 / 9.5

CREATE TRANSFORM

CREATE TRANSFORM — 定义一个新的转换

概要

CREATE [ OR REPLACE ] TRANSFORM FOR type_name LANGUAGE lang_name (
    FROM SQL WITH FUNCTION from_sql_function_name [ (argument_type [, ...]) ],
    TO SQL WITH FUNCTION to_sql_function_name [ (argument_type [, ...]) ]
);

描述

CREATE TRANSFORM 定义了一个新的转换。 CREATE OR REPLACE TRANSFORM 将会创建新转换,或替换现有定义。

转换指定了如何将一个数据类型适配到过程语言。例如,当使用 hstore 类型在 PL/Python 中编写函数时,PL/Python 并没有预先知道如何在 Python 环境中呈现 hstore 值。语言实现通常默认使用文本表示,但这在例如,使用关联数组或列表会更合适时,会很不方便。

转换指定了两个函数

  • 一个“从 SQL”函数,用于将数据类型从 SQL 环境转换为语言环境。当调用用该语言编写的函数的参数时,将调用此函数。

  • 一个“到 SQL”函数,用于将数据类型从语言环境转换为 SQL 环境。当调用用该语言编写的函数的返回值时,将调用此函数。

不一定需要同时提供这两个函数。如果其中一个未指定,则在必要时将使用特定语言的默认行为。(如果想完全阻止某个方向的转换发生,您也可以编写一个总是出错的转换函数。)

要创建转换,您必须拥有并具有对该类型的 USAGE 权限,对该语言具有 USAGE 权限,以及拥有并具有对 from-SQL 和 to-SQL 函数(如果已指定)的 EXECUTE 权限。

参数

type_name

转换的数据类型的名称。

lang_name

转换的语言的名称。

from_sql_function_name[(argument_type [, ...])]

将数据类型从 SQL 环境转换为语言环境的函数的名称。它必须接受一个 internal 类型的参数,并返回 internal 类型。实际参数将是转换类型的类型,并且函数应按此进行编码。(但是,不允许声明一个返回 internal 且至少带有一个 internal 类型参数的 SQL 级函数。)实际返回值将是语言实现特有的。如果未指定参数列表,则函数名称必须在其模式中是唯一的。

to_sql_function_name[(argument_type [, ...])]

将数据类型从语言环境转换为 SQL 环境的函数的名称。它必须接受一个 internal 类型的参数,并返回转换类型的类型。实际参数值将是语言实现特有的。如果未指定参数列表,则函数名称必须在其模式中是唯一的。

注释

使用 DROP TRANSFORM 来删除转换。

示例

要为 hstore 类型和 plpython3u 语言创建转换,请首先设置类型和语言

CREATE TYPE hstore ...;

CREATE EXTENSION plpython3u;

然后创建必要的函数

CREATE FUNCTION hstore_to_plpython(val internal) RETURNS internal
LANGUAGE C STRICT IMMUTABLE
AS ...;

CREATE FUNCTION plpython_to_hstore(val internal) RETURNS hstore
LANGUAGE C STRICT IMMUTABLE
AS ...;

最后创建转换将它们连接在一起

CREATE TRANSFORM FOR hstore LANGUAGE plpython3u (
    FROM SQL WITH FUNCTION hstore_to_plpython(internal),
    TO SQL WITH FUNCTION plpython_to_hstore(internal)
);

实际上,这些命令将被包装在一个扩展中。

contrib 部分包含一些提供转换的扩展,它们可以作为实际的例子。

兼容性

此形式的 CREATE TRANSFORMPostgreSQL 的一个扩展。在SQLSQL 标准中存在一个 CREATE TRANSFORM 命令,用于将数据类型适配到客户端语言。 PostgreSQL 不支持这种用法。

提交更正

如果您在文档中看到任何不正确、与您对特定功能的使用经验不符或需要进一步澄清的内容,请使用 此表单 来报告文档问题。