Cosmos DB中CONTAINS方法使用参数化查询报错如何解决？

你的代码存在两处核心错误，直接触发参数无效报错：

• 参数名不符合Cosmos DB命名规则：Cosmos DB要求查询参数必须是@开头的合法标识符，名称中不能包含.符号。你定义的参数名@c.Surname带了属性路径用的点号，会被查询引擎识别为对容器别名c下Surname属性的引用，而非独立查询参数，直接触发格式校验错误。
• 查询语句写法违背参数化查询逻辑：你使用C#字符串插值$""语法直接把surname变量值拼入SQL，还给占位符额外包裹了单引号。这相当于提前把参数值硬编码到SQL语句中，既失去了参数化查询防注入、自动类型转义的作用，插值后SQL里的占位符会变成@xxx（xxx是你传入的姓氏实际值），和后续WithParameter传入的参数名完全不匹配，根本无法完成参数绑定。

编写Cosmos DB参数化查询记住两个核心规则即可：

• 不要用字符串插值、字符串拼接的方式把参数值写入SQL语句，参数位置直接写固定的@参数名占位符即可，不需要给占位符加单引号，SDK会自动完成类型转义和特殊字符处理。
• 参数名保持简单合法即可，只需要@开头，不要带入容器别名（比如例子里的c）、点号这类路径符号，常规场景直接用和字段语义对应的名称（比如@surname）就不会出错。

基于CONTAINS的模糊查询正确代码如下：

// 移除$插值标记，参数位置直接写占位符@surname，不额外加单引号
var query = "SELECT * FROM c WHERE CONTAINS(c.Surname, @surname, true)";
var queryDefinition = new QueryDefinition(query)
    // 传入的参数名和SQL里的占位符完全一致，不带点号
    .WithParameter("@surname", surname);

如果需要多字段模糊匹配，按相同规则扩展参数即可，示例：

var query = "SELECT * FROM c WHERE CONTAINS(c.Surname, @surname, true) AND CONTAINS(c.Email, @email, true)";
var queryDefinition = new QueryDefinition(query)
    .WithParameter("@surname", surname)
    .WithParameter("@email", email);

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