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