选择 打开 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。

受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
测试与开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0
历史版本PostgreSQL 9.1 已于 2016 年 10 月结束社区维护,本页译文保留供仍在使用旧版本的读者参考。新系统请看当前版本

42.3. 数据值 #

一般来说,PL/Python 的目标是在 PostgreSQL 世界和 Python 世界之间提供一种自然的映射。下面描述的数据映射规则就是基于这一目标。

42.3.1. 数据类型映射

函数参数会被从其 PostgreSQL 类型转换为对应的 Python 类型:

  • PostgreSQL 的 boolean 被转换为 Python 的 bool

  • PostgreSQL 的 smallintint 被转换为 Python 的 int。PostgreSQL 的 bigint 在 Python 2 中被转换为 long,在 Python 3 中被转换为 int

  • PostgreSQL 的 realdoublenumeric 被转换为 Python 的 float。注意对于 numeric 这会丢失信息并可能导致不正确的结果。这一点可能会在将来的版本中修复。

  • PostgreSQL 的 bytea 在 Python 2 中被转换为 str,在 Python 3 中被转换为 bytes。在 Python 2 中,该字符串应当被当作没有任何字符编码的字节序列。

  • 所有其他数据类型,包括 PostgreSQL 的字符串类型,都被转换为 Python 的 str。在 Python 2 中,该字符串将采用 PostgreSQL 服务器编码;在 Python 3 中,它将和所有字符串一样是 Unicode 字符串。

  • 对于非标量数据类型,请参见下文。

函数返回值会按如下方式转换为声明的 PostgreSQL 返回数据类型:

  • 当 PostgreSQL 返回类型为boolean时,返回值会按照Python规则进行真值判定。也就是说,0 和空字符串为假,但值得注意的是,'f' 为真。

  • 如果 PostgreSQL 返回类型是 bytea,会先使用相应的 Python 内置函数,将返回值转换为字符串(Python 2)或 bytes(Python 3),再将结果转换为 bytea

  • 对于所有其他 PostgreSQL 返回类型,返回值会使用 Python 内置函数str转换为字符串,然后将结果传给 PostgreSQL 数据类型的输入函数。

    Python 2 中的字符串传给 PostgreSQL 时,必须采用 PostgreSQL 服务器编码。 在当前服务器编码中无效的字符串会引发错误,但并非所有编码不匹配都能被检测到, 因此处理不当仍可能产生乱码数据。Unicode 字符串会自动转换为正确的编码, 因而使用它们可能更安全、更方便。在 Python 3 中,所有字符串都是 Unicode 字符串。

  • 对于非标量数据类型,请参见下文。

请注意,即使声明的 PostgreSQL 返回类型与实际返回对象的 Python 数据类型在逻辑上并不匹配,也不会报错;无论如何该值都会被转换。

42.3.2. 空值、None

如果将 SQL 空值传递给函数,该参数值在 Python 中会表现为 None。例如,函数 pymax 的定义(见 第 42.2 节)对空值输入会返回错误结果。可以在函数定义中添加 STRICT,让 PostgreSQL 采取更合理的行为:如果传入空值,就完全不调用函数,而是自动返回空值结果。也可以在函数体中检查空值输入:

CREATE FUNCTION pymax (a integer, b integer)
  RETURNS integer
AS $$
  if (a is None) or (b is None):
    return None
  if a > b:
    return a
  return b
$$ LANGUAGE plpythonu;

如上所示,要从 PL/Python 函数返回 SQL 空值,只需返回 None。无论函数是否严格,都可以这样做。

42.3.3. 数组、列表 #

SQL 数组值会作为 Python 列表传入 PL/Python。要从 PL/Python 函数返回 SQL 数组值,请返回一个 Python 序列,例如列表或元组:

CREATE FUNCTION return_arr()
  RETURNS int[]
AS $$
return (1, 2, 3, 4, 5)
$$ LANGUAGE plpythonu;

SELECT return_arr();
 return_arr
-------------
 {1,2,3,4,5}
(1 row)

请注意,在 Python 中,字符串也是序列,这可能会带来一些 Python 程序员熟悉但并不理想的效果:

CREATE FUNCTION return_str_arr()
  RETURNS varchar[]
AS $$
return "hello"
$$ LANGUAGE plpythonu;

SELECT return_str_arr();
 return_str_arr
----------------
 {h,e,l,l,o}
(1 row)

42.3.4. 复合类型

复合类型参数会以 Python 映射的形式传给函数。映射中的元素名就是复合类型的属性名。如果传入行中的某个属性为空值,那么它在映射中的值就是None。例如:

CREATE TABLE employee (
  name text,
  salary integer,
  age integer
);

CREATE FUNCTION overpaid (e employee)
  RETURNS boolean
AS $$
  if e["salary"] > 200000:
    return True
  if (e["age"] < 30) and (e["salary"] > 100000):
    return True
  return False
$$ LANGUAGE plpythonu;

有多种方法可以从 Python 函数返回行类型或复合类型。以下示例假定我们有:

CREATE TYPE named_value AS (
  name   text,
  value  integer
);

复合结果可以按以下形式返回:

序列类型(元组或列表,但不能是集合,因为集合不可通过索引访问)

返回的序列对象,其项目数必须与复合结果类型的字段数相同。索引 0 的项目赋给复合类型的第一个字段,索引 1 的项目赋给第二个字段,依此类推。例如:

CREATE FUNCTION make_pair (name text, value integer)
  RETURNS named_value
AS $$
  return [ name, value ]
  # 也可以使用元组: return ( name, value )
$$ LANGUAGE plpythonu;

要为某一列返回 SQL 空值,请将 None 放在对应位置。

映射(字典)

结果类型中每一列的值,都使用列名作为键从映射中取得。例如:

CREATE FUNCTION make_pair (name text, value integer)
  RETURNS named_value
AS $$
  return { "name": name, "value": value }
$$ LANGUAGE plpythonu;

字典中多余的键值对会被忽略,缺少键则会被视为错误。要为某一列返回 SQL 空值,请插入 None,并以对应列名为键。

对象(提供方法__getattr__的任何对象)

其工作方式与映射相同。例如:

CREATE FUNCTION make_pair (name text, value integer)
  RETURNS named_value
AS $$
  class named_value:
    def __init__ (self, n, v):
      self.name = n
      self.value = v
  return named_value(name, value)

  # 或者简写为
  class nv: pass
  nv.name = name
  nv.value = value
  return nv
$$ LANGUAGE plpythonu;

也支持带OUT参数的函数。例如:

CREATE FUNCTION multiout_simple(OUT i integer, OUT j integer) AS $$
return (1, 2)
$$ LANGUAGE plpythonu;

SELECT * FROM multiout_simple();

42.3.5. 集合返回函数

PL/Python函数也可以返回标量类型或复合类型的集合。实现方式有多种,因为返回的对象在内部会被转换成一个迭代器。以下示例假定我们有如下复合类型:

CREATE TYPE greeting AS (
  how text,
  who text
);

集合结果可以通过以下对象返回:

序列类型(元组、列表、集合)
CREATE FUNCTION greet (how text)
  RETURNS SETOF greeting
AS $$
  # 返回包含列表的元组,以列表表示复合类型
  # 其他组合方式也都可用
  return ( [ how, "World" ], [ how, "PostgreSQL" ], [ how, "PL/Python" ] )
$$ LANGUAGE plpythonu;
迭代器(任何提供 __iter__next 方法的对象)
CREATE FUNCTION greet (how text)
  RETURNS SETOF greeting
AS $$
  class producer:
    def __init__ (self, how, who):
      self.how = how
      self.who = who
      self.ndx = -1

    def __iter__ (self):
      return self

    def next (self):
      self.ndx += 1
      if self.ndx == len(self.who):
        raise StopIteration
      return ( self.how, self.who[self.ndx] )

  return producer(how, [ "World", "PostgreSQL", "PL/Python" ])
$$ LANGUAGE plpythonu;
生成器(yield
CREATE FUNCTION greet (how text)
  RETURNS SETOF greeting
AS $$
  for who in [ "World", "PostgreSQL", "PL/Python" ]:
    yield ( how, who )
$$ LANGUAGE plpythonu;

警告

由于 Python 的缺陷 #1483133, 某些调试版本的 Python 2.4(以--with-pydebug选项配置并编译) 在使用迭代器返回集合结果时会导致PostgreSQL服务器崩溃。 未打补丁的 Fedora 4 就包含此缺陷。在 Python 的正式版本或已打补丁的 Fedora 4 中不会发生这种情况。

也支持带OUT参数的集合返回函数(使用RETURNS SETOF record)。例如:

CREATE FUNCTION multiout_simple_setof(n integer, OUT integer, OUT integer) RETURNS SETOF record AS $$
return [(1, 2)] * n
$$ LANGUAGE plpythonu;

SELECT * FROM multiout_simple_setof(3);

提交更正

译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。