PostgresAdapter、PostGIS 和 GreenPlum

PostgresAdapter 模块从基于 PostresSQL 的数据库中读取数据，并生成包含解析数据的 NumPy 数组或 Pandas 数据帧。PostgresAdapter 可用于访问来自 PostgresSQL 和 GreenPlum 的数据，并具有支持 PostGIS 点、线、多线、多边形和多边形的增强功能。目前实现了以下功能：

  • PostgresAdapter 引擎是用 C 语言编写的，以确保在从源中读取数据的同时解析返回的数据。数据以小块的形式读取和解析，而不是一次将整个数据读入内存。
  • Python 切片符号可用于指定要从数据源读取的记录子集。
  • 可以指定返回列的子集，而不是返回记录的所有列。

适配器方法

PostgreSQL 适配器构造函数：

PostgresAdapter (connection_uri, table=None, query=None, field_filter=None, dataframe=False, field_names=None, field_types=None, field_shapes=None):

创建用于连接到基于 PostgreSQL 的数据库的适配器。
connection_uri：描述如何连接到数据库的字符串URI
table：字符串，要从中读取记录的表的名称。只有表
可以设置参数或查询参数，但不能同时设置。
查询：字符串，用于读取记录的自定义查询。只能设置查询参数或表参数，不能同时设置。设置查询参数时不能设置 field_filter 参数（因为在查询字符串中指定字段很简单）。
field_filter：查询中包含的字段名称（仅在指定表参数时有效）
数据帧：bool，将结果作为数据帧而不是数组返回
field_names：列表，输出数组或数据帧中的字段名称。默认为数据库表列名。
field_types：列表，输出数组或数据帧中每个字段的 NumPy dtype。默认为数据库表列类型。
field_shapes：列表，具有可变长度数据的几何字段类型的每个字段值的形状。例如，对于具有 2d 点的 'path' 数据库列，路径的点将默认存储在列表对象中。如果指定了“10”的字段形状，则点将存储在 2x10 浮点子数组中（每点 2 个浮点数*最多 10 个点）。应为诸如 multipolygon 之类的类型指定 (x,y) 形式的字段形状，其中 x 是多边形的最大数量，y 是每个多边形的最大长度（推断点的大小）。
关闭()
关闭与数据库的连接。

PostgresAdapter 对象支持数组切片：

读取所有记录：adapter[:]
读取前 100 条记录：adapter[0:100]
读取最后一条记录：adapter[-1]
读取所有其他记录：adapter[::2]

适配器属性

num_records（只读）
获取将从表或自定义查询返回的记录数。
num_fields（只读）
获取将从表或自定义查询返回的记录中的字段数
字段名称
获取/设置最终数组或数据帧中字段的名称。可以通过指定名称列表或字段编号到字段名称的字典映射来设置字段名称。如果名称是列表，则列表的长度必须与数据集中的字段数匹配。如果 names 是一个 dict，如果没有为该字段指定 dict 中的名称，则将使用数据库中的字段名称。
字段类型
获取/设置最终数组或数据帧中的字段类型。可以通过指定 NumPy dtype 列表或字段编号或名称到字段类型的字典映射来设置字段类型。如果 types 是列表，则列表的长度必须与数据集中的字段数匹配。如果 types 是 dict，如果 type 未在 dict 中指定，则将使用数据库中的字段类型。
字段形状
获取/设置可变长度字段的字段形状。字段形状可以通过指定形状元组列表（或单个整数，如果形状具有一维）或字段编号或名称到字段形状的字典映射来设置。如果 shape 是一个列表，则列表的长度必须与数据集中的字段数相匹配。字段的值 None 或零，或未指定的形状，意味着字段将允许无限长度值，如果字段是 PostgreSQL 几何类型，则值将存储在 Python 列表对象中，或作为众所周知的文本字符串对象如果字段是 PostGIS 类型。

基本用法

为数据源创建 PostgresAdapter 对象：

>>> import iopro
>>> adapter = iopro.PostgresAdapter('host=localhost dbname=db_name user=user table=table_name')

IOPro 适配器使用切片来检索数据。要从表或查询中检索记录，可以使用标准的 NumPy 切片符号：

>>> # read all records
>>> array = adapter[:]

>>> # read first ten records
>>> array = adapter[0:10]

>>> # read last record
>>> array = adapter[-1]

>>> # read every other record
>>> array = adapter[::2]

PostgreSQL 适配器有一些属性，我们可以使用它们来了解有关我们数据的更多信息。要获取数据集中的记录数：

>>> adapter.num_records
5

或字段数：

>>> adapter.num_fields
5

要查找每个字段的名称：

>>> adapter.field_names
['field1', 'real', 'name', 'point2d', 'multipoint3d']

这些名称来自数据库中列的名称，默认情况下用于 NumPy 数组结果中的字段名称。可以通过使用字段名称列表设置字段名称属性来更改这些名称：

>>> adapter.field_names = ['field1', 'field2', 'field3', 'field4', 'field5']
>>> adapter[:].dtype
dtype([('field1', '<i4'), ('field2', '<f4'), ('field3', '<U10'), ('field4', '<f8', (2,)), ('field5', 'O')])

单个字段也可以使用dict来设置，其中key是字段编号，value是我们想要的字段名：

>>> adapter.field_names = {1: 'AAA'}
>>> adapter[:].dtype
dtype([('integer', '<i4'), ('AAA', '<f4'), ('string', '<U10'), ('point2d', '<f8', (2,)), ('multipoint3d', 'O')])

要找出每个字段的 NumPy dtype：

>>> adapter.field_types
['i4', 'f4', 'U10', 'f8', 'O']

与字段名称属性类似，可以使用列表或字典设置 types 属性以强制将字段强制转换为特定类型：

>>> adapter.field_types = {0: 'f4', 1: 'i4', 2: 'U3', 4: 'O'}

通过将字段名称列表传递给构造函数来过滤返回的字段：

>>> adapter = iopro.PostgresAdapter('host=localhost dbname=db_name user=user',
                                     table='data',
                                     field_filter=['field1', 'field2'])

对于具有可变长度的 path 或 multipoint3d 等字段，适配器将返回值作为包含每个点的浮点组件的元组列表（如果是 PostgreSQL 几何类型）或作为众所周知的文本格式的字符串对象（如果是 PostGIS 类型） . 为了提高性能，可以指定一个字段形状，这将设置字段值的最大维度。例如，可以将 multipoint3d 字段设置为最多两个点，以便每组 3d 点将存储在 2x3 浮点子数组中：

>>> adapter = iopro.PostgresAdapter('host=localhost dbname=db_name user=user'
                                    table='data',
                                    field_filter=['multipoint3d'],
                                    field_shapes={'multipoint3d': 2})
>>> adapter[:]
array([([[0.0, 1.0, 2.0], [3.0, 4.0, 5.0]],),
       ([[6.0, 7.0, 8.0], [9.0, 10.0, 11.0]],),
       ([[12.0, 13.0, 14.0], [15.0, 16.0, 17.0]],),
       ([[18.0, 19.0, 20.0], [21.0, 22.0, 23.0]],),
       ([[24.0, 25.0, 26.0], [27.0, 28.0, 29.0]],)],
      dtype=[('multipoint3d', '<f8', (2, 3))])

对于更高级的查询，可以将自定义选择查询传递给构造函数。可以将表名或自定义查询传递给构造函数，但不能同时传递两者。

>>> adapter = iopro.PostgresAdapter('host=localhost dbname=db_name user=user',
                                     query='select integer, string from data where data.integer > 2')
>>> adapter[:]

数据也可以使用适配器构造函数的 dataframe' 参数作为 pandas 数据帧返回：

>>> adapter = iopro.PostgresAdapter('host=localhost dbname=iopro_tutorial user=jayvius',
                                    table='data',
                                    dataframe=True)

要检索位于给定边界框内的某些 PostGIS 数据：

>>> adapter = iopro.PostgresAdapter('host=localhost dbname=db_name user=user',
                                    query='select integer, point2d from data '
                                          'where data.point2d @ ST_MakeEnvelope(0, 0, 4, 4)')
关闭数据库连接：
>>> adapter.close()