Firestore模式下Google Datastore的IN ARRAY GQL查询枚举异常问题

问题概述 #

在Firestore模式的Google Datastore中执行包含IN ARRAY(..)语法的GQL查询时，调用QueryResults.hasNext()读取实体过程中会抛出IllegalArgumentException: Can't get the number of an unknown enum value。异常固定触发在某个特定实体的读取环节，且2022年12月版本的Java Datastore API也存在该问题。

重现代码 #

String sql = "SELECT *  FROM myentity WHERE myfield IN ARRAY('abc','efg') and some other conditions LIMIT 10001 OFFSET 0";
GqlQuery.Builder builder = GqlQuery.newGqlQueryBuilder(sql);
builder.setAllowLiteral(true);
GqlQuery query = builder.build();
QueryResults response = datastore.run(query);
while(response.hasNext()) { // <- 此处抛出异常
        Entity entity = (Entity)response.next();
// 实体处理逻辑
}

异常栈信息 #

Can't get the number of an unknown enum value.
java.lang.IllegalArgumentException: Can't get the number of an unknown enum value.
at com.google.datastore.v1.PropertyFilter$Operator.getNumber(PropertyFilter.java:233)
at com.google.datastore.v1.PropertyFilter$Builder.setOp(PropertyFilter.java:929)
at com.google.cloud.datastore.StructuredQuery$PropertyFilter.toPb(StructuredQuery.java:519)
at com.google.cloud.datastore.StructuredQuery$CompositeFilter.toPb(StructuredQuery.java:237)
at com.google.cloud.datastore.StructuredQuery.toPb(StructuredQuery.java:1011)
at com.google.cloud.datastore.StructuredQuery.populatePb(StructuredQuery.java:975)
at com.google.cloud.datastore.QueryResultsImpl.sendRequest(QueryResultsImpl.java:71)
at com.google.cloud.datastore.QueryResultsImpl.computeNext(QueryResultsImpl.java:93)
at com.google.common.collect.AbstractIterator.tryToComputeNext(AbstractIterator.java:141)
at com.google.common.collect.AbstractIterator.hasNext(AbstractIterator.java:136)

排查与解决方案 #

1. 修正GQL语法（核心修复） #

Firestore模式的Datastore GQL不支持IN ARRAY(..)的写法，标准语法是直接使用IN后跟值列表。ARRAY关键字属于冗余写法，会导致API在解析过滤器时无法识别枚举操作符，触发异常。

修正后的查询语句：

String sql = "SELECT * FROM myentity WHERE myfield IN ('abc','efg') and some other conditions LIMIT 1000 OFFSET 0";

2. 检查实体字段类型一致性 #

异常固定触发在特定实体，说明该实体的myfield字段类型可能与查询中的字符串类型不匹配（比如字段实际存储为枚举、数组或其他复杂类型）。需要定位该实体，确认字段类型，并调整查询条件匹配实际类型：

• 如果字段是枚举类型，使用枚举的原始值进行查询
• 如果字段是数组类型，确保查询逻辑符合数组匹配规则

3. 拆分大结果集查询 #

Datastore查询默认单页最多返回1000条结果，设置LIMIT 10001会触发自动分页，分页请求转换时可能出现枚举操作符错误。建议拆分查询，使用游标（Cursor）实现高效分页：

// 初始查询
String baseSql = "SELECT * FROM myentity WHERE myfield IN ('abc','efg') and some other conditions LIMIT 1000";
GqlQuery initialQuery = GqlQuery.newGqlQueryBuilder(baseSql)
        .setAllowLiteral(true)
        .build();
QueryResults<Entity> results = datastore.run(initialQuery);

// 处理第一页
processEntities(results);
Cursor cursor = results.getCursor();

// 分页遍历剩余结果
while (cursor != null) {
    GqlQuery nextQuery = GqlQuery.newGqlQueryBuilder(baseSql)
            .setAllowLiteral(true)
            .setStartCursor(cursor)
            .build();
    results = datastore.run(nextQuery);
    processEntities(results);
    cursor = results.getCursor();
}

// 实体处理方法
private void processEntities(QueryResults<Entity> results) {
    while (results.hasNext()) {
        Entity entity = results.next();
        // 业务逻辑处理
    }
}

4. 升级API版本 #

尽管2022年12月版本存在该问题，建议升级到最新的Google Cloud Datastore Java API版本，官方可能已修复该枚举解析的兼容性问题。

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