数据形态

下面给你一个高价值可长期复用的总结：

常用的数据查询场景 -> SQL 查询形态 -> 查询结果的数据结构 -> Python 中的对应数据格式。

这是一个完全贴近你在 FastAPI + SQLAlchemy + PostgreSQL 项目中使用的“实战速查表”，可以直接用在你的业务逻辑、ORM 查询、数据转换工具函数中。

✅ 一、单值查询（Single Value）

场景

查询总数
查询最大值/最小值/平均值
查询某个字段是否存在
获取某个 ID 是否存在

SQL 示例

SELECT COUNT(*) FROM users;
SELECT MAX(age) FROM users;
SELECT EXISTS(SELECT 1 FROM users WHERE id=1);

PostgreSQL 返回形态

类型	示例
单个数值（int/bigint/numeric）	123
布尔值	true/false
单个字符串	‘hello’

Python 对应格式

Python 类型	示例
int	123
float	12.34
str	“hello”
bool	True/False

SQLAlchemy 查询

count = session.execute(stmt).scalar_one()

✅ 二、单行查询（Single Row）

场景

查询单个用户
查询详情页数据
查询最新一条记录

SQL 示例

SELECT id, name, age FROM users WHERE id = 1;

PostgreSQL 返回形态

类似：

(1, 'Alice', 20)

Python 对应格式

Python 类型	示例
tuple	(1, “Alice”, 20)
ORM 对象	User(id=1, name=“Alice”)
dict（转换后）	{‘id’:1, ’name’:‘Alice’, ‘age’:20}

SQLAlchemy 查询

obj = session.execute(stmt).scalar_one()

✅ 三、单列多行（Single Column, Multiple Rows）

场景

查询所有 code
查询股票名称列表
查询某表所有主键
查询一组数值用于 IN 查询

SQL 示例

SELECT code FROM ashare;

PostgreSQL 返回形态

['000001', '000002', '000003']

Python 对应格式

Python 类型	示例
`list[str]`	`["000001", "000002"]`
`list[int]`	`[1, 2, 3]`

SQLAlchemy 查询

codes = session.execute(stmt).scalars().all()

✅ 四、多行多列（Rows -> Table Data）

场景

列表页
分页数据
任意 JOIN
报表数据
用户列表、股票列表等

SQL 示例

SELECT code, name, price FROM ashare ORDER BY code LIMIT 10;

PostgreSQL 返回形态

[('000001', '平安银行', 10.5),
 ('000002', '万科A', 13.2)]

Python 对应格式

Python 格式	示例
`list[tuple]`	`[("000001","平安银行",10.5)]`
`list[ORM 对象]`	`[Ashare(...), Ashare(...)]`
`list[dict]`（你项目常用）	`[{"code":"000001", "name":"平安银行"}]`

SQLAlchemy 查询

rows = session.execute(
    select(Ashare.code, Ashare.name, Ashare.price)
).all()   # list of tuples

若使用 ORM 模式：

objs = session.execute(select(Ashare)).scalars().all()

✅ 五、聚合形态（Aggregate）

场景

聚合统计
分组统计（group by）
业务报表
柱状图、折线图数据源

SQL 示例

SELECT plate, COUNT(*)
FROM ashare
GROUP BY plate;

PostgreSQL 返回形态

[('银行', 32), ('科技', 20)]

Python 格式

list[tuple]

转 dict：

{"银行": 32, "科技": 20}

✅ 六、JSON 查询（JSON / JSONB）

场景

jsonb 字段存储
动态属性
聚合生成 JSON 对象

SQL 示例

SELECT json_build_object('code', code, 'name', name)
FROM ashare LIMIT 1;

PostgreSQL 返回形态

{"code":"000001","name":"平安银行"}

Python 对应格式

Python 类型	示例
`dict`	`{"code": "000001", "name": "平安银行"}`
`list[dict]`	`[{}, {}]`

✅ 七、数组查询（Array）

场景

股票标签
用户角色列表
文章标签
ANY/ALL 查询

SQL 示例

SELECT tags FROM articles;

PostgreSQL 返回

{"科技","AI","大模型"}

Python 对应

["科技", "AI", "大模型"]

✅ 八、子查询与嵌套结构（Subquery / Nested）

场景

复杂筛选
Top1 子查询
分组后取最新记录

SQL 示例

SELECT *
FROM stock s
WHERE s.id = (
    SELECT id FROM stock ORDER BY date DESC LIMIT 1
);

Python 对应格式

ORM 对象或 tuple。

✅ 九、JOIN 查询（跨表、多表）

场景

用户与角色
股票与概念板块
数据关联查询
多表报表

SQL 示例

SELECT u.id, u.name, r.role
FROM users u
JOIN roles r ON u.role_id = r.id;

Python 对应格式

格式	示例
tuple	`(1, "张三", "admin")`
dict（转换后）	`{"id":1,"name":"张三","role":"admin"}`

✅ 十、分页查询（Pagination）

SQL 示例

SELECT id, name FROM users ORDER BY id LIMIT 10 OFFSET 20;

Python 结果

list[dict] | list[tuple] | list[ORM]

🧩 最终总结：常用 SQL 查询形态 -> Python 数据类型总览

场景	SQL 结果	Python 形式
单值	`5`	int/str/float/bool
单行	`(1, "A")`	`tuple` / `dict` / ORM
单列	`['a','b']`	`list[str]`
多行多列	`[(...),(...)]`	`list[tuple]` / `list[dict]` / ORM
聚合统计	`[(key, val)]`	`list[tuple]` / `dict`
JSON	`{"a":1}`	`dict`
数组	`{1,2,3}`	`list`
JOIN	`[(...)]`	`list[tuple]` / `list[dict]`
分页	`[(...)]`	`list[...]`