Search Plugin

Search Plugin

The search plugin provides a unified search API across three backends. App code written against any one backend works with the others by changing one env var and restarting.

Backend Comparison

Feature	MeiliSearch	Typesense	OpenSearch
Best for	Small deploys, low RAM	Multi-tenant, teams	Enterprise, compliance
Multi-tenant isolation	Filter-based	Scoped API keys	Role + filter
Schema	Auto-inferred	Schema-first (auto on first batch)	Dynamic mappings
Disk footprint	Low	Medium	High
TLS in dev	Optional	Optional	OPENSEARCH_TLS_VERIFY=false
Bundle	search ($0.99/mo)	search ($0.99/mo)	search ($0.99/mo)

All three share the same HTTP API surface on port 8050 (CS_3).

Installation

nself license set nself_pro_xxxx...
nself plugin install search
nself build

Configuration

Set SEARCH_ENGINE to choose the active backend. All other vars for the inactive backends are ignored.

MeiliSearch (default)

SEARCH_ENGINE=meilisearch
MEILISEARCH_URL=http://localhost:7700
MEILISEARCH_MASTER_KEY=your-master-key

Typesense

SEARCH_ENGINE=typesense
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=https
TYPESENSE_API_KEY=your-api-key

OpenSearch

SEARCH_ENGINE=opensearch
OPENSEARCH_URL=https://localhost:9200
OPENSEARCH_USERNAME=admin
OPENSEARCH_PASSWORD=your-password
# Dev only, allows self-signed certificate:
OPENSEARCH_TLS_VERIFY=false

API Reference

All routes are prefixed /search and served by the plugin on port 8050.

Method	Path	Description
GET	/search/status	Backend type, version, stats
GET	/search/indexes	List all indexes
POST	/search/index/:name/documents	Upsert documents
DELETE	/search/index/:name/documents/:id	Delete a document
POST	/search/index/:name/query	Full-text search
POST	/search/index/:name/schema	Create or update index schema

Upsert documents

POST /search/index/products/documents
[{"id": "1", "title": "Widget", "price": 9.99}]

Search

POST /search/index/products/query
{"query": "widget", "limit": 20, "highlight_fields": ["title"]}

Status response

{
  "backend": "typesense",
  "version": "0.25.2",
  "indexes": 4,
  "extra": {"ok": true}
}

Multi-tenant Isolation (Typesense)

When using SEARCH_ENGINE=typesense, the plugin reads the X-Hasura-Role request header and generates a Typesense scoped API key that restricts results to documents tagged with that role. Queries from different roles cannot see each other’s documents within the same collection.

Switching Backends

Changing SEARCH_ENGINE and restarting the plugin triggers a full reindex from Postgres (np_search_documents table). The reindex runs automatically on startup, no manual intervention required.

Hasura Remote Schema

The search plugin is wired into Hasura under the search namespace. Queries use the same search namespace regardless of the active backend.

Database Migration

On startup the plugin applies:

ALTER TABLE np_search_indexes
  ADD COLUMN IF NOT EXISTS backend TEXT NOT NULL DEFAULT 'meilisearch';

This is idempotent and safe to run repeatedly.