Cosmos DB使用IQueryable过滤可空Guid字段无返回结果如何解决？

问题根源 #

你的问题由两个原因共同导致：

1. 序列化配置错误：默认配置下，Microsoft.Azure.Cosmos SDK会将Guid?这类可空值类型序列化为包含hasValue和value两个属性的嵌套JSON对象，而非直接存储为Guid字符串或null，你容器中已存储的ClientId实际是嵌套结构，自然匹配不到直接查询Guid值的条件。
2. LINQ翻译规则适配问题：你显式调用.HasValue和.Value的写法，会被Cosmos LINQ提供器识别为访问可空对象的嵌套属性，所以生成的SQL会出现root['clientId']['hasValue']和root['clientId']['value']这类不符合你预期的字段访问逻辑。

解决步骤 #

方案一：修正序列化配置+调整LINQ写法（推荐） #

该方案可以让存储结构符合你预期的扁平结构，查询效率更高。

1. 调整Cosmos客户端初始化时的序列化配置
   如果你使用Newtonsoft.Json作为序列化器：

using Microsoft.Azure.Cosmos;
using Newtonsoft.Json;
using Newtonsoft.Json.Converters;

var cosmosClient = new CosmosClient("你的服务终结点", "你的访问密钥", new CosmosClientOptions
{
    Serializer = new NewtonsoftJsonCosmosSerializer(new JsonSerializerSettings
    {
        NullValueHandling = NullValueHandling.Ignore,
        Converters = { new StringEnumConverter() }
    })
});

如果你使用System.Text.Json作为序列化器：

using Microsoft.Azure.Cosmos;
using System.Text.Json;
using System.Text.Json.Serialization;

var cosmosClient = new CosmosClient("你的服务终结点", "你的访问密钥", new CosmosClientOptions
{
    Serializer = new SystemTextJsonCosmosSerializer(new JsonSerializerOptions
    {
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
        Converters = { new JsonStringEnumConverter() }
    })
});

配置完成后，新写入的Lead文档中ClientId字段会直接存储为Guid字符串，为null时不会存储该字段，符合预期存储结构。

2. 修改LINQ查询逻辑
   避免显式调用.HasValue和.Value，调整为如下写法：

if (search.ClientId?.Any() == true)
{
    var filterIds = search.ClientId.Cast<Guid?>().ToList();
    queryable = queryable.Where(lead => lead.ClientId != null && filterIds.Contains(lead.ClientId));
}

修改后生成的SQL会符合你的预期：

WHERE IS_DEFINED(root['clientId']) AND root['clientId'] IN ('some GUID', 'another GUID') ORDER BY root['created'] ASC

方案二：兼容已有旧数据（无需修改存储结构） #

如果你不想修改已经写入的旧数据，不需要调整序列化配置，直接用你原来的LINQ写法即可，生成的SQL可以匹配现有嵌套结构的存储数据，直接返回符合条件的结果。

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