Sanity GROQ怎么用 内容查询语言教程

Sanity GROQ是Sanity的内容查询语言，类似GraphQL，可以精准查询需要的数据，适合做复杂内容筛选和展示。它直接面向Sanity内容库中的文档，能筛选、排序并整理结果，也可以沿着引用关系读取关联内容。下面从基础语法开始，逐步写出可用于文章列表的查询，再介绍聚合与字段投影。建议先在Sanity Studio的Vision工具中运行示例，确认字段名称和返回结果与你的内容模型一致。

第一步：了解GROQ基础语法

先记住最常见的结构：星号代表从内容库中选择文档，方括号用来写筛选条件，花括号用来指定返回字段。比如 *[_type == “post”] 表示找出类型为post的文档。Sanity文档通常通过_type区分类型；字段名要和你的schema保持一致，大小写也要匹配。刚开始可以先只查询一种内容类型，避免结果里混入不相关文档。

接着在方括号里添加条件。等于用==，不等于用!=，大于或小于可以用>、<，多个条件可用&&表示同时满足，用||表示满足其中一项。例如 *[_type == “post” && defined(title)] 会筛选有标题的文章。defined()适合检查字段是否存在；如果条件较多，使用括号明确逻辑顺序，方便自己检查，也减少筛选结果出错。

查询可以逐步组合，不必一开始写得很复杂。先确认内容类型，再增加字段条件，最后才加入排序、分页或引用解析。示例中的post、title、publishedAt都只是常见字段名，不一定与你的项目相同。运行查询后如果结果为空，先检查文档类型、字段拼写和字段值，再确认当前查询的数据集里是否已有符合条件的内容。

第二步：编写基础查询

以文章列表为例，先查询全部文章：*[_type == “post”]。若只需要标题和发布日期，可写成 *[_type == “post”]{title, publishedAt}。在Vision里粘贴查询并执行，观察结果是否为预期字段。只取页面真正需要的数据，能让返回结构更清楚，也避免把整篇正文、图片元数据等暂时用不到的内容一并取回。

如果要查一篇指定文章，可以按slug筛选，例如 *[_type == “post” && slug.current == $slug][0]{title, body}。这里的$slug是参数占位符，实际请求时传入具体值；末尾的[0]表示取匹配结果中的第一条，适合查询单篇详情。参数化写法能让查询模板重复使用，也比把用户输入直接拼进查询字符串更稳妥。

使用过滤和排序

需要筛选已发布文章时，可以组合条件，例如 *[_type == “post” && defined(publishedAt)]；若还要限定日期，可继续添加日期比较条件。搜索标题可使用match，例如 *[_type == “post” && title match “GROQ*”]。match用于文本匹配，星号可表达前缀匹配；它与严格相等不同，适合在内容字段中查找符合关键词模式的文档。

筛选后用管道符接order排序，例如 *[_type == “post”] | order(publishedAt desc)，desc代表降序，asc代表升序。要限制列表长度，可在排序后添加范围切片，例如 [0…10]获取前十条，再接投影字段。把筛选、排序、切片按顺序组合，能得到适合列表页的数据；注意切片范围的结束位置不包含在结果中。

第三步：聚合和投影字段

投影就是用花括号选择并整理输出字段。比如 {title, “slug”: slug.current}会保留title，并把slug.current映射到返回结果里的slug字段。字段前加引号并使用冒号，可为计算值或嵌套路径起一个清晰名称。若确实需要原文档的全部字段，可以写{…}，但生产查询通常优先列出页面需要的字段，便于控制返回数据。

聚合常用于统计数组项目数量，例如 *[_type == “post”]{“tagCount”: count(tags)}会为每篇文章返回标签数量。要统计符合条件的文档，可以把筛选结果传给count，例如 count(*[_type == “post” && defined(publishedAt)])。聚合前先确认目标是统计文档、数组元素还是满足筛选条件的项目，避免把不同层级的数据混在一起。

Sanity内容常通过引用字段关联作者或分类。在投影里可以用箭头解析引用，例如 {“authorName”: author->name}；引用数组则可写 authors[]->{name}，只取每位作者的姓名。若页面需要作者头像或分类slug，也可以继续扩展投影。写完后检查引用是否真实存在，并确认关联文档中的字段名称正确。

最后，建议把复杂查询拆成清晰的几段：先写筛选，再排序和分页，最后投影字段；每次只增加一个功能并运行验证。排查问题时优先检查schema字段、引号、括号和数组路径。若在规划内容页面或原型时需要国内工具辅助，可了解墨刀AI；润灭也可作为相关内容制作流程中的参考。官网：modao.cgref.cn