使用Python与PostgreSQL的JSON数据进行交互

 更新时间:2026年02月07日 09:51:00   作者:数据知道  
PostgreSQL自9.2版本起原生支持JSON数据类型,并在后续版本中不断增强其功能,现已提供JSON和JSONB两种类型、丰富的操作符、索引支持及函数体系,本文将系统讲解如何在Python中高效、安全、可维护地与PostgreSQL的JSON数据交互,需要的朋友可以参考下

PostgreSQL 自 9.2 版本起原生支持 JSON 数据类型,并在后续版本中不断增强其功能,现已提供 JSONJSONB 两种类型、丰富的操作符、索引支持及函数体系。与此同时,Python 作为数据处理的主流语言,与 PostgreSQL 的结合日益紧密。

本文将系统讲解如何在 Python 中高效、安全、可维护地与 PostgreSQL 的 JSON 数据交互,涵盖:

  • JSON 与 JSONB 的区别与选型
  • 使用 psycopg2asyncpg 等主流驱动
  • 自动序列化/反序列化 Python 字典与 JSON
  • 复杂查询:路径提取、条件过滤、更新操作
  • 性能优化与索引策略
  • 实战案例:配置存储、日志分析、动态表单等

一、PostgreSQL 中的 JSON 类型基础

参考

  • PostgreSQL JSON 函数文档:https://www.postgresql.org/docs/current/functions-json.html
  • psycopg2 JSON 支持:https://www.psycopg.org/docs/extras.html#json-adaptation
  • asyncpg 类型映射:https://magicstack.github.io/asyncpg/current/usage.html#type-conversion

1.1 JSON vs JSONB:关键区别

特性JSONJSONB
存储格式文本(保留原始格式)二进制(解析后存储)
是否去重否(保留重复键)是(仅保留最后一个键值)
是否保留顺序否(对象键无序)
索引支持不支持(需表达式索引)支持 GIN、GiST 索引
查询性能较慢(每次需解析)快(已解析为内部结构)
存储空间较大较小(无空白、无重复)

推荐:除非必须保留原始 JSON 格式(如审计日志),否则一律使用 JSONB

1.2 常用操作符与函数

1、路径提取

->:返回 JSON 对象(仍为 JSONB)

SELECT data->'user'->'name' FROM logs;

->>:返回文本(TEXT)

SELECT data->>'status' FROM orders;

2、条件查询

检查键是否存在:

SELECT * FROM events WHERE data ? 'error_code';

检查嵌套路径:

SELECT * FROM configs WHERE data @> '{"feature": {"enabled": true}}';

3、更新操作

设置字段(PostgreSQL 9.5+):

UPDATE users SET profile = jsonb_set(profile, '{settings,theme}', '"dark"');

二、Python 驱动选择与配置

2.1 主流驱动对比

驱动异步支持JSON 自动转换成熟度适用场景
psycopg2需手动注册适配器同步应用、Django、Flask
psycopg2-binary同上快速原型、无需编译
asyncpg自动转换 dict ↔ JSONB异步框架(FastAPI, aiohttp)
SQLAlchemy + psycopg2通过 JSON / JSONB 类型自动处理极高ORM 场景

2.2 PostgreSQL 的 JSONB 与 Python 的结合注意点

PostgreSQL 的 JSONB 与 Python 的结合,为处理半结构化数据提供了强大而灵活的方案。通过合理选择驱动、配置自动转换、利用索引和操作符,可实现:

  • 开发效率高:无需预定义 schema
  • 查询能力强:支持复杂嵌套查询
  • 性能可优化:GIN 索引、路径索引保障效率

但也要谨记:

  • 不要滥用 JSON:结构化数据仍应使用关系模型
  • 保持查询简单:避免过度嵌套导致维护困难
  • 监控性能:定期分析执行计划

三、使用 psycopg2 处理 JSON

3.1 基础连接与自动转换

默认情况下,psycopg2JSONB 列返回为字符串。需注册适配器实现自动转换:

import json
import psycopg2
from psycopg2.extras import Json

# 注册自动转换:DB → Python
def _json_decode(data, cur):
    if data is None:
        return None
    return json.loads(data)

# 注册适配器
psycopg2.extensions.register_type(
    psycopg2.extensions.new_type(
        (3802,), "JSONB", _json_decode  # 3802 是 JSONB 的 OID
    )
)

# 连接数据库
conn = psycopg2.connect(
    host="localhost",
    database="mydb",
    user="user",
    password="pass"
)

3.2 插入 JSON 数据

data = {
    "user_id": 123,
    "action": "login",
    "metadata": {
        "ip": "192.168.1.1",
        "device": "mobile"
    }
}

cur = conn.cursor()
cur.execute(
    "INSERT INTO events (event_data) VALUES (%s)",
    (Json(data),)  # 使用 Json 包装器
)
conn.commit()

注意:必须使用 psycopg2.extras.Json,否则会被当作字符串插入。

3.3 查询并自动反序列化

cur.execute("SELECT id, event_data FROM events WHERE id = %s", (1,))
row = cur.fetchone()
print(type(row[1]))  # <class 'dict'>
print(row[1]['metadata']['ip'])  # 192.168.1.1

得益于前面的适配器注册,event_data 自动转为 dict

3.4 复杂查询示例

1、提取嵌套字段

cur.execute("""
    SELECT 
        id,
        event_data->>'action' AS action,
        event_data->'metadata'->>'ip' AS ip
    FROM events
    WHERE (event_data->'metadata'->>'device') = %s
""", ("mobile",))

for row in cur:
    print(f"Action: {row[1]}, IP: {row[2]}")

2、条件过滤(使用 @>)

# 查找包含特定子结构的记录
filter_condition = {"metadata": {"device": "mobile"}}
cur.execute(
    "SELECT * FROM events WHERE event_data @> %s",
    (Json(filter_condition),)
)

四、使用 asyncpg 处理 JSON(异步场景)

asyncpg 对 JSONB 支持更友好,默认自动转换。

4.1 基础用法

import asyncio
import asyncpg

async def main():
    conn = await asyncpg.connect(
        host='localhost',
        database='mydb',
        user='user',
        password='pass'
    )

    # 插入:直接传 dict
    data = {"user_id": 123, "tags": ["a", "b"]}
    await conn.execute(
        "INSERT INTO items (payload) VALUES ($1)",
        data  # asyncpg 自动序列化为 JSONB
    )

    # 查询:自动反序列化为 dict/list
    row = await conn.fetchrow("SELECT payload FROM items LIMIT 1")
    print(type(row['payload']))  # <class 'dict'>
    print(row['payload']['tags'])  # ['a', 'b']

    await conn.close()

asyncio.run(main())

优势:无需额外配置,开箱即用。

4.2 复杂查询

# 使用路径操作符
rows = await conn.fetch("""
    SELECT 
        id,
        payload->'user'->>'name' AS name
    FROM profiles
    WHERE payload @> $1
""", {"settings": {"visible": True}})

for r in rows:
    print(r['name'])

五、使用 SQLAlchemy ORM 处理 JSON

SQLAlchemy 通过 JSONJSONB 类型提供 ORM 支持。

5.1 模型定义

from sqlalchemy import create_engine, Column, Integer
from sqlalchemy.dialects.postgresql import JSONB
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

Base = declarative_base()

class Event(Base):
    __tablename__ = 'events'
    id = Column(Integer, primary_key=True)
    data = Column(JSONB)  # 使用 JSONB

engine = create_engine('postgresql://user:pass@localhost/mydb')
Session = sessionmaker(bind=engine)

5.2 CRUD 操作

session = Session()

# 插入
event = Event(data={
    "type": "click",
    "element": {"id": "btn1", "class": "primary"}
})
session.add(event)
session.commit()

# 查询(自动转为 dict)
e = session.query(Event).first()
print(e.data['element']['id'])  # btn1

# 条件查询(使用 .op() 调用操作符)
from sqlalchemy import text
results = session.query(Event).filter(
    Event.data.op('@>')({'type': 'click'})
).all()

5.3 使用专用函数(SQLAlchemy 1.4+)

from sqlalchemy.dialects.postgresql import JSONB

# 提取字段
session.query(
    Event.data['user']['name'].astext.label('username')
).all()

六、高级技巧与最佳实践

6.1 动态构建 JSON 查询条件

避免拼接 SQL,使用参数化:

def find_by_metadata(conn, **kwargs):
    # 构建嵌套 dict
    condition = {"metadata": kwargs}
    cur = conn.cursor()
    cur.execute(
        "SELECT * FROM events WHERE event_data @> %s",
        (Json(condition),)
    )
    return cur.fetchall()

# 调用
results = find_by_metadata(conn, device="mobile", os="iOS")

6.2 更新 JSON 字段

# 使用 jsonb_set 更新嵌套字段
cur.execute("""
    UPDATE users 
    SET profile = jsonb_set(profile, %s, %s, true)
    WHERE id = %s
""", (
    ['settings', 'notifications'],  # 路径(数组)
    Json({"email": True, "push": False}),  # 新值
    user_id
))

第四个参数 true 表示:若路径不存在则创建。

6.3 索引优化

对高频查询字段建立 GIN 索引:

-- 全文索引(适用于任意键查询)
CREATE INDEX idx_event_data ON events USING GIN (event_data);

-- 特定路径索引(更高效)
CREATE INDEX idx_event_action ON events ((event_data->>'action'));

在 Python 中可通过 Alembic 或原生 SQL 创建。

七、性能考量

7.1 存储效率

  • JSONBJSON 节省 10%~30% 空间
  • 避免在 JSON 中存储大文本(如 base64 图片),应存 URL

7.2 查询性能

  • 避免在 WHERE 中对 JSON 字段使用函数(如 length(data->>'name')),会导致索引失效
  • 优先使用 @>, ?, ->> 等支持索引的操作符

7.3 批量操作

  • 使用 execute_values(psycopg2)或 copy_records_to_table(asyncpg)提升批量插入性能
  • 示例(psycopg2):
from psycopg2.extras import execute_values
data_list = [{"id": i, "tags": ["x"]} for i in range(1000)]
execute_values(
    cur,
    "INSERT INTO items (payload) VALUES %s",
    [(Json(d),) for d in data_list]
)

八、典型应用场景

8.1 用户配置存储

CREATE TABLE user_settings (
    user_id INT PRIMARY KEY,
    preferences JSONB NOT NULL DEFAULT '{}'
);
  • 优势:无需 ALTER TABLE 即可新增配置项
  • 查询:SELECT preferences->'theme' FROM user_settings

8.2 日志与事件追踪

  • 存储非结构化日志,支持按任意字段过滤
  • 结合 BRIN 索引按时间分区,GIN 索引按内容查询

8.3 动态表单/问卷

  • 表单结构存为 JSON,回答存为另一 JSON
  • 避免 EAV(Entity-Attribute-Value)反模式

九、常见陷阱与解决方案

9.1 时区与日期处理

JSON 不支持日期类型,通常存为 ISO 字符串:

data = {"created_at": datetime.utcnow().isoformat()}

查询时用 to_timestamp() 转换:

SELECT to_timestamp(data->>'created_at', 'YYYY-MM-DD"T"HH24:MI:SS.US') 
FROM logs;

9.2 精度丢失(浮点数)

PostgreSQL 的 JSONB 使用 IEEE 754 双精度,与 Python 一致,一般无问题。
但若需高精度(如金融),应存为字符串或使用 NUMERIC 字段。

9.3 键名大小写敏感

JSON 对象键区分大小写:

-- 以下不等价
data->'UserId'  vs  data->'userid'

建议统一使用小写命名。

以上就是使用Python与PostgreSQL的JSON数据进行交互的详细内容,更多关于Python与PostgreSQL JSON数据交互的资料请关注脚本之家其它相关文章!

相关文章

  • 关于tensorflow和keras版本的对应关系

    关于tensorflow和keras版本的对应关系

    这篇文章主要介绍了关于tensorflow和keras版本的对应关系,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2023-06-06
  • Python语言开发高并发爬虫示例探讨

    Python语言开发高并发爬虫示例探讨

    这篇文章主要为大家介绍了Python语言开发高并发爬虫示例探讨,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
    2023-12-12
  • Python提取视频帧图片实例代码

    Python提取视频帧图片实例代码

    大家好,本篇文章主要讲的是Python提取视频帧图片实例代码,感兴趣的同学赶快来看一看吧,对你有帮助的话记得收藏一下,方便下次浏览
    2021-12-12
  • 使用Python的urllib2模块处理url和图片的技巧两则

    使用Python的urllib2模块处理url和图片的技巧两则

    这篇文章主要介绍了使用Python的urllib2模块处理url和图片的两个小技巧,分别是获取带有中文参数的url内容和获取远程图片的大小和尺寸,需要的朋友可以参考下
    2016-02-02
  • python实现飞船游戏的纵向移动

    python实现飞船游戏的纵向移动

    这篇文章主要为大家详细介绍了python实现飞船游戏的纵向移动,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2020-04-04
  • 跟老齐学Python之开始真正编程

    跟老齐学Python之开始真正编程

    通过对四则运算的学习,已经初步接触了Python中内容,但是到目前为止,还不能算编程,只能算会用一些指令(或者叫做命令)来做点简单的工作。列位稍安勿躁,下面我们就学习如何编写一个真正的程序。
    2014-09-09
  • python实现磁盘日志清理的示例

    python实现磁盘日志清理的示例

    这篇文章主要介绍了python实现磁盘日志清理的示例,帮助大家更好的理解和使用python,感兴趣的朋友可以了解下
    2020-11-11
  • Python新版极验验证码识别验证码教程详解

    Python新版极验验证码识别验证码教程详解

    这篇文章主要介绍了Python新版极验验证码识别验证码,极验验证是一种在计算机领域用于区分自然人和机器人的,通过简单集成的方式,为开发者提供安全、便捷的云端验证服务
    2023-02-02
  • 详解如何在Matplotlib中绘制平滑曲线

    详解如何在Matplotlib中绘制平滑曲线

    这篇文章主要为大家详细介绍了如何在Matplotlib中绘制平滑曲线,文中的示例代码讲解详细,具有一定的借鉴价值,有需要的小伙伴可以参考下
    2024-04-04
  • python爬取分析超级大乐透历史开奖数据

    python爬取分析超级大乐透历史开奖数据

    这篇文章主要介绍了python爬取分析超级大乐透历史开奖数据,本次使用了requests和beautifulsoup库进行数据的爬取,通过实例代码给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
    2021-02-02

最新评论