如何在Azure Function Cosmos DB输入绑定sqlQuery中正确替换路由/查询参数

适用于JavaScript栈HTTP触发器场景，针对{key}占位符默认解析为字符串导致的三类查询异常，对应解决方案如下：

问题根因说明 #

Cosmos DB输入绑定的{key}占位符本质是字符串字面量替换，仅支持在查询的等值匹配、字符串比较位做替换，不支持在要求数值常量、标识符、别名的语法位置直接使用，且Cosmos DB SQL本身存在固定语法限制：

• TOP子句后仅允许接整数常量，不支持接表达式、函数返回值
• AS关键字后仅允许接静态标识符，不支持接字符串字面量
• 未显式指定别名的计算列（含动态属性索引c[xxx]），引擎会自动生成$1/$2格式的默认列名

分问题解决方案 #

1. TOP参数传入报类型/语法错误 #

不要在function.json中静态配置sqlQuery拼接{max}，也不要尝试在SQL中用CAST/CONVERT转换——这类写法从Cosmos SQL语法层面就不支持。
正确做法是移除绑定中的静态sqlQuery配置，在函数代码中通过命令式绑定调用Cosmos客户端，走SDK原生参数化查询，直接传入数值类型的TOP参数：

// 函数入口代码
module.exports = async function (context, req) {
    // 从路由/查询参数中获取值并转成对应类型
    const pageSize = parseInt(req.query.max ?? req.params.max);
    const targetField = req.query.telemetry ?? req.params.telemetry;

    // 执行参数化查询
    const result = await context.bindings.cosmosDB.query({
        query: "SELECT TOP @pageSize c[@field] AS fieldValue FROM c",
        parameters: [
            { name: "@pageSize", value: pageSize },
            { name: "@field", value: targetField }
        ]
    }).fetchAll();

    // 处理后续结果映射
    const response = result.resources.map(item => ({
        [targetField]: item.fieldValue
    }));

    context.res = { body: response };
}

对应的function.json中Cosmos DB输入绑定配置参考：

{
  "type": "cosmosDB",
  "direction": "in",
  "name": "cosmosDB",
  "databaseName": "你的数据库名",
  "containerName": "你的容器名",
  "connectionStringSetting": "CosmosDB连接字符串配置项名",
  "sqlQuery": "" // 留空，不配置静态SQL
}

2. 动态属性查询返回键名为$1 #

这个是Cosmos DB的默认行为：只要查询列是计算表达式（包括动态索引取值）且没有指定静态别名，就会返回$1这类自动生成的列名，没有配置项可以修改这个默认规则。
直接参照上面的代码示例，在查询时给动态列指定一个固定别名（比如示例里的fieldValue），拿到结果后在JS代码层通过对象计算属性，把键名替换成你需要的动态字段名即可。

3. AS后接{key}占位符报语法错误 #

这个是语法限制导致的：AS后必须写不带引号的静态标识符，而{key}占位符替换后会生成带单引号的字符串字面量（比如替换后是AS 'temperature'），完全不符合语法要求。
Cosmos DB SQL本身不支持参数化别名，不要尝试在SQL层面实现动态别名，统一在代码层做结果键名映射即可，逻辑简单且性能无损耗。

最佳实践提醒 #

• 静态配置sqlQuery+{key}占位符的写法，仅适合参数为字符串类型、且出现在值匹配位置的场景，比如SELECT * FROM c WHERE c.deviceId = {deviceId}
• 所有涉及动态数值、动态字段名、动态返回结构的查询，统一走SDK参数化查询，既可以避免语法问题，也能从根本上防止SQL注入风险。

内容的提问来源于stack exchange，提问作者neo