Search — Reference
The Search surface is the discovery plane for every SGEN site. It owns the index that backs site-wide search, the indexing rules that decide which records are searchable, the synonym dictionary, the boost rules that reorder ranked results, the did-you-mean correction layer, and the analytics that capture what visitors search for. Anything that affects how a visitor's query maps to a page on the live site traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, tuning the ranking, or wiring a custom record type into the index. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Search lives under the Search module in SG-Admin. The module renders four primary views — the index status dashboard, the synonym dictionary editor, the boost rules editor, and the search analytics view — and exposes write operations for rebuild index, configure indexing rules, add and edit synonyms, add and edit boost rules, and prune analytics history.
The module is paired by convention: one half renders the views and prepares the data, the other half handles writes and dispatches background work to the indexer. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
The index itself is maintained by a background indexer that consumes record-change events from the rest of the platform. The Search module is the administrative surface over that indexer; query execution at visitor request time goes through a separate front-end search endpoint that reads from the same index.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Search
- URL prefix:
/sg-admin/search/ - View templates:
application/views/Admin/Search/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Search → Index status │├──────────────────────────────────────────────────────────────────────┤│ Index health: ✔ ready Last full rebuild: 3 days ago ││ Records indexed: 1,847 Pending updates: 0 │├──────────────────────────────────────────────────────────────────────┤│ Record type Indexed Excluded Last incremental ││ ─────────────── ─────── ──────── ───────────────────── ││ Page 124 3 2 min ago ││ Post 892 8 17 min ago ││ Product 118 0 1 hour ago ││ KB article 713 2 1 hour ago ││ ││ [Rebuild now] [Configure indexing rules] │└──────────────────────────────────────────────────────────────────────┘Actions
The Search surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
View index status
Returns the health of the index — total record count, per-record-type breakdown, pending update count, time of the last full rebuild, time of the last incremental update, and any error captured by the indexer since the last successful run. Used as the entry view to confirm that the index is current before any tuning work begins.
Rebuild index
Dispatches a full rebuild — every searchable record is re-read from its source surface and re-emitted into the index. Rebuild runs in the background; the surface returns immediately with a tracking identifier. While a rebuild is in progress, the index continues to serve queries from its previous state. The new state replaces the old atomically when the rebuild completes.
Configure indexing rules
Sets, per record type, whether the record type is included in the index at all, which fields contribute to the searchable text, and any per-record exclusion conditions (for example, draft posts excluded by status). Changes take effect immediately for incremental updates; a full rebuild is required to apply changes to records that were previously indexed under the old rules.
List and edit synonyms
The synonym dictionary maps query-time terms to one or more equivalent terms that should match the same records. Entries are bidirectional by default (a search for either term surfaces results indexed under the other) but a one-way mode is available for directional aliases. The list view supports filter and free-text search; the editor accepts a term and one or more synonym values per entry.
List and edit boost rules
Boost rules reorder results that match a query. Each rule carries a target (a record type, a tag, a field value, or an explicit record identifier) and a relative weight. At query time, the search engine multiplies the base relevance score by the boost weight before sorting. Negative weights are permitted and act as demotion.
View search analytics
Shows the queries visitors ran on the site, paginated, with columns for the query string, the number of times it was issued, the click-through rate (how often a result was clicked vs how often no result was clicked), and the most recent occurrence. Filters by date range and by whether the query returned zero results. Used to identify gaps — frequent queries that return nothing are the canonical input to the synonym dictionary.
Configure did-you-mean
Toggles the did-you-mean correction layer and sets the minimum-distance threshold for triggering a correction. When enabled, queries that return zero results are checked against the index vocabulary; if a near-match is found within the threshold, the surface returns a "did you mean" suggestion. The threshold trades false positives (suggesting a correction for a deliberate query) against false negatives (missing a typo).
Prune analytics history
Removes analytics records older than the configured retention cutoff. Aggregated rollups (total query count, click-through rate per query) are preserved; the per-occurrence detail is removed. Prune runs on a schedule; manual invocation is available for administrators.
Data model
The Search surface manages several related record types. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
Indexing rule (per record type):
| Field | Type | Notes |
|---|---|---|
record_type | string | Slug of the record type. Primary key. |
included | boolean | Whether the record type is in the index at all. |
searchable_fields | array | Field slugs that contribute to the searchable text. |
exclusion_filter | structured | Optional condition that excludes individual records. |
boost_field | string | Optional. Name of a field whose value is read as a per-record boost weight. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
term | string | The query-time term. |
synonyms | array | One or more equivalent terms. |
directional | boolean | When true, only term → synonyms resolves; reverse does not. |
created_at, updated_at | timestamp | Standard. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
target_type | enum | record_type, tag, field_value, record_id. |
target_value | string | Interpreted against target_type. |
weight | decimal | Multiplier applied to base relevance. Negative for demotion. |
active | boolean | When false, the rule is preserved but ignored at query time. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
query | string | The visitor query, lower-cased and trimmed. |
result_count | integer | Number of results returned. |
clicked_result_id | integer | Optional. Set when the visitor clicked a result. |
occurred_at | timestamp | Set on query, immutable. |
SOURCE RECORDS (page / post / product / kb)││ change events▼INDEXING RULES ──filters out excluded records──▶│▼INDEX (eventually consistent)││ visitor query▼SYNONYM EXPANSION ──rewrites query terms──▶│▼BASE RELEVANCE SCORE││ × boost rules▼ORDERED RESULTS ──or──▶ DID-YOU-MEAN (if zero results)│▼ANALYTICS RECORD(query + result count + click)Permissions
Access to the Search surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Search administrative surface. Visitor query execution at the front-end search endpoint is not gated by the admin check.
Layer 2 — per-action capability. Within SG-Admin, each Search action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| View index status | ✔ | ✔ | ✔ |
| Rebuild index | ✔ | — | — |
| Configure indexing rules | ✔ | — | — |
| List and edit synonyms | ✔ | ✔ | — |
| List and edit boost rules | ✔ | ✔ | — |
| View search analytics | ✔ | ✔ | ✔ |
| Configure did-you-mean | ✔ | — | — |
| Prune analytics history | ✔ | — | — |
Self-protection rules. A rebuild cannot be triggered while a prior rebuild is still in progress — the surface returns a structured rejection that names the running rebuild's tracking identifier. Boost rules with weight set to zero are rejected at write time (use the active flag to disable a rule, not zero weight).
Audit. Every write — rebuild dispatch, indexing-rule change, synonym add or edit, boost rule add or edit, did-you-mean configuration, analytics prune — emits an Activity Log entry. The log records the acting operator, the target record (if any), and the change shape. Activity Log retention is governed by the site's general settings.
ADMIN OPERATOR REQUEST VISITOR QUERY REQUEST│ │▼ ▼┌─────────────────────────┐ ┌─────────────────────────┐│ Admin gate │ │ No admin gate ││ (SG-Admin entry) │ │ (front-end endpoint) │└────────────┬────────────┘ └────────────┬────────────┘│ │▼ ▼┌─────────────────────────┐ ┌─────────────────────────┐│ Capability check │ │ Rate limit + abuse ││ (per-action) │ │ (per visitor identity) │└────────────┬────────────┘ └────────────┬────────────┘│ │▼ ▼action executes query executes│ │▼ ▼Activity Log entry Analytics recordRelated references
- Settings — Reference. Owns the role definitions, the front-end search endpoint configuration, the analytics retention cutoff, and the rate-limit thresholds for the visitor query path.
- Users — Reference. Operator identifiers on indexing-rule and boost-rule writes resolve through the Users surface.
- Pages — Reference. Pages are a default-included record type; their indexing rule defines which page fields contribute to the searchable text.
- Posts — Reference. Posts are a default-included record type; the indexing rule for posts respects the draft and scheduled states.
- Sitemaps — Reference. The sitemap surface and the search index share a similar inclusion model but operate independently — a record excluded from search may still appear in the sitemap and vice versa.
- Logs — Reference. Indexer errors and rebuild progress markers surface on the appropriate channels for operator investigation.
- Tools — Reference. The Activity Log search surface lives under Tools; it is the canonical place to investigate "who changed the boost rules and when."
/docs/search.