cbq是Couchbase官方随服务端一起发布的命令行查询Shell，底层通过N1QL（现在的SQL++）接口与集群通信。相比Web控制台，它更适合脚本化操作和远程排查，比如批量执行语句、分析执行计划、定位慢查询。本文从安装启动讲起，介绍连接集群的方式、常用Shell命令、N1QL查询实战以及故障排查技巧。
一、安装与启动cbq
cbq工具位于Couchbase安装目录的bin文件夹下，例如Linux默认路径为/opt/couchbase/bin/cbq，Windows则是C:\Program Files\Couchbase\Server\bin\cbq.exe。服务端安装完成后无需额外下载，直接进入该目录执行即可。如果只在客户端机器上操作，也可以单独安装Couchbase Shell工具包获得cbq。
启动方式有两种：一种是直接输入cbq进入交互模式，随后在Shell内部使用\connect命令连接集群；另一种是在启动时通过参数指定目标地址和凭证，一步到位完成连接，这种方式更适合写进自动化脚本。
cd /opt/couchbase/bin ./cbq -u Administrator -p password -e couchbase://127.0.0.1
参数含义很直观：-u指定用户名，-p指定密码，-e指定集群地址。如果集群启用了TLS，地址需要写成couchbases://并配合CA证书参数。连接成功后会出现cbq>提示符，表示可以输入查询语句了。
二、常用Shell命令
cbq的命令分为两类：以反斜杠开头的Shell命令，以及标准的N1QL语句。Shell命令用于控制会话环境，常用的有下面几个。
\connect：连接或切换集群，例如\connect couchbase://192.168.1.10\disconnect：断开当前连接\set：设置会话参数，如\set -timeout 120s\quit或\exit：退出Shell\source：执行外部脚本文件中的语句，适合批量初始化\help：查看帮助
其中\set值得多说一句。它可以在会话级别覆盖查询设置，比如控制超时时间，或者切换命名上下文的\set -query-context travel-sample.inventory。切换上下文后，查询时可以省略bucket和scope前缀，直接写SELECT * FROM airline，大大减少重复输入。
\source命令对批量初始化特别有用。把建索引、插入样例数据的语句写进一个文本文件，用\source /path/init.n1ql一次执行完毕，比在Web控制台逐条粘贴效率高得多。
三、N1QL查询实战
N1QL语法接近标准SQL，最大的特点是对JSON文档模型的支持。先看一个基础例子，从travel-sample示例桶中查询航线数据。
SELECT name, iata, country FROM `travel-sample`.inventory.airline WHERE country = "United States" LIMIT 5;
注意bucket名称需要用反引号包裹，因为travel-sample包含连字符，不包裹会被解析成减法运算。嵌套字段可以用点号直接访问，配合UNNEST可以把数组展开成多行，这是处理JSON数组最常用的手段。
SELECT s.schedule[0].day AS first_day, r.airline FROM `travel-sample`.inventory.route AS r UNNEST r.schedule AS s WHERE r.airlineid = "airline_10" LIMIT 10;
聚合查询同样支持GROUP BY和HAVING，写法与SQL基本一致。需要提醒的是，如果查询条件没有索引覆盖，集群会报错提示缺少索引，这是Couchbase与MySQL等传统数据库的一个重要差异：没有匹配的索引时，N1QL默认拒绝执行全桶扫描，除非使用USE KEYS指定文档主键。
四、索引管理与执行计划分析
cbq也是管理索引的主要入口。创建索引使用CREATE INDEX，支持复合索引和部分索引。
CREATE INDEX idx_airline_country ON `travel-sample`.inventory.airline(country, name); -- 查看索引状态 SELECT * FROM system:indexes WHERE keyspace_id = "airline";
排查慢查询离不开执行计划。在语句前加上EXPLAIN可以查看查询会走哪个索引、估算的代价等关键信息。观察输出中的算子一项，如果出现SequentialScan说明走了顺序扫描，通常意味着索引设计有问题，需要针对WHERE条件调整索引字段顺序。
此外，system:keyspaces、system:nodes等系统键空间能查到集群元数据，在排查节点状态和桶结构时非常实用，建议日常多加利用。
五、常见问题与解决
使用cbq时最常见的报错是连接失败，提示connection refused。多数情况是查询服务没有在目标节点上启用，可以到Web控制台的Services页面确认该节点是否运行Query服务。其次是认证失败，新版Couchbase已不支持匿名访问，务必携带用户名密码。
超时问题也时有发生，表现为查询返回timeout错误。可以先用\set -timeout 300s延长超时时间观察是否只是数据量太大，再结合EXPLAIN结果优化索引。如果查询结果中文显示为乱码，一般是终端编码问题，把SSH客户端字符集调整为UTF-8即可。退出时如果Shell卡住，可以按Ctrl+C中断当前语句，再用\quit退出。