Sanity Embeddings: Semantic Search in a Next.js App Router Site
By Nayan Kyada · · 6 min read
Part of The Sanity + Next.js Guide
Sanity Embeddings semantic search in Next.js is one of those features that looks complicated from the outside but is surprisingly lean to wire up once you understand the moving parts. This post covers the current native Embeddings feature built into Sanity datasets — not the older Embeddings Index API, which Sanity is sunsetting. If you found a guide that talks about a separate embeddings-index resource you have to provision via the Management API, it is stale; skip it.
What Sanity Embeddings actually is
Sanity's dataset embeddings feature lets you turn on vector indexing for a dataset directly. Sanity handles the embedding model and the vector store; you never manage a separate service. Queries use the text::semanticSimilarity() GROQ function inside score(), which takes a natural-language string and ranks documents by semantic similarity. According to Sanity's docs, dataset embeddings are available on all plans; generating embeddings is included, and semantic queries count against your organization's monthly semantic search quota (see sanity.io/pricing).
The workflow has three parts:
- Enable embeddings on the dataset (via the Sanity CLI or HTTP API), optionally scoped with a projection.
- Run a semantic query from your Next.js route handler using the Sanity client.
- Render the results in a search UI component.
Setting up the embeddings index in your dataset
Embeddings are enabled per dataset with the Sanity CLI. Use a projection to scope what gets embedded — for a blog you would typically embed only post documents and the fields people actually search against:
sanity datasets embeddings enable production --projection='{ _type == "post" => { title, excerpt, body } }'
sanity datasets embeddings status productionDocument types not listed in a conditional projection are not embedded. Sanity generates embeddings for existing documents asynchronously (the status command shows ready when it's done), and afterwards keeps them up to date automatically when documents change — usually within a minute or so. You do not configure that yourself.
There is no application code required for the indexing step. There's also no index name to remember: the query runs against whichever dataset your client points at.
Querying embeddings from a Next.js route handler
Create a route handler that accepts a search term, fires the semantic query against Sanity, and returns JSON. Using a server-side route handler keeps your Sanity read token out of the browser.
// app/api/search/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@sanity/client';
const client = createClient({
projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
apiVersion: '2024-09-01',
useCdn: false,
token: process.env.SANITY_API_READ_TOKEN,
});
export async function GET(req: NextRequest) {
const q = req.nextUrl.searchParams.get('q')?.trim();
if (!q) return NextResponse.json({ results: [] });
// text::semanticSimilarity() is only valid inside score().
// The filter restricts which documents are scored; the slice caps the result count.
const results = await client.fetch(
`*[_type == "post"] | score(text::semanticSimilarity($query)) | order(_score desc) [0...6] {
_id,
_type,
title,
"slug": slug.current,
excerpt
}`,
{ query: q }
);
return NextResponse.json({ results });
}A few things worth noting here. The [0...6] slice caps the number of results — keep it small to keep the UI fast. Each semantic query counts against your plan's semantic search quota, which is another reason to only fire it from the server and after a debounce. The read token is only needed if your dataset is private; keeping the query in a route handler keeps it out of the browser either way.
If the dataset does not have embeddings enabled, a text::semanticSimilarity() query returns an error — you will see a clear error in the logs rather than silent empty results.
Building the search UI in App Router
The UI is a client component so the user can type without a full page reload. It calls the route handler with a debounced fetch and renders results as they arrive.
// components/SemanticSearch.tsx
'use client';
import { useRef, useState, useTransition } from 'react';
type Result = {
_id: string;
_type: string;
title: string;
slug: string;
excerpt?: string;
};
export function SemanticSearch() {
const [query, setQuery] = useState('');
const [results, setResults] = useState<Result[]>([]);
const [isPending, startTransition] = useTransition();
const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
function handleChange(value: string) {
setQuery(value);
if (debounceRef.current) clearTimeout(debounceRef.current);
if (value.length < 3) { setResults([]); return; }
// Debounce the embeddings fetch — it's a slower, non-cacheable query,
// so firing it on every keystroke would hammer the API needlessly.
debounceRef.current = setTimeout(() => {
startTransition(async () => {
const res = await fetch(`/api/search?q=${encodeURIComponent(value)}`);
const data = await res.json();
setResults(data.results ?? []);
});
}, 300);
}
return (
<div className="w-full max-w-xl">
<input
type="search"
value={query}
onChange={(e) => handleChange(e.target.value)}
placeholder="Search articles…"
className="w-full rounded-lg border border-neutral-300 px-4 py-2 text-sm"
/>
{isPending && <p className="mt-2 text-xs text-neutral-400">Searching…</p>}
{results.length > 0 && (
<ul className="mt-3 divide-y divide-neutral-100 rounded-lg border border-neutral-200">
{results.map((r) => (
<li key={r._id} className="px-4 py-3">
<a href={`/blog/${r.slug}`} className="font-medium text-neutral-900 hover:underline">
{r.title}
</a>
{r.excerpt && <p className="mt-0.5 text-xs text-neutral-500 line-clamp-2">{r.excerpt}</p>}
</li>
))}
</ul>
)}
</div>
);
}Drop <SemanticSearch /> into any server component page. Because the component is 'use client', the surrounding page stays static and the search widget hydrates independently.
Where semantic beats keyword search
Keyword search (including Algolia) matches on tokens. If a user types "how to improve site speed" and your article is titled "optimising Core Web Vitals", a keyword index will likely miss it. The embeddings query will surface it because the underlying vectors capture meaning, not just character sequences.
The trade-off is latency. A semantic query does noticeably more work than a plain GROQ filter, so expect it to be slower — measure it on your own dataset. That's why the component above debounces 300 ms before firing the fetch — searching on every keystroke would hammer the API for no benefit. The useTransition marks the fetch as non-urgent on top of that, so React will not block the input from updating while results load.
Caching and rate limits
Every semantic query counts toward your organization's monthly semantic search quota, and Sanity notes it may apply rate limits to embeddings-enabled datasets — check the current quotas on the pricing page before going to production. For sites with high search volume, a short-lived cache layer (Redis or Vercel KV, keyed by the query string) can take the pressure off. A 60-second TTL on popular queries is usually enough to flatten spikes without serving stale results.
Do not cache in the Next.js route handler with revalidate — the same cache key would be shared across users and the route has no user-specific data to protect, but query diversity makes server-side caching wasteful unless you observe repeated identical queries in your logs first.
Frequently asked questions
01What is Sanity's native Embeddings feature, and is the old Embeddings Index API still relevant?
Dataset embeddings let you enable vector indexing on a dataset itself (optionally scoped with a GROQ projection) — Sanity handles the embedding model and vector store, and you query it with `text::semanticSimilarity()` inside GROQ's `score()`. The older, separately-provisioned Embeddings Index API is being sunset; if a guide describes provisioning a separate `embeddings-index` resource via the Management API, it's describing the deprecated approach.
02Why does a Sanity embeddings search feel slower than a regular GROQ filter?
Because it's doing more work — the search term has to be embedded and compared against document vectors on every query, which is noticeably slower than a plain filter. Debounce the search input (300ms is a reasonable default) and consider a short-lived cache layer like Redis or Vercel KV for popular queries if search volume is high.