GROQ-запити в Sanity: від основ до просунутої оптимізації
Уявіть: ви будуєте headless-сайт на Sanity та Next.js. Контентна модель розрослася — 6 типів документів, складні зв'язки, динамічні зони. На першому ж промо-лендінгу ловите фрустрацію: N+1 запитів, вкладені fetch, а блок «схожі статті» завантажується 7 секунд. Ми зіткнулися з цим на проєкті великого медіапорталу: 12 секунд завантаження, 47 окремих запитів. Рішення — один GROQ-запит, який скоротив час до 0.8 секунди. Знайомо? Ми з таким працювали не раз.
GROQ (Graph-Relational Object Queries) — не REST, не SQL, не GraphQL. Він гнучкіший за REST для складних структур: проєкції, join через ->, умовні вибірки, агрегації — все в одному запиті без проблем N+1. Наша команда з понад п'ятирічним досвідом роботи з Sanity налаштувала десятки проєктів, скорочуючи навантаження на API до трьох разів. У цій статті покажемо, як правильно писати GROQ-запити, уникати типових помилок та оптимізувати швидкість.
Чому GROQ, а не REST чи GraphQL?
Sanity з коробки пропонує HTTP API, але кастомні ендпоїнти під кожну сторінку — шлях до хаосу. GROQ же дає єдиний синтаксис для будь-яких вибірок. Порівняйте:
| Критерій | GROQ | REST API | GraphQL |
|---|---|---|---|
| Кількість запитів на сторінку | 1 (один складний) | 5–15 (множинні) | 1–3 (але з проблемою N+1 при пагінації) |
| Join (resolve) | Вбудований -> |
Потребує окремих запитів | Потребує batch-завантаження |
| Умовні проєкції | Вбудований _type == "..." => |
Немає, доводиться фільтрувати на клієнті | Є, через фрагменти |
| Агрегації (count, unique) | Вбудовані функції | Немає, потрібні серверні хуки | Є, але складніше |
GROQ у 2–3 рази швидший при вибірці сторінок з кількома типами блоків — перевірено на наших проєктах.
Як правильно виконувати join-запити в GROQ?
Join у GROQ реалізується через оператор розв'язання ->. Він замінює реляційні JOIN і дозволяє підтягнути пов'язані документи без додаткових запитів. Покрокова інструкція:
- Визначте поле-посилання в документі (наприклад,
authorтипуreference). - Використовуйте оператор
->після поля:author->{name}. - Обмежте поля проєкцією, щоб не завантажувати зайві дані.
Приклад запиту за один прохід повертає пости разом з даними автора:
*[_type == "post"]{ title, "author": author->{name, "avatar": image.asset->url} } Глибину розв'язання варто обмежувати — на практиці вистачає двох-трьох рівнів.
Приклад з практики: оптимізація завантаження блогу
Одного разу клієнт звернувся з проблемою: сторінка блогу на Sanity + Next.js завантажувалася 12 секунд. Ми виявили, що для списку статей виконувалося 47 окремих запитів (кожен пост підтягував автора, категорії, схожі статті та метадані). Рішення — один GROQ-запит з resolve та пагінацією:
*[_type == "post" && status == "published"] | order(publishedAt desc) [$start...$end] { _id, title, "slug": slug.current, publishedAt, "author": author->{ name, "avatar": image.asset->url }, "categories": categories[]->{ title, "slug": slug.current }, "excerpt": string::slice(pt::text(body), 0, 200) } count(*[_type == "post" && status == "published"]) Результат: 1 запит, 0.8 секунди замість 12. Плюс бонус — підрахунок загальної кількості статей для пагінації. Подібні оптимізації ми закладаємо в стандартний набір запитів.
Що входить у налаштування GROQ-запитів
Ми пропонуємо розробку під ключ — від аудиту до документації. До пакету входить:
- Аналіз контентної моделі та виявлення вузьких місць (N+1, зайві запити)
- Проєктування універсальних запитів для 4–6 типів сторінок: лендінги, списки, детальна картка, пошук
- Реалізація з типізацією TypeScript — кожен запит обгорнутий у groq-тег і повертає коректний тип
- Оптимізація через проєкції, resolve та агрегації — мінімальний payload
- Інтеграція з Sanity Vision для налагодження та тестування
- Навчання команди — передаємо документацію та шаблони
Стандартний набір включає базовий синтаксис, параметризовані запити, Portable Text, пагінацію, fulltext-пошук з Algolia (якщо потрібно), та зворотні зв'язки (refs). Все це перевірено на 30+ проєктах.
Типові помилки при написанні GROQ
- Рядкова конкатенація замість параметрів — ризик ін'єкцій, відсутність кешування. Завжди використовуйте
$variable. - Надмірна вкладеність resolve — більше трьох рівнів веде до падіння продуктивності. Обмежуйтеся 2–3.
- Ігнорування
defined()при перевірці полів — у Sanity поля можуть бути null. - Відсутність пагінації на списках більше 100 елементів. Використовуйте
[$start...$end]. - Забули про лічильник — повертайте одночасно масив і count.
Приклад повного набору запитів (з типізацією)
import { createClient } from '@sanity/client' import { groq } from 'next-sanity' const postQuery = groq` *[_type == "post" && slug.current == $slug][0] { _id, title, "slug": slug.current, publishedAt, body, "author": author->{ name, "image": image.asset->url }, "relatedPosts": *[_type == "post" && references(^.categories[]._ref) && _id != ^._id] | order(publishedAt desc) [0...3] { title, "slug": slug.current } } ` type PostResult = { _id: string title: string slug: string publishedAt: string body: any[] author: { name: string; image: string } relatedPosts: { title: string; slug: string }[] } const post = await client.fetch<PostResult>(postQuery, { slug: params.slug }) Повну документацію по GROQ можна вивчити на офіційному сайті Sanity. Якщо хочете прискорити розробку — наші інженери готові допомогти з налаштуванням. Зв'яжіться з нами — обговоримо ваш проєкт і підберемо оптимальне рішення. Отримайте консультацію інженера по Sanity.
Строки та вартість
Розробка набору запитів займає від одного до трьох днів залежно від складності моделі. Вартість розраховується індивідуально. Ми не приховуємо цифр: пишіть — оцінимо ваш проєкт за один робочий день. Гарантуємо, що запити будуть оптимізовані під Core Web Vitals і не викличуть N+1.