使用SQLAlchemy向Azure Synapse插入数据时遇OUTPUT语法错误求助

根本原因 #

Azure Synapse（尤其是无服务器SQL池）不支持SQL Server的OUTPUT子句，但SQLAlchemy默认的MS SQL dialect会生成包含OUTPUT inserted.id的INSERT语句来获取自增主键，这直接触发了语法错误。

解决方案 #

1. 使用适配Synapse的SQLAlchemy Dialect #

官方默认的MS SQL dialect不完全适配Synapse，推荐使用专门的sqlalchemy-synapse库：

• 安装依赖：

  pip install sqlalchemy-synapse
  

• 替换引擎创建逻辑：

  from sqlalchemy import create_engine
  
  # 替换为你的Synapse连接信息
  engine = create_engine('synapse://<username>:<password>@<synapse-workspace>.sql.azuresynapse.net/<database-name>')
  

这个dialect会自动规避Synapse不支持的语法（如OUTPUT子句），无需修改插入代码。

2. 手动调整插入逻辑（无需额外依赖） #

如果不想更换dialect，可直接修改插入代码，避免SQLAlchemy生成OUTPUT语句：

场景1：不需要返回自增ID

from sqlalchemy import insert

# 构造插入语句
stmt = insert(User).values(username='test_user', email='test@example.com')
# 执行插入
db.session.execute(stmt)
db.session.commit()

场景2：需要获取自增ID（仅适用于Synapse专用SQL池）

专用池支持SCOPE_IDENTITY()，可通过以下方式获取：

from sqlalchemy import text, insert

# 执行插入
stmt = insert(User).values(username='test_user', email='test@example.com')
db.session.execute(stmt)
# 查询刚插入的ID
user_id = db.session.execute(text("SELECT SCOPE_IDENTITY()")).scalar()
db.session.commit()

注意：无服务器SQL池不支持自增IDENTITY列的SCOPE_IDENTITY()，建议改用UUID作为主键。

3. 模型配置优化 #

确保你的SQLAlchemy模型主键配置与Synapse表定义一致：

from sqlalchemy import Column, Integer, String, text
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    # 匹配Synapse的IDENTITY(1,1)定义
    id = Column(Integer, primary_key=True, server_default=text('IDENTITY(1,1)'))
    username = Column(String(50), nullable=False)
    email = Column(String(100), nullable=False)

验证步骤 #

1. 在Synapse Studio中直接执行以下语句，确认是否报错：

   INSERT INTO users (username, email) OUTPUT inserted.id VALUES ('test', 'test@example.com')
   

   若报错，则证明Synapse确实不支持OUTPUT子句。
2. 应用上述解决方案后，重新执行插入代码，验证是否成功提交。

内容的提问来源于stack exchange，提问作者Eva Sanchez-Guerrero Ayala