如何通过Python控制台将PostGIS SQL查询添加为QGIS 3项目图层

问题背景 #

需要通过Python控制台/插件代码，将支持多表连接的PostGIS SELECT查询结果作为新图层加载到QGIS3项目中。常规setDataSource()传入表名+简单过滤条件的写法不支持多表关联等复杂SQL，而DB Manager的SQL窗口可视化加载逻辑可以通过代码复现。

原有加载单表的示例代码：

from qgis.core import QgsVectorLayer, QgsDataSourceUri, QgsProject

uri = QgsDataSourceUri()
uri.setConnection("localhost", "5432", "my_database", "postgres", "password")

uri.setDataSource("public", "my_table", "geom")

vlayer = QgsVectorLayer(uri.uri(), "my_new_layer", "postgres")
QgsProject.instance().addMapLayer(vlayer, True)

目标是将数据源替换为复杂SQL查询，例如下方多表连接逻辑：

SELECT * FROM my_table_1
JOIN my_table_2 ON my_table_1.foreign_key = my_table_2.primary_key;

实现方案 #

QgsDataSourceUri.setDataSource()原生支持传入子查询作为数据源，不需要在数据库中创建实体视图，和DB Manager加载SQL图层的底层逻辑完全一致，适合集成到插件中，具体写法规则：

• schema参数传入空字符串，子查询不需要指定schema
• 表名位置传入用括号包裹的自定义SQL语句，并给子查询设置别名（部分QGIS版本可省略别名，兼容起见建议加上）
• 第三个参数必须明确指定SQL查询返回的几何字段名，禁止模糊查询几何字段
• 第五个参数显式指定查询结果中唯一非空的主键字段，避免图层交互异常
• 自定义SQL语句末尾不要加分号，避免触发语法错误

完整示例代码 #

from qgis.core import QgsVectorLayer, QgsDataSourceUri, QgsProject

# 初始化数据库连接
uri = QgsDataSourceUri()
uri.setConnection("localhost", "5432", "my_database", "postgres", "password")

# 编写自定义复杂查询，必须显式返回几何字段、唯一主键字段
custom_query = """
SELECT 
  t1.id AS layer_id,
  t1.geom,
  t1.attr1,
  t2.attr2
FROM my_table_1 t1
JOIN my_table_2 t2 ON t1.foreign_key = t2.primary_key
"""

# 传入子查询作为数据源：参数顺序为 schema, 子查询, 几何字段名, 过滤条件, 主键字段名
uri.setDataSource(
    "",
    f"({custom_query}) AS query_result",
    "geom",
    "",
    "layer_id"
)

# 初始化图层并校验有效性
vlayer = QgsVectorLayer(uri.uri(), "自定义查询图层", "postgres")
if not vlayer.isValid():
    print(f"图层加载失败：{vlayer.error().message()}")
else:
    QgsProject.instance().addMapLayer(vlayer, True)

注意事项 #

• 自定义SQL中禁止使用SELECT *写法，必须明确列出需要的字段，保证几何字段、主键字段可被QGIS精准识别
• 如果已知几何字段的坐标系SRID，可以在setDataSource()中新增参数传入SRID值，避免QGIS自动识别坐标系出错
• 如果查询结果没有单一字段作为主键，可以传入字段列表拼接的唯一键，例如"t1.id||'-'||t2.id"作为主键参数
• 该方法加载的图层为临时查询图层，不会修改数据库中的原有数据，也不会在数据库中创建实体视图，查询性能和直接在数据库中执行SQL一致

内容的提问来源于stack exchange，提问作者GeographyJames