PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

CREATE TRANSFORM

CREATE TRANSFORM — 定义一个新的转换

Synopsis

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 会创建一个新的转换,或者替换一个现有的定义。

转换指定如何把一种数据类型适配到一种过程语言。例如,在 PL/Python 中使用 hstore 类型编写函数时,PL/Python 事先并不知道如何在 Python 环境中表示 hstore 值。语言实现通常默认使用文本表示,但在关联数组或列表更为合适的情况下,这就会很不方便。

一种转换指定两个函数:

  • 一个 “from 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 TRANSFORM 是 PostgreSQL 的扩展。CREATE TRANSFORM 命令也存在于 SQL 标准中,但它是用于把数据类型适配到客户端语言的。PostgreSQL 不支持那种用法。

另请参阅

CREATE FUNCTION, CREATE LANGUAGE, CREATE TYPE, DROP TRANSFORM