Algolia Core Workflow B — Indexing & Data Sync

Overview

Keep your Algolia index synchronized with your source database. Covers full reindex, incremental updates, partial updates, synonyms, and query rules.

Prerequisites

• Completed algolia-install-auth setup
• Familiarity with algolia-core-workflow-a (search)
• Source database or API with change tracking (timestamps, events)

Instructions

Step 1: Full Reindex with replaceAllObjects

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// replaceAllObjects atomically swaps index content
// Internally: creates temp index → indexes all records → moves temp to target
// Search continues on old data until swap is complete — zero downtime
async function fullReindex(records: Record<string, any>[]) {
  const { taskID } = await client.replaceAllObjects({
    indexName: 'products',
    objects: records,
    batchSize: 1000,  // Records per batch (default 1000)
  });
  await client.waitForTask({ indexName: 'products', taskID });
  console.log(`Full reindex complete: ${records.length} records`);
}

Step 2: Incremental Updates with partialUpdateObject

// Only update changed fields — much faster than full saveObjects
async function updateProductPrice(objectID: string, newPrice: number) {
  await client.partialUpdateObject({
    indexName: 'products',
    objectID,
    attributesToUpdate: {
      price: newPrice,
      updated_at: new Date().toISOString(),
    },
    createIfNotExists: false,  // Don't create if missing
  });
}

// Batch partial updates
async function syncPriceChanges(changes: { id: string; price: number }[]) {
  const { taskID } = await client.partialUpdateObjects({
    indexName: 'products',
    objects: changes.map(c => ({
      objectID: c.id,
      price: c.price,
      updated_at: new Date().toISOString(),
    })),
    createIfNotExists: false,
  });
  await client.waitForTask({ indexName: 'products', taskID });
}

Step 3: Manage Synonyms

// Synonyms help users find products with different terminology
await client.saveSynonyms({
  indexName: 'products',
  synonymHit: [
    // Two-way synonym: any of these terms match each other
    {
      objectID: 'syn-1',
      type: 'synonym',
      synonyms: ['laptop', 'notebook', 'portable computer'],
    },
    // One-way synonym: "phone" also searches for "smartphone" but not reverse
    {
      objectID: 'syn-2',
      type: 'oneWaySynonym',
      input: 'phone',
      synonyms: ['smartphone', 'mobile phone', 'cell phone'],
    },
    

Algolia Cost Tuning

Overview

Algolia pricing is based on search requests and records. A search request is one API call (which may contain multiple queries via search({ requests: [...] })). Records are counted across all indices including replicas.

Pricing Structure (2025)

What Counts as Records

• Every object in every index = 1 record
• Standard replicas duplicate records (multiply your count)
• Virtual replicas share records (no extra cost)
• Synonyms and rules do NOT count as records

What Counts as Search Requests

• searchSingleIndex() = 1 request
• search({ requests: [q1, q2, q3] }) = 1 request (multi-query)
• browse() = 1 request per page
• saveObjects() = NOT a search request (indexing operations are free)

Instructions

Step 1: Audit Current Usage

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Check total records across all indices
const { items } = await client.listIndices();
let totalRecords = 0;
let replicaRecords = 0;

items.forEach(idx => {
  const records = idx.entries || 0;
  console.log(`${idx.name}: ${records.toLocaleString()} records, ${(idx.dataSize || 0 / 1024).toFixed(0)}KB`);
  if (idx.name.includes('_replica') || idx.primary) {
    replicaRecords += records;
  }
  totalRecords += records;
});

console.log(`\nTotal: ${totalRecords.toLocaleString()} records (${replicaRecords.toLocaleString()} in replicas)`);

Step 2: Replace Standard Replicas with Virtual Replicas

// Standard replicas: duplicate all records (doubles cost)
// Virtual replicas: share records with primary (no extra cost)

// BEFORE: 3 standard replicas = 4x record count
await client.setSettings({
  indexName: 'products',
  indexSettings: {
    replicas: [
      // 'products_price_asc',      // Standard: costs records
      // 'products_price_desc',     // Standard: costs records
      'virtual(products_price_asc)',  // Virtual: FREE
      'virtual(products_price_desc)', // Virtual: FREE
    ],
  },
});

// Virtual replica limitation:

Algolia Data Handling

Overview

Algolia stores your records in their cloud. You control what data goes in (via saveObjects), what comes back (via attributesToRetrieve), and what users can search (via searchableAttributes). For privacy compliance, you must filter PII before indexing and implement deletion workflows.

Data Flow: Source → Algolia → User

Source Database        Transform           Algolia Index           Search Response
┌──────────┐     ┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│ Full user │     │ Strip PII    │     │ Searchable       │     │ Retrieved    │
│ record    │ ──▶ │ Truncate     │ ──▶ │ fields only      │ ──▶ │ fields only  │
│ (all cols)│     │ Normalize    │     │ + ranking data   │     │ (UI needs)   │
└──────────┘     └──────────────┘     └──────────────────┘     └──────────────┘

Instructions

Step 1: Transform Records Before Indexing

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Define what goes into Algolia — NOT everything from your DB
interface AlgoliaProduct {
  objectID: string;
  name: string;
  description: string;     // Truncated, plain text
  category: string;
  brand: string;
  price: number;
  in_stock: boolean;
  image_url: string;
  rating: number;
  _tags: string[];
}

function transformForAlgolia(dbRecord: any): AlgoliaProduct {
  return {
    objectID: dbRecord.id,
    name: dbRecord.name,
    description: stripHtml(dbRecord.description).substring(0, 5000),
    category: dbRecord.category?.name || 'uncategorized',
    brand: dbRecord.brand?.name || '',
    price: dbRecord.price_cents / 100,
    in_stock: dbRecord.inventory_count > 0,
    image_url: dbRecord.images?.[0]?.url || '',
    rating: dbRecord.avg_rating || 0,
    _tags: buildTags(dbRecord),
  };
}

// Strip HTML tags for clean search text
function stripHtml(html: string): string {
  return html?.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim() || '';
}

function buildTags(record: any): string[] {
  const tags: string[] = [];
  if (record.is_featured) tags.push('featured');
  if (record.is_new) tags.push('new-arrival');
  if (record.discount_percent > 0) tags.push('on-sale');
  return tags;
}

Step 2: PII Detection and Filtering

// NEVER index PII unless absolutely necessary for search
const PII_FIELDS = ['email', 'phone', 'ssn', 'address', 'credit_card', 'password', 'api_key'];

function stripPII(record: Record<string, any>): Record<string, any> {
  const clean = { ...record };
  for (const field of PII_FIELDS) {
    delete clean[field];
  }
  return clean;
}

/

Algolia Debug Bundle

Overview

Collect all necessary diagnostic information for Algolia support tickets or internal troubleshooting. Uses real Algolia API endpoints to gather index stats, key permissions, and query performance data.

Prerequisites

• ALGOLIAAPPID and ALGOLIAADMINKEY environment variables set
• curl and jq available
• Permission to read API key ACLs and index settings

Instructions

Step 1: Create the Debug Bundle Script

#!/bin/bash
# algolia-debug-bundle.sh
set -euo pipefail

APP_ID="${ALGOLIA_APP_ID:?Set ALGOLIA_APP_ID}"
API_KEY="${ALGOLIA_ADMIN_KEY:?Set ALGOLIA_ADMIN_KEY}"
BUNDLE_DIR="algolia-debug-$(date +%Y%m%d-%H%M%S)"
BASE_URL="https://${APP_ID}-dsn.algolia.net"
HEADERS=(-H "X-Algolia-Application-Id: ${APP_ID}" -H "X-Algolia-API-Key: ${API_KEY}")

mkdir -p "$BUNDLE_DIR"

echo "=== Algolia Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" | tee -a "$BUNDLE_DIR/summary.txt"
echo "App ID: $APP_ID" | tee -a "$BUNDLE_DIR/summary.txt"

# 1. List all indices with record counts
echo "--- Indices ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "${BASE_URL}/1/indexes" "${HEADERS[@]}" \
  | jq '.items[] | {name, entries, dataSize, lastBuildTimeS}' \
  > "$BUNDLE_DIR/indices.json" 2>/dev/null
echo "Indices saved" >> "$BUNDLE_DIR/summary.txt"

# 2. Check API key permissions (redacted key)
echo "--- API Key ACL ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "${BASE_URL}/1/keys" "${HEADERS[@]}" \
  | jq '.keys[] | {description, acl, indexes, maxQueriesPerIPPerHour, validity}' \
  > "$BUNDLE_DIR/api-keys-acl.json" 2>/dev/null
echo "Key ACLs saved (keys redacted)" >> "$BUNDLE_DIR/summary.txt"

# 3. Get recent query logs (last 1000)
echo "--- Query Logs ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "${BASE_URL}/1/logs?length=100&type=all" "${HEADERS[@]}" \
  | jq '.logs[] | {timestamp, method, url, answer_code, processing_time_ms, query_nb_hits}' \
  > "$BUNDLE_DIR/query-logs.json" 2>/dev/null
echo "Last 100 log entries saved" >> "$BUNDLE_DIR/summary.txt"

# 4. Network connectivity test
echo "--- Network Diagnostics ---" >> "$BUNDLE_DIR/summary.txt"
for host in "${APP_ID}-dsn.algolia.net" "${APP_ID}-1.algolianet.com" "${APP_ID}-2.algolianet.com"; do
  RESULT=$(curl -s -o /dev/null -w "%{http_code},%{time_total}" "https://${host}/1/indexes" "

Algolia Deploy Integration

Overview

Deploy Algolia-powered applications to production platforms with proper API key separation (Admin on backend, Search-Only on frontend) and InstantSearch widget integration.

Prerequisites

• Algolia App ID + Admin key (backend) + Search-Only key (frontend)
• Platform CLI installed (vercel, fly, or gcloud)
• algoliasearch v5 for backend, react-instantsearch or instantsearch.js for frontend

Instructions

Step 1: Backend API Key Configuration

Vercel

# Environment variables in Vercel
vercel env add ALGOLIA_APP_ID production       # Your Application ID
vercel env add ALGOLIA_ADMIN_KEY production     # Admin key (server-side only)
vercel env add ALGOLIA_SEARCH_KEY production    # Search-only key (can be public)

# For client-side access (Next.js convention)
vercel env add NEXT_PUBLIC_ALGOLIA_APP_ID production
vercel env add NEXT_PUBLIC_ALGOLIA_SEARCH_KEY production

Fly.io

fly secrets set \
  ALGOLIA_APP_ID=YourApplicationID \
  ALGOLIA_ADMIN_KEY=your_admin_key \
  ALGOLIA_SEARCH_KEY=your_search_key

Google Cloud Run

# Store in Secret Manager
echo -n "your_admin_key" | gcloud secrets create algolia-admin-key --data-file=-
echo -n "your_search_key" | gcloud secrets create algolia-search-key --data-file=-

# Deploy with secrets mounted as env vars
gcloud run deploy search-service \
  --image gcr.io/$PROJECT_ID/search-service \
  --set-secrets=ALGOLIA_ADMIN_KEY=algolia-admin-key:latest,ALGOLIA_SEARCH_KEY=algolia-search-key:latest \
  --region us-central1

Step 2: Backend Search API (Next.js API Route)

// app/api/search/route.ts
import { algoliasearch } from 'algoliasearch';
import { NextRequest, NextResponse } from 'next/server';

const client = algoliasearch(
  process.env.ALGOLIA_APP_ID!,
  process.env.ALGOLIA_ADMIN_KEY!
);

export async function GET(request: NextRequest) {
  const query = request.nextUrl.searchParams.get('q') || '';
  const page = parseInt(request.nextUrl.searchParams.get('page') || '0');

  const { hits, nbHits, nbPages } = await client.searchSingleIndex({
    indexName: 'products',
    searchParams: {
      query,
      hitsPerPage: 20,
      page,
      attributesToRetrieve: ['name', 'price', 'image_url', 'category'],
      attributesToHighlight: ['name'],
    },
  });

  return NextResponse.json({ hits, totalHits: nbHits, totalPages: nbPages, page });
}

Step 3: Frontend with InstantSearch (React)

npm install react-instantsearch algoliasearch

// components/AlgoliaSearch.tsx
import

Algolia Enterprise RBAC

Overview

Algolia's access control is built on API keys with ACL (Access Control Lists). Each key has specific permissions, index restrictions, and rate limits. For multi-tenant apps, Secured API Keys provide per-user filtering without creating individual keys. For team management, Algolia's dashboard supports team members with role-based access.

API Key ACL Permissions

Instructions

Step 1: Define Application Roles

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Role definitions with minimal permissions
const ROLES = {
  // Backend search service: search only, scoped to specific indices
  searchService: {
    acl: ['search'] as const,
    description: 'Search service — production read-only',
    indexes: ['products', 'articles'],
    maxQueriesPerIPPerHour: 100000,
  },

  // Indexing pipeline: write records, no search or delete
  indexingPipeline: {
    acl: ['addObject', 'editSettings', 'listIndexes'] as const,
    description: 'Indexing pipeline — write-only, no delete',
    indexes: ['products', 'articles'],
    maxQueriesPerIPPerHour: 10000,
  },

  // Analytics dashboard: read analytics, no data access
  analyticsDashboard: {
    acl: ['analytics', 'usage', 'listIndexes'] as const,
    description: 'Analytics reader — no record access',
    indexes: ['products', 'articles'],
    maxQueriesPerIPPerHour: 5000,
  },

  // Data admin: full CRUD, 

Algolia Hello World

Overview

Index records into Algolia and search them back — the two fundamental operations. Uses the algoliasearch v5 client where all methods live on the client directly (no initIndex).

Prerequisites

• algoliasearch v5 installed (npm install algoliasearch)
• ALGOLIAAPPID and ALGOLIAADMINKEY environment variables set
• See algolia-install-auth for setup

Instructions

Step 1: Index Records with saveObjects

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(
  process.env.ALGOLIA_APP_ID!,
  process.env.ALGOLIA_ADMIN_KEY!
);

// saveObjects adds or replaces records. Each must have objectID
// (or Algolia auto-generates one).
const { taskID } = await client.saveObjects({
  indexName: 'movies',
  objects: [
    { objectID: '1', title: 'The Matrix', year: 1999, genre: 'sci-fi' },
    { objectID: '2', title: 'Inception', year: 2010, genre: 'sci-fi' },
    { objectID: '3', title: 'Pulp Fiction', year: 1994, genre: 'crime' },
  ],
});

// Wait for indexing to complete before searching
await client.waitForTask({ indexName: 'movies', taskID });
console.log('Indexing complete.');

Step 2: Search with searchSingleIndex

// Basic search — Algolia searches all searchableAttributes by default
const { hits } = await client.searchSingleIndex({
  indexName: 'movies',
  searchParams: { query: 'matrix' },
});

console.log(`Found ${hits.length} results:`);
hits.forEach(hit => {
  // _highlightResult shows which parts matched
  console.log(`  ${hit.title} (${hit.year})`);
});

Step 3: Configure Index Settings

// Settings define how Algolia ranks results
await client.setSettings({
  indexName: 'movies',
  indexSettings: {
    searchableAttributes: ['title', 'genre'],       // Fields to search
    attributesForFaceting: ['genre', 'year'],        // Filterable fields
    customRanking: ['desc(year)'],                   // Tie-breaker: newer first
    attributesToRetrieve: ['title', 'year', 'genre'],// Fields returned in hits
  },
});

Output

Indexing complete.
Found 1 results:
  The Matrix (1999)

Error Handling

#!/bin/bash
echo "=== ALGOLIA TRIAGE ==="

# 1. Is Algolia's infrastructure up?
echo -n "Algolia Status: "
curl -s https://status.algolia.com/api/v2/status.json | jq -r '.status.description'

# 2. Can we reach our Algolia app?
echo -n "API Connectivity: "
curl -s -o /dev/null -w "HTTP %{http_code} (%{time_total}s)" \
  "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" \
  -H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
  -H "X-Algolia-API-Key: ${ALGOLIA_ADMIN_KEY}"
echo ""

# 3. Can we actually search?
echo -n "Search test: "
curl -s "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes/products/query" \
  -H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
  -H "X-Algolia-API-Key: ${ALGOLIA_SEARCH_KEY}" \
  -d '{"query":"test","hitsPerPage":1}' | jq '{nbHits, processingTimeMS}'

# 4. Check index health
echo "Index stats:"
curl -s "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" \
  -H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
  -H "X-Algolia-API-Key: ${ALGOLIA_ADMIN_KEY}" \
  | jq '.items[] | {name, entries, lastBuildTimeS}'

Search returning errors?
├── YES: What HTTP status?
│   ├── 403: API key issue
│   │   ├── Key expired/deleted → Rotate key (see below)
│   │   └── Wrong key type → Use admin key for writes, search key for reads
│   ├── 404: Index doesn't exist
│   │   ├── Typo in index name → Check INDICES config
│   │   └── Index accidentally deleted → Trigger full reindex
│   ├── 429: Rate limited
│   │   ├── Per-key limit → Increase maxQueriesPerIPPerHour
│   │   └── Server limit → Reduce indexing batch frequency
│   └── 5xx: Algolia-side error
│       ├── status.algolia.com shows incident → Wait + enable fallback
│       └─

# Full client (Search + Analytics + Recommend + A/B Testing + Personalization)
npm install algoliasearch

# Or search-only (lighter bundle, frontend use)
npm install algoliasearch  # then import { liteClient } from 'algoliasearch/lite'

# Or individual API clients if you only need one
npm install @algolia/client-search
npm install @algolia/client-analytics
npm install @algolia/recommend

# .env (NEVER commit — add to .gitignore)
ALGOLIA_APP_ID=YourApplicationID
ALGOLIA_ADMIN_KEY=your_admin_api_key
ALGOLIA_SEARCH_KEY=your_search_only_api_key

# .gitignore
.env
.env.local
.env.*.local

// src/algolia/client.ts
import { algoliasearch } from 'algoliasearch';

// Backend — Admin client for indexing operations
const client = algoliasearch(
  process.env.ALGOLIA_APP_ID!,
  process.env.ALGOLIA_ADMIN_KEY!
);

// Frontend — Search-only client (safe to expose)
import { liteClient } from 'algoliasearch/lite';

const searchClient = liteClient(
  process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
  process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY!
);

// Quick verification: list indices
async function verifyAlgoliaConnection() {
  try {
    const { items } = await client.listIndices();
    console.log(`Connected. Found ${items.length} indices.`);
    return true;
  } catch (error) {
    console.error('Algolia connection failed:', error);
    return false;
  }
}

await verifyAlgoliaConnection();

// src/algolia/config.ts
import { algoliasearch } from 'algoliasearch';

const ENV = process.env.NODE_ENV || 'development';

// Each environment gets its own index prefix
export function indexName(base: string): string {
  if (ENV === 'production') return base;
  return `${ENV}_${base}`; // e.g., "development_products"
}

export const client = algoliasearch(
  process.env.ALGOLIA_APP_ID!,
  process.env.ALGOLIA_ADMIN_KEY!
);

// scripts/seed-algolia.ts
import { client, indexName } from '../src/algolia/config';

const SEED_DATA = [
  { objectID: 'prod-1', name: 'Widget A', category: 'tools', price: 29.99 },
  { objectID: 'prod-2', name: 'Widget B', category: 'tools', price: 49.99 },
  { objectID: 'prod-3', name: 'Gadget C', category: 'electronics', price: 199.99 },
];

async function seed() {
  const idx = indexName('products');

  // replaceAllObjects atomically swaps index content
  const { taskID } = await client.replaceAllObjects({
    indexName: idx,
    objects: SEED_DATA,
  });
  await client.waitForTask({ indexName: idx, taskID });

  // Configure settings for the dev index
  await client.setSettings({
    indexName: idx,
    indexSettings: {
      searchableAttributes: ['name', 'category'],
      attributesForFaceting: ['category', 'filterOnly(price)'],
      customRanking: ['asc(price)'],
    },
  });

  console.log(`Seeded ${SEED_DATA.length} records into ${idx}`);
}

seed().catch(console.error);

{
  "scripts": {
    "seed:algolia": "npx tsx scripts/seed-algolia.ts",
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch"
  }
}

// tests/algolia.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';

// Mock the entire algoliasearch module
vi.mock('algoliasearch', () => ({
  algoliasearch: vi.fn(() => ({
    searchSingleIndex: vi.fn().mockResolvedValue({
      hits: [
        { objectID: '1', name: 'Widget A', _highlightResult: {} },
      ],
      nbHits: 1,
      page: 0,
      nbPages: 1,
    })

# Find all search-related code
grep -rn "elasticsearch\|elastic\|typesense\|meilisearch\|\.search(" \
  --include="*.ts" --include="*.tsx" --include="*.js" src/ | wc -l

# Inventory current search features used
grep -rn "aggregations\|facets\|filters\|sort\|highlight\|suggest" \
  --include="*.ts" --include="*.tsx" src/

// Document current capabilities
interface MigrationAssessment {
  currentEngine: string;
  recordCount: number;
  indexCount: number;
  features: {
    fullTextSearch: boolean;
    faceting: boolean;
    filtering: boolean;
    geoSearch: boolean;
    synonyms: boolean;
    customRanking: boolean;
    analytics: boolean;
    abTesting: boolean;
    recommendations: boolean;
  };
  integrationPoints: string[];  // Files that call the search engine
  queryPatterns: string[];       // Types of queries used
}

// src/search/adapter.ts
// Abstraction layer — both engines implement the same interface

interface SearchResult<T> {
  hits: T[];
  totalHits: number;
  totalPages: number;
  currentPage: number;
  facets?: Record<string, Record<string, number>>;
  processingTimeMs: number;
}

interface SearchAdapter {
  search<T>(params: {
    index: string;
    query: string;
    filters?: string;
    facets?: string[];
    page?: number;
    hitsPerPage?: number;
  }): Promise<SearchResult<T>>;

  index(params: { index: string; records: Record<string, any>[] }): Promise<void>;
  delete(params: { index: string; ids: string[] }): Promise<void>;
}

// src/search/algolia-adapter.ts
import { algoliasearch, ApiError } from 'algoliasearch';

export class AlgoliaAdapter implements SearchAdapter {
  private client;

// src/algolia/config.ts
import { algoliasearch, type Algoliasearch } from 'algoliasearch';

type Environment = 'development' | 'staging' | 'production';

interface AlgoliaConfig {
  appId: string;
  apiKey: string;
  searchKey: string;
  environment: Environment;
}

function getConfig(): AlgoliaConfig {
  const env = (process.env.NODE_ENV || 'development') as Environment;

  return {
    appId: process.env.ALGOLIA_APP_ID!,
    apiKey: process.env.ALGOLIA_ADMIN_KEY!,
    searchKey: process.env.ALGOLIA_SEARCH_KEY!,
    environment: env,
  };
}

// Prefix index names with environment
export function indexName(base: string): string {
  const { environment } = getConfig();
  if (environment === 'production') return base;  // No prefix in prod
  return `${environment}_${base}`;
  // development_products, staging_products, products
}

let _client: Algoliasearch | null = null;

export function getClient(): Algoliasearch {
  if (!_client) {
    const config = getConfig();
    _client = algoliasearch(config.appId, config.apiKey);
  }
  return _client;
}

import { algoliasearch } from 'algoliasearch';

const adminClient = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Create environment-scoped keys that can ONLY access their own indices
async function createEnvironmentKeys() {
  // Staging key: can only access staging_* indices
  const { key: stagingKey } = await adminClient.addApiKey({
    apiKey: {
      acl: ['search', 'addObject', 'deleteObject', 'editSettings', 'browse'],
      description: 'Staging environment — full access to staging indices only',
      indexes: ['staging_*'],
      maxQueriesPerIPPerHour: 10000,
    },
  });
  console.log(`Staging key: ${stagingKey}`);

  // Dev key: can only access development_* indices
  const { key: devKey } = await adminClient.addApiKey({
    apiKey: {
      acl: ['search', 'addObject', &

// src/algolia/instrumented-client.ts
import { algoliasearch, ApiError } from 'algoliasearch';
import { Counter, Histogram, Gauge, Registry } from 'prom-client';

const registry = new Registry();

const searchLatency = new Histogram({
  name: 'algolia_search_duration_seconds',
  help: 'Algolia search request duration in seconds',
  labelNames: ['index', 'status'],
  buckets: [0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5],
  registers: [registry],
});

const searchTotal = new Counter({
  name: 'algolia_search_requests_total',
  help: 'Total Algolia search requests',
  labelNames: ['index', 'status'],
  registers: [registry],
});

const searchErrors = new Counter({
  name: 'algolia_errors_total',
  help: 'Total Algolia errors by type',
  labelNames: ['index', 'error_type', 'status_code'],
  registers: [registry],
});

const indexRecords = new Gauge({
  name: 'algolia_index_records',
  help: 'Number of records in Algolia index',
  labelNames: ['index'],
  registers: [registry],
});

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

export async function instrumentedSearch<T = any>(
  indexName: string,
  searchParams: Record<string, any>
) {
  const timer = searchLatency.startTimer({ index: indexName });

  try {
    const result = await client.searchSingleIndex<T>({ indexName, searchParams });
    timer({ status: 'success' });
    searchTotal.inc({ index: indexName, status: 'success' });
    return result;
  } catch (error) {
    timer({ status: 'error' });
    searchTotal.inc({ index: indexName, status: 'error' });

    if (error instanceof ApiError) {
      searchErrors.inc({
        index: indexName,
        error_type: error.s

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// BAD: Full record with unnecessary data
const badRecord = {
  objectID: '1',
  name: 'Running Shoes',
  full_html_description: '<div>...5000 chars of HTML...</div>',  // Too big
  internal_notes: 'Supplier ref: ABC-123',                       // Not searchable
  all_reviews: [/* 200 reviews */],                                // Huge array
};

// GOOD: Lean record for search
const goodRecord = {
  objectID: '1',
  name: 'Running Shoes',
  description: 'Lightweight running shoes with cushioned sole',  // Plain text, truncated
  category: 'shoes',
  brand: 'Nike',
  price: 129.99,
  rating: 4.5,
  review_count: 200,          // Count, not full reviews
  in_stock: true,
  image_url: '/images/1.jpg', // URL, not base64
};

await client.setSettings({
  indexName: 'products',
  indexSettings: {
    // Order matters: first attribute = highest priority in ranking
    // Fewer searchable attributes = faster search
    searchableAttributes: [
      'name',                    // Highest priority
      'brand',
      'category',
      'unordered(description)',  // unordered = position in attribute doesn't affect ranking
    ],
    // DON'T make IDs, URLs, or numeric fields searchable

    // unretrievableAttributes: fields searchable but never returned in hits
    // Use for fields users should match against but not see
    unretrievableAttributes: ['internal_tags'],

    // attributesToRetrieve: limit what comes back (smaller response = faster)
    attributesToRetrieve: ['name', 'brand', 'price', 'image_url', 'category'],
  },
});

// Verify production settings
const settings = await client.getSettings({ indexName: 'products' });
console.log(JSON.stringify(settings, null, 2));

// Replicas give users alternate sort orders
await client.setSettings({
  indexName: 'products',
  indexSettings: {
    // Standard replicas: share parent's data, use their own relevance settings
    replicas: [
      'products_price_asc',    // Sort by price ascending
      'products_price_desc',   // Sort by price descending
      'products_newest',       // Sort by newest first
    ],
  },
});

// Configure each replica's ranking
await client.setSettings({
  indexName: 'products_price_asc',
  indexSettings: {
    ranking: [
      'asc(price)',    // Primary: price ascending
      'typo', 'geo', 'words', 'filters', 'proximity', 'attribute', 'exact', 'custom',
    ],
  },
});

// He

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Create a rate-limited API key for frontend use
const { key } = await client.addApiKey({
  apiKey: {
    acl: ['search'],
    description: 'Frontend search key — rate limited',
    maxQueriesPerIPPerHour: 1000,  // Per user IP
    maxHitsPerQuery: 20,
    indexes: ['products'],          // Restrict to specific indices
    validity: 0,                    // 0 = never expires
  },
});
console.log(`Created rate-limited key: ${key}`);

import { ApiError } from 'algoliasearch';

async function withBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 30000 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (attempt === config.maxRetries) throw error;

      // Only retry on 429 or 5xx
      if (error instanceof ApiError) {
        if (error.status !== 429 && error.status < 500) throw error;
      }

      /

┌──────────────────────────────────────────────────────────────┐
│                      Frontend                                 │
│  InstantSearch.js / React InstantSearch                       │
│  Uses: liteClient (search-only key)                          │
│  Sends: search-insights events (clicks, conversions)          │
└───────────────────────┬──────────────────────────────────────┘
                        │ Search + Events
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                   Algolia Cloud                               │
│  ┌─────────┐  ┌──────────────┐  ┌─────────────┐             │
│  │ Search   │  │ Analytics    │  │ Recommend   │             │
│  │ Engine   │  │ + Insights   │  │ (ML-based)  │             │
│  └─────────┘  └──────────────┘  └─────────────┘             │
└───────────────────────▲──────────────────────────────────────┘
                        │ Indexing (admin key)
                        │
┌──────────────────────────────────────────────────────────────┐
│                    Backend Service                            │
│  ┌────────────┐  ┌──────────────┐  ┌─────────────────┐      │
│  │ Search     │  │ Indexing     │  │ Settings        │      │
│  │ Service    │  │ Pipeline     │  │ Manager         │      │
│  └────────────┘  └──────┬───────┘  └─────────────────┘      │
│                         │                                     │
│  ┌──────────────────────▼────────────────────────────┐       │
│  │              Source Database                        │       │
│  │  PostgreSQL / MongoDB / CMS / External API          │       │
│  └────────────────────────────────────────────────────┘       │
└──────────────────────────────────────────────────────────────┘

src/
├── algolia/
│   ├── client.ts           # Singleton client (see algolia-sdk-patterns)
│   ├── indices.ts          # Index name constants + environment prefixing
│   ├── settings/
│   │   ├── products.ts     # Products index settings
│   │   ├── articles.ts     # Articles index settings
│   │   └── apply.ts        # Script to apply all settings
│   └── transforms/
│       ├── product.ts      # DB record → Algolia record transformer
│       └── article.ts      # DB record → Algolia record transformer
├── services/
│   ├── search.ts           # Search service (wraps Algolia client)
│   └── indexing.ts         # Indexing pipeline (DB → transform → Algolia)
├── api/
│   ├── search.ts           # Search endpoint (returns Algolia results)
│   └── reindex.ts          # Admin endpoint to trigger reindex
└── jobs/
    └── sync-algolia.ts     # Cron job for periodic full sync

// src/algolia/client.ts
import { algoliasearch, type Algoliasearch } from 'algoliasearch';

let _client: Algoliasearch | null = null;

export function getClient(): Algoliasearch {
  if (!_client) {
    const appId = process.env.ALGOLIA_APP_ID;
    const apiKey = process.env.ALGOLIA_ADMIN_KEY;
    if (!appId || !apiKey) {
      throw new Error(
        'ALGOLIA_APP_ID and ALGOLIA_ADMIN_KEY must be set. '
        + 'Get them from dashboard.algolia.com > Settings > API Keys'
      );
    }
    _client = algoliasearch(appId, apiKey);
  }
  return _client;
}

// For testing: reset singleton
export function resetClient(): void {
  _client = null;
}

// src/algolia/types.ts

// Define your record shape — extends Algolia's Hit type
interface Product {
  objectID: string;
  name: string;
  category: string;
  price: number;
  description: string;
  image_url: string;
}

// src/algolia/search.ts
import { getClient } from './client';

export async function searchProducts(
  query: string,
  options?: {
    filters?: string;
    facetFilters?: string[][];
    hitsPerPage?: number;
    page?: number;
  }
) {
  const client = getClient();

  const { hits, nbHits, nbPages, page } = await client.searchSingleIndex<Product>({
    indexName: 'products',
    searchParams: {
      query,
      filters: options?.filters,
      facetFilters: options?.facetFilters,
      hitsPerPage: options?.hitsPerPage ?? 20,
      page: options?.page ?? 0,
      attributesToRetrieve: ['name', 'category', 'price', 'image_url'],
      attributesToHighlight: ['name', 'description'],
    },
  });

  return { hits, totalHits: nbHits, totalPages: nbPages, currentPage: page };
}

// Usage: const { hits } = await searchProducts('laptop', { filters: 'price < 1000' });

// src/algolia/errors.ts
import { ApiError } from 'algoliasearch';

export async function safeAlgoliaCall<T>(
  operation: string,
  fn: () => Promise<T>
): Promise<{ data: T | null; error: string | null }> {
  try {
    const data = await fn();
    return { data, error: null };
  } catch

# .env (NEVER commit — add to .gitignore)
ALGOLIA_APP_ID=YourApplicationID
ALGOLIA_ADMIN_KEY=admin_api_key_here        # Backend only
ALGOLIA_SEARCH_KEY=search_only_key_here     # OK for frontend

# .gitignore — MUST include:
.env
.env.local
.env.*.local

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Create a write-only key for a specific microservice
const { key: indexingKey } = await client.addApiKey({
  apiKey: {
    acl: ['addObject', 'deleteObject', 'editSettings'],
    description: 'Product sync service — write only',
    indexes: ['products', 'products_staging'],  // Restrict to specific indices
    maxQueriesPerIPPerHour: 5000,
    referers: [],  // Empty = no referer restriction (backend use)
  },
});

// Create a search key restricted to specific referers (frontend)
const { key: frontendKey } = await client.addApiKey({
  apiKey: {
    acl: ['search'],
    description: 'Frontend search — domain-restricted',
    indexes: ['products'],
    referers: ['https://mystore.com/*', 'https://*.mystore.com/*'],
    maxQueriesPerIPPerHour: 1000,
    maxHitsPerQuery: 50,
  },
});

// Secured API keys are generated on YOUR server, not via Algolia API.
// They embed restrictions that the client can't bypass.

function generateUserSearchKey(userId: string, tenantId: string): string {
  const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

  return client.generateSecuredA

git checkout -b upgrade/algoliasearch-v5
npm install algoliasearch@latest
npm list algoliasearch  # Verify v5.x.x

// v4
import algoliasearch from 'algoliasearch';
const client = algoliasearch('APP_ID', 'API_KEY');

// v5
im

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Enable clickAnalytics to get queryID in search results
const { hits, queryID } = await client.searchSingleIndex({
  indexName: 'products',
  searchParams: {
    query: 'running shoes',
    clickAnalytics: true,  // Returns queryID for event correlation
  },
});
// queryID links this search to subsequent click/conversion events

// The Insights API is built into the algoliasearch client
// Events connect user behavior back to specific search queries

// Track a click on a search result
await client.pushEvents({
  events: [{
    eventType: 'click',
    eventName: 'Product Clicked',
    index: 'products',
    userToken: 'user-123',        // Unique user identifier
    queryID: queryID,              // From search response
    objectIDs: ['product-456'],    // What was clicked
    positions: [3],                // Position in results (1-indexed)
    timestamp: Date.now(),
  }],
});

// Track a conversion (purchase, add-to-cart)
await client.pushEvents({
  events: [{
    eventType: 'conversion',
    eventName: 'Product Purchased',
    index: 'products',
    userToken: 'user-123',
    queryID: queryID,
    objectIDs: ['product-456'],
    timestamp: Date.now(),
  }],
});

// Track a view (product page visit, no search context)
await client.pushEvents({
  events: [{
    eventType: 'view',
    eventName: 'Product Viewed',
    index: 'products',
    userToken: 'user-123',
    objectIDs: ['product-456'],
    timestamp: Date.now(),
  }],
});

npm install search-insights

// Frontend: lightweight event tracking
import { default as aa } from 'search-insights';

aa('init', {
  appId: 'YourAppID',
  apiKey: 'YourSearchOnlyKe