在使用 SQLAlchemy（尤其是配合 Databricks 连接器）时，query.count().scalar() 意外返回 None 导致类型错误，通常源于版本不兼容；升级至 SQLAlchemy 2.0+ 及配套 databricks-sqlalchemy 2.0.5 可彻底解决。
在使用 sqlalchemy（尤其是配合 databricks 连接器）时，`query.count().scalar()` 意外返回 `none` 导致类型错误，通常源于版本不兼容；升级至 sqlalchemy 2.0+ 及配套 databricks-sqlalchemy 2.0.5 可彻底解决。
该问题并非逻辑错误，而是典型的驱动层与 ORM 层版本失配所致。在 SQLAlchemy 1.4.x 中，.count() 方法底层调用的是 SELECT COUNT(*) 子查询，并期望返回一个标量整数；但在某些旧版 Databricks 连接器（如 sqlalchemy-databricks==0.2.0）中，该查询可能因 SQL 方言适配不全、空结果集处理异常或游标未正确关闭等原因，导致 .scalar() 返回 None 而非 0 —— 进而引发 int() argument must be a string, a bytes-like object or a real number, not 'NoneType' 报错。
值得注意的是，len(db.query(query_class).all()) 能正常工作，是因为它先执行完整查询加载所有对象到内存再计数，绕过了底层 COUNT 优化路径，但该方式严重低效且不可用于大数据集分页场景，不应作为替代方案。
✅ 正确解决方案是统一升级核心依赖：
databricks-sql-connector==4.0.0 databricks-sqlalchemy==2.0.5 SQLAlchemy==2.0.39
升级后，.count() 行为符合预期：空表返回 0，非空表返回准确行数，且全程不触发 .all()，保持高效分页能力。同时，SQLAlchemy 2.0 引入了更严格的类型安全和标准化的执行接口（如推荐使用 session.execute(select(func.count())).scalar_one()），建议同步迁移以获得长期可维护性。
⚠️ 注意事项：
- 升级前请清除虚拟环境并重装依赖（
pip uninstall -y sqlalchemy sqlalchemy-databricks && pip install -r requirements.txt），避免残留缓存； - 若使用 FastAPI + SQLAlchemy 2.0，需确认 Session 配置启用
expire_on_commit=False并采用session.scalars()/session.execute()新式调用； -
sqlalchemy-databricks已被官方弃用，应替换为databricks-sqlalchemy（由 Databricks 官方维护）。
通过版本对齐，不仅修复 count() 返回 None 的问题，也提升了查询稳定性与未来兼容性。
