NL2SQL accuracy stuck at 40%? The author's answer: schema comments, not the model
A practitioner account of a government data-platform deployment where the generated SQL was syntactically valid and ran fine, but filtered on the wrong column: user_status stored registration-channel codes while the real validity flag was is_valid, so "valid users" came out wrong. The author argues deployment failures mostly stem from undocumented fields, undefined business metrics, and unclear ownership, and recommends a three-layer approach: add table/column comments with enumerated values, write machine-readable metric definitions with formulas, time windows, exclusions and an owner, then choose where the semantic layer lives. In one internal validation on more than 100 questions with the same model, executable-SQL rate stayed near full marks while answer accuracy reportedly rose from just over 40% to above 85% after comments and metric definitions were added.
The case shows that in production NL2SQL, wrong-but-plausible SQL is more dangerous than failing SQL, and that documentation of schema semantics and metric definitions, not model choice, sets the practical accuracy ceiling on real enterprise databases.
AI 数据库的发布会上，各家讲的是库内推理、向量检索、多模融合，性能数字一个比一个漂亮。但项目落地时最先卡住人的往往不是这些，而是库里的表没人写注释、口径没人定。
这篇把方法拆成三层，每层都给可执行的 SQL，最后给一组同模型对比数据。
一、问题不在模型，先看一个真实现象
第一个项目是政务数据平台，一百六十多张表，挑一个业务口试点。POC 那周演示很顺，领导问什么都能出一条 SQL，还能出个表。
第二周业务真用起来，投诉就来了。上机去看：SQL 语法没有任何问题，表名对、字段名对、能跑、有结果。问题是过滤条件用错了字段——业务问「有效用户数」，模型查的是 user_status = 1，而这张表里 user_status 存的是注册渠道编码，真正的状态字段是 is_valid。
模型没报错，它只是把这个字段当成了「用户状态」，因为这字段在库里连一句注释都没有，它只能靠名字猜。