Amazon Keyspaces单键ALLOW FILTERING查询在Node.js中返回0行问题

问题原因排查与解决方案 #

1. 一致性级别配置不匹配 #

AWS Keyspaces控制台默认使用LOCAL_ONE一致性级别执行查询，而cassandra-driver 4.x版本默认查询一致性级别为LOCAL_QUORUM。如果写入数据时使用了低一致性级别，或者跨可用区数据同步未完成，LOCAL_QUORUM级别的查询会无法读取到仅写入了单可用区节点的数据，就会出现控制台能查到数据、Node.js侧返回空的情况。
解决方法：执行查询时显式指定和控制台对齐的一致性级别：

const { types } = require('cassandra-driver');
const query = "SELECT fields FROM table WHERE KeyA = 'value' LIMIT 10 ALLOW FILTERING";
// 显式指定一致性级别为LOCAL_ONE
const options = { consistency: types.consistencies.localOne };
const result = await client.execute(query, [], options);

2. ALLOW FILTERING参数未在驱动侧显式开启 #

你使用的cassandra-driver v4.6.1对AWS Keyspaces的兼容存在已知的小问题：即使CQL语句中写了ALLOW FILTERING，驱动也可能忽略该标识，要求在查询选项中显式开启allowFiltering配置，否则不会触发全分区过滤逻辑，直接返回0行结果。
解决方法：查询选项中新增allowFiltering: true配置：

const options = { 
  consistency: types.consistencies.localOne,
  allowFiltering: true
};

3. 键值转义/绑定错误 #

检查Node.js代码中KeyA的取值是否和控制台输入完全一致：如果代码中使用了参数绑定或者字符串拼接，可能存在特殊字符转义、多余空格/引号、编码不匹配的问题，导致实际发送到服务端的查询条件和控制台执行的不一致。你可以开启驱动的debug日志，打印实际下发的查询语句和参数做核对。

4. 分页参数默认值问题 #

cassandra-driver默认开启自动分页，默认单次拉取数据量可能小于你扫描到匹配数据需要的分区范围，导致第一页返回空结果。可以显式设置fetchSize参数和LIMIT值一致，验证是否是分页逻辑导致的问题。

该问题不属于AWS侧服务故障，也不是cassandra-driver的核心功能bug，基本都是Node.js侧和控制台的查询配置未对齐导致的，优先排查前两项配置即可解决90%以上的同类问题。

内容的提问来源于stack exchange，提问作者Miguel Angel Acevedo