The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
feat: Add edge function and hooks for search V2 (#51103)
Jeremias Menichelli99103b3571b0
diff --git a/apps/docs/app/api/search_v2/cors.ts b/apps/docs/app/api/search_v2/cors.tsnew file mode 100644index 00000000000..c7243dfacd1--- /dev/null+++ b/apps/docs/app/api/search_v2/cors.ts@@ -0,0 +1,5 @@+export const corsHeaders = {+ 'Access-Control-Allow-Origin': '*',+ 'Access-Control-Allow-Methods': 'GET, OPTIONS',+ 'Access-Control-Allow-Headers': 'content-type',+}diff --git a/apps/docs/app/api/search_v2/route.ts b/apps/docs/app/api/search_v2/route.tsnew file mode 100644index 00000000000..94030052ef7--- /dev/null+++ b/apps/docs/app/api/search_v2/route.ts@@ -0,0 +1,32 @@+import { supabaseSearchV2 } from '~/scripts/search_v2/client'+import { type NextRequest } from 'next/server'++import { corsHeaders } from './cors'++export const runtime = 'edge'++export async function OPTIONS() {+ return new Response(null, { headers: corsHeaders })+}++export async function GET(request: NextRequest) {+ const { searchParams } = new URL(request.url)+ const query = searchParams.get('q')?.trim()+ const limit = Number(searchParams.get('limit')) || 10++ if (!query) {+ return Response.json({ error: 'Missing q parameter' }, { status: 400, headers: corsHeaders })+ }++ const { data, error } = await supabaseSearchV2().rpc('search_docs', {+ query_text: query,+ match_limit: limit,+ })++ if (error) {+ console.error('Error running docs search v2:', error)+ return Response.json({ error: error.message }, { status: 500, headers: corsHeaders })+ }++ return Response.json(data, { headers: corsHeaders })+}diff --git a/apps/docs/features/SearchV2/SearchV2.utils.test.tsx b/apps/docs/features/SearchV2/SearchV2.utils.test.tsxnew file mode 100644index 00000000000..d79b031082c--- /dev/null+++ b/apps/docs/features/SearchV2/SearchV2.utils.test.tsx@@ -0,0 +1,79 @@+import { load } from 'cheerio'+import { renderToStaticMarkup } from 'react-dom/server'+import { describe, expect, it } from 'vitest'++import { formatHeadingPath, highlightMatches } from './SearchV2.utils'++describe('formatHeadingPath', () => {+ it('joins multiple headings with " > "', () => {+ expect(formatHeadingPath(['Title 1', 'Title 2'])).toBe('Title 1 > Title 2')+ })++ it('returns a single-element path unchanged', () => {+ expect(formatHeadingPath(['Title 1'])).toBe('Title 1')+ })++ it('returns an empty string for an empty path', () => {+ expect(formatHeadingPath([])).toBe('')+ })+})++function renderHighlight(text: string, query: string) {+ const result = highlightMatches(text, query)+ if (typeof result === 'string') return { html: result, strongTexts: [] as string[] }++ const html = renderToStaticMarkup(<>{result}</>)+ const $ = load(html)+ return {+ html: $.root().text(),+ strongTexts: $('strong')+ .map((_, el) => $(el).text())+ .get(),+ }+}++describe('highlightMatches', () => {+ it('highlights a single case-insensitive partial match', () => {+ const result = highlightMatches('Bring your own MCP', 'mcp server')+ expect(typeof result).not.toBe('string')++ const { strongTexts, html } = renderHighlight('Bring your own MCP', 'mcp server')+ expect(strongTexts).toEqual(['MCP'])+ expect(html).toBe('Bring your own MCP')+ })++ it('highlights multiple non-overlapping token matches independently', () => {+ const { strongTexts } = renderHighlight('MCP servers for your server', 'mcp server')+ expect(strongTexts).toEqual(['MCP', 'server', 'server'])+ })++ it('merges overlapping/adjacent matches into a single run', () => {+ const { strongTexts } = renderHighlight('server', 'server serv')+ expect(strongTexts).toEqual(['server'])+ })++ it('returns the original string unchanged when there is no match', () => {+ const result = highlightMatches('Bring your own MCP', 'unrelated')+ expect(result).toBe('Bring your own MCP')+ })++ it('is case-insensitive but preserves the original casing of the matched text', () => {+ const { strongTexts } = renderHighlight('Bring your own MCP', 'MCP')+ expect(strongTexts).toEqual(['MCP'])+ })++ it('returns the text unchanged for an empty or whitespace-only query', () => {+ expect(highlightMatches('Bring your own MCP', '')).toBe('Bring your own MCP')+ expect(highlightMatches('Bring your own MCP', ' ')).toBe('Bring your own MCP')+ })++ it('excludes common prepositions/articles/conjunctions from highlighting', () => {+ const { strongTexts } = renderHighlight('The best MCP server for you', 'the mcp server')+ expect(strongTexts).toEqual(['MCP', 'server'])+ })++ it('returns the text unchanged when the query is made up entirely of ignored words', () => {+ const result = highlightMatches('The best MCP server', 'the of')+ expect(result).toBe('The best MCP server')+ })+})diff --git a/apps/docs/features/SearchV2/SearchV2.utils.tsx b/apps/docs/features/SearchV2/SearchV2.utils.tsxnew file mode 100644index 00000000000..d7db0f83e3c--- /dev/null+++ b/apps/docs/features/SearchV2/SearchV2.utils.tsx@@ -0,0 +1,86 @@+import type { ReactNode } from 'react'++/** Common English prepositions/articles/conjunctions, excluded from highlighting so a query like "the mcp server" doesn't bold "the". */+const IGNORED_WORDS = new Set([+ 'a',+ 'an',+ 'the',+ 'and',+ 'or',+ 'but',+ 'of',+ 'in',+ 'on',+ 'at',+ 'to',+ 'for',+ 'from',+ 'by',+ 'with',+ 'as',+])++/** Join a heading breadcrumb into a single display string, e.g. ['Title 1', 'Title 2'] -> 'Title 1 > Title 2'. */+function formatHeadingPath(headingPath: string[]): string {+ return headingPath.join(' > ')+}++/** Case-insensitive, whitespace-split match ranges for every occurrence of every query token in text. */+function getMatchRanges(text: string, query: string): Array<[number, number]> {+ const tokens = query+ .split(/\s+/)+ .map((token) => token.trim())+ .filter((token) => token.length > 0 && !IGNORED_WORDS.has(token.toLowerCase()))+ if (tokens.length === 0) return []++ const lowerText = text.toLowerCase()+ const ranges: Array<[number, number]> = []++ for (const token of tokens) {+ const lowerToken = token.toLowerCase()+ let fromIndex = 0+ while (fromIndex <= lowerText.length) {+ const idx = lowerText.indexOf(lowerToken, fromIndex)+ if (idx === -1) break+ ranges.push([idx, idx + lowerToken.length])+ fromIndex = idx + lowerToken.length+ }+ }++ if (ranges.length === 0) return []++ ranges.sort((a, b) => a[0] - b[0])+ const merged: Array<[number, number]> = [ranges[0]]+ for (const [start, end] of ranges.slice(1)) {+ const last = merged[merged.length - 1]+ if (start <= last[1]) {+ last[1] = Math.max(last[1], end)+ } else {+ merged.push([start, end])+ }+ }+ return merged+}++/**+ * Highlight every case-insensitive, per-word partial match of `query` inside `text`.+ * Returns the plain string when there's no match, otherwise a fragment with matches+ * wrapped in <strong>, preserving the original casing of `text`.+ */+function highlightMatches(text: string, query: string): ReactNode {+ const ranges = getMatchRanges(text, query)+ if (ranges.length === 0) return text++ const nodes: ReactNode[] = []+ let cursor = 0+ ranges.forEach(([start, end], i) => {+ if (start > cursor) nodes.push(text.slice(cursor, start))+ nodes.push(<strong key={i}>{text.slice(start, end)}</strong>)+ cursor = end+ })+ if (cursor < text.length) nodes.push(text.slice(cursor))++ return <>{nodes}</>+}++export { formatHeadingPath, highlightMatches }diff --git a/apps/docs/features/SearchV2/SearchV2Dialog.tsx b/apps/docs/features/SearchV2/SearchV2Dialog.tsxindex f49a27c5c77..ee12c97675a 100644--- a/apps/docs/features/SearchV2/SearchV2Dialog.tsx+++ b/apps/docs/features/SearchV2/SearchV2Dialog.tsx@@ -1,10 +1,10 @@'use client'-import { useDocsSearch, type DocsSearchResult } from 'common'+import { useDocsSearchV2, type DocsSearchV2Result } from 'common'import { Loader2 } from 'lucide-react'import { useRouter } from 'next/navigation'import { VisuallyHidden } from 'radix-ui'-import { useEffect } from 'react'+import { useEffect, useState } from 'react'import {Command,CommandEmpty,@@ -18,6 +18,8 @@ import {DialogTitle,} from 'ui'+import { formatHeadingPath, highlightMatches } from './SearchV2.utils'+interface SearchV2DialogProps {open: booleanonOpenChange: (open: boolean) => void@@ -25,14 +27,25 @@ interface SearchV2DialogProps {export function SearchV2Dialog({ open, onOpenChange }: SearchV2DialogProps) {const router = useRouter()- const { searchState, handleDocsSearchDebounced, resetSearch } = useDocsSearch()+ const { searchState, handleDocsSearchDebounced, resetSearch } = useDocsSearchV2()+ const [highlightQuery, setHighlightQuery] = useState('')// Clear stale results once the dialog closesuseEffect(() => {if (!open) resetSearch()}, [open, resetSearch])- const results: DocsSearchResult[] =+ // Only update the highlighted query once a new result set actually lands, so highlights+ // don't shift on every keystroke while the debounced search is still in flight.+ useEffect(() => {+ if (searchState.status === 'results' || searchState.status === 'noResults') {+ setHighlightQuery(searchState.query)+ } else if (searchState.status === 'initial') {+ setHighlightQuery('')+ }+ }, [searchState])++ const results: DocsSearchV2Result[] ='results' in searchState? searchState.results: 'staleResults' in searchState@@ -107,16 +120,18 @@ export function SearchV2Dialog({ open, onOpenChange }: SearchV2DialogProps) {<CommandGroup heading="Results" forceMount>{results.map((page) => (<CommandItem- key={page.id}- value={String(page.id)}+ key={page.path}+ value={page.path}forceMountonSelect={() => handleSelect(page.path)}><div className="flex flex-col">- <span className="text-sm">{page.title}</span>- {(page.description || page.subtitle) && (+ <span className="text-sm">+ {highlightMatches(formatHeadingPath(page.headingPath), highlightQuery)}+ </span>+ {page.excerpt && (<span className="text-xs text-foreground-muted">- {page.description || page.subtitle}+ {highlightMatches(page.excerpt, highlightQuery)}</span>)}</div>diff --git a/apps/docs/features/SearchV2/useSearchV2Variant.ts b/apps/docs/features/SearchV2/useSearchV2Variant.tsindex d9f515dc4cb..7615e6a86b3 100644--- a/apps/docs/features/SearchV2/useSearchV2Variant.ts+++ b/apps/docs/features/SearchV2/useSearchV2Variant.ts@@ -3,7 +3,6 @@import { useFeatureFlags, useSearchParamsShallow } from 'common'import { SEARCH_V2_FLAG, type SearchV2Variant } from './constants'-import { IS_PRODUCTION } from '@/lib/constants'const VARIANTS: SearchV2Variant[] = ['control', 'search-v2-active']diff --git a/apps/docs/scripts/search_v2/client.ts b/apps/docs/scripts/search_v2/client.tsnew file mode 100644index 00000000000..cfc7a6a8846--- /dev/null+++ b/apps/docs/scripts/search_v2/client.ts@@ -0,0 +1,40 @@+import { createClient, type SupabaseClient } from '@supabase/supabase-js'++// Search V2 lives in its own Supabase project (see ./sql/setup.sql), separate from the main+// docs content DB `lib/supabase.ts` connects to — so it needs its own client and its own+// hand-written Database type (there's no generated schema for this project).+export type Database = {+ public: {+ Tables: Record<string, never>+ Views: Record<string, never>+ Functions: {+ search_docs: {+ Args: { query_text: string; match_limit?: number }+ Returns: Array<{+ slug: string+ page_title: string+ heading: string+ heading_level: number+ heading_path: string[]+ excerpt: string+ score: number+ }>+ }+ }+ Enums: Record<string, never>+ CompositeTypes: Record<string, never>+ }+}++let _supabaseSearchV2: SupabaseClient<Database>++export function supabaseSearchV2() {+ if (!_supabaseSearchV2) {+ _supabaseSearchV2 = createClient<Database>(+ `https://${process.env.SEARCH_V2_SUPABASE_PROJECT_ID}.supabase.co`,+ process.env.SEARCH_V2_SUPABASE_SECRET_KEY!+ )+ }++ return _supabaseSearchV2+}diff --git a/apps/docs/turbo.jsonc b/apps/docs/turbo.jsoncindex 187126ea25b..e91e7301a8e 100644--- a/apps/docs/turbo.jsonc+++ b/apps/docs/turbo.jsonc@@ -82,6 +82,8 @@"LOGFLARE_INGESTION_API_KEY","LOGFLARE_SOURCE_TOKEN","OPENAI_API_KEY",+ "SEARCH_V2_SUPABASE_PROJECT_ID",+ "SEARCH_V2_SUPABASE_SECRET_KEY","SITE_NAME","SUPABASE_SECRET_KEY",],diff --git a/packages/common/hooks/index.ts b/packages/common/hooks/index.tsindex a4b85a25c79..23bbecba6a7 100644--- a/packages/common/hooks/index.ts+++ b/packages/common/hooks/index.ts@@ -7,6 +7,7 @@ export * from './useCopy'export * from './useCopyMarkdownFromUrl'export * from './useDebounce'export * from './useDocsSearch'+export * from './useDocsSearchV2'export * from './useDragToClose'export * from './useEffectEvent'export * from './useIsomorphicLayoutEffect'diff --git a/packages/common/hooks/useDocsSearchV2.ts b/packages/common/hooks/useDocsSearchV2.tsnew file mode 100644index 00000000000..57ecd61aeeb--- /dev/null+++ b/packages/common/hooks/useDocsSearchV2.ts@@ -0,0 +1,140 @@+'use client'++import { compact, debounce } from 'lodash'+import { useCallback, useMemo, useReducer, useRef } from 'react'++// This app's own base path, set only for apps deployed under a path prefix (docs' is '/docs').+const BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH ?? ''+// Public URL of the docs deployment, which hosts the search API routes.+const DOCS_URL = process.env.NEXT_PUBLIC_DOCS_URL || 'https://supabase.com/docs'+// From inside the docs app itself, call our own routes relatively; from studio/www, call docs directly.+const SEARCH_API_BASE = BASE_PATH === '/docs' ? BASE_PATH : DOCS_URL++interface DocsSearchV2Result {+ path: string+ title: string+ heading: string+ excerpt: string+ headingPath: string[]+ score: number+}++type SearchState =+ | { status: 'initial'; key: number }+ | { status: 'loading'; key: number; staleResults: DocsSearchV2Result[] }+ | { status: 'results'; key: number; results: DocsSearchV2Result[]; query: string }+ | { status: 'noResults'; key: number; query: string }+ | { status: 'error'; key: number; message: string }++type Action =+ | { type: 'resultsReturned'; key: number; results: DocsSearchV2Result[]; query: string }+ | { type: 'newSearchDispatched'; key: number }+ | { type: 'reset'; key: number }+ | { type: 'errored'; key: number; message: string }++function reshapeResult(row: unknown): DocsSearchV2Result | null {+ if (typeof row !== 'object' || row === null) return null+ if (+ !(+ 'slug' in row &&+ 'page_title' in row &&+ 'heading' in row &&+ 'excerpt' in row &&+ 'heading_path' in row &&+ 'score' in row+ )+ )+ return null++ const slug = row.slug as string+ return {+ // Next's router already prepends the app's basePath ('/docs'), so don't add it here.+ path: slug ? `/${slug}` : '/',+ title: row.page_title as string,+ heading: row.heading as string,+ excerpt: row.excerpt as string,+ headingPath: row.heading_path as string[],+ score: row.score as number,+ }+}++function reducer(state: SearchState, action: Action): SearchState {+ // Ignore responses from outdated async functions+ if (state.key > action.key) {+ return state+ }+ switch (action.type) {+ case 'resultsReturned':+ return action.results.length+ ? { status: 'results', key: action.key, results: action.results, query: action.query }+ : { status: 'noResults', key: action.key, query: action.query }+ case 'newSearchDispatched':+ return {+ status: 'loading',+ key: action.key,+ staleResults:+ 'results' in state ? state.results : 'staleResults' in state ? state.staleResults : [],+ }+ case 'reset':+ return { status: 'initial', key: action.key }+ case 'errored':+ return { status: 'error', key: action.key, message: action.message }+ default:+ return state+ }+}++const useDocsSearchV2 = () => {+ const [state, dispatch] = useReducer(reducer, { status: 'initial', key: 0 })+ const key = useRef(0)++ const handleSearch = useCallback(async (query: string) => {+ key.current += 1+ const localKey = key.current+ dispatch({ type: 'newSearchDispatched', key: localKey })++ try {+ const params = new URLSearchParams({ q: query.trim() })+ const response = await fetch(`${SEARCH_API_BASE}/api/search_v2?${params}`)+ const data = await response.json()+ if (!Array.isArray(data)) {+ throw new Error(data?.error ?? "didn't get expected results array")+ }+ dispatch({+ type: 'resultsReturned',+ key: localKey,+ results: compact(data.map(reshapeResult)),+ query: query.trim(),+ })+ } catch (error) {+ console.error(`[ERROR] Error fetching docs search v2 results: ${error}`)+ dispatch({+ type: 'errored',+ key: localKey,+ message: error instanceof Error ? error.message : '',+ })+ }+ }, [])++ const debouncedSearch = useMemo(() => debounce(handleSearch, 250), [handleSearch])++ const debounceCancel = useCallback(() => {+ debouncedSearch.cancel()+ }, [debouncedSearch])++ const resetSearch = useCallback(() => {+ debounceCancel()+ key.current += 1+ dispatch({ type: 'reset', key: key.current })+ }, [debounceCancel])++ return {+ searchState: state,+ handleDocsSearch: handleSearch,+ handleDocsSearchDebounced: debouncedSearch,+ resetSearch,+ }+}++export { useDocsSearchV2 }+export type { DocsSearchV2Result }