SQLModel 本身不直接暴露索引类型的配置选项，但可通过继承 SQLAlchemy 的 __table_args__ 机制，在模型中声明带数据库特性的索引（如 PostgreSQL 的 Hash 索引），同时保持跨方言兼容性。
sqlmodel 本身不直接暴露索引类型的配置选项，但可通过继承 sqlalchemy 的 `__table_args__` 机制，在模型中声明带数据库特性的索引（如 postgresql 的 hash 索引），同时保持跨方言兼容性。
SQLModel 作为 SQLAlchemy 和 Pydantic 的融合层，其核心优势在于简洁的声明式建模能力，但底层仍完全依赖 SQLAlchemy 的 DDL（数据定义语言）能力。这意味着——虽然 Field(index=True) 仅支持默认 B-Tree 索引（适用于范围查询、排序和前缀匹配），但若需更精细的性能优化（例如对高基数等值查询加速），你完全可以绕过高层抽象，直接使用 SQLAlchemy 原生的索引控制机制。
关键在于：利用 __table_args__ 元组声明 sqlalchemy.Index 实例，并通过方言特定参数（如 postgresql_using="hash"）指定索引算法。该方式具备以下特性：
- ✅ 数据库感知：postgresql_using="hash" 仅在 PostgreSQL 中生效；SQLite、MySQL 等其他后端会自动忽略该参数，退化为标准 B-Tree 索引（即 CREATE INDEX ... ON table (col)），保证迁移安全；
- ✅ 零侵入建模：无需修改 Field() 定义，也不用编写原始 SQL，所有逻辑仍保留在模型类内；
- ✅ 可复用与组合：__table_args__ 支持元组形式，可同时定义多个索引、唯一约束或表级选项。
下面是一个完整示例：
PostgreSQL 18.4 官方 Ubuntu 安装包现已发布，这是目前最新的稳定版本。推荐通过官方 APT 仓库安装：先执行 sudo apt update 更新索引，再运行 sudo apt install postgresql-18 即可完成部署。新版本引入了异步 I/O 子系统，在顺序扫描与 VACUUM 场景下性能提升显著，同时支持 UUID v7 原生生成函数与虚拟生成列。
from sqlmodel import SQLModel, Field, create_engine
from sqlalchemy import Index
class Hero(SQLModel, table=True):
id: int | None = Field(default=None, primary_key=True)
name: str = Field() # 不再用 index=True —— 改由 __table_args__ 统一管理
secret_name: str
age: int | None = Field(default=None)
# 声明 Hash 索引（仅 PostgreSQL 生效）
__table_args__ = (
Index("ix_hero_name_hash", "name", postgresql_using="hash"),
Index("ix_hero_age_btree", "age"), # 默认 B-Tree，全平台兼容
{"comment": "Hero records with optimized lookup strategies"},
)创建引擎并初始化表结构：
# PostgreSQL（启用 Hash 索引）
engine = create_engine("postgresql://user:pass@localhost/mydb")
SQLModel.metadata.create_all(engine)
# → 生成：CREATE INDEX ix_hero_name_hash ON hero USING hash (name);
# SQLite（自动降级为 B-Tree）
engine = create_engine("sqlite:///database.db")
SQLModel.metadata.create_all(engine)
# → 生成：CREATE INDEX ix_hero_name_hash ON hero (name);⚠️ 注意事项：
- Hash 索引仅支持精确等值查询（如 WHERE name = 'John'），不支持 >,
- MySQL 8.0+ 虽支持哈希索引，但仅限于 MEMORY 存储引擎，且 SQLAlchemy 当前未提供 mysql_using="hash" 参数（需手动 DDL 或 text() 执行）；
- 若需条件索引、函数索引或部分索引（Partial Index），同样可通过 Index(..., postgresql_where=...) 等扩展参数实现。
总结来说，SQLModel 并非“封闭”的 ORM 封装，而是鼓励你在必要时优雅地“下沉”至 SQLAlchemy 层。这种设计既保障了快速上手的体验，又不失生产环境所需的灵活性与控制力——真正做到了「简单处极简，复杂处可控」。
