Skip to content

Commit f280951

Browse files
Alexandre Oliveiraclaude
Alexandre Oliveira
and
claude
committed
docs(turing): add Search Engine page with cores, system info, and plugin architecture
search-engine.md (new): - Instance listing with blank state - Create/edit form: General Info + Connection Settings with 3 vendor defaults (SOLR http://localhost:8983/solr, LUCENE /data/turing/lucene, ES http://localhost:9200) - Instance detail: Settings, Cores, System Information navigation sections - Cores section: listing (name/numDocs/sites with badges/flags), search filter, per-core actions (delete blocked if in use, clear documents), create core with locale selector + append-locale toggle + name preview - System Information: UP/DOWN badge, engine version, Lucene version, OS, Java, JVM memory - Plugin architecture: Mermaid diagram (Factory → 3 plugins), TurSearchEnginePlugin interface with all 12+ methods across 4 categories - Protections: delete-in-use blocking with site/locale list, repo-level caching - Tip for naming convention {site}_{lang}_{COUNTRY} administration-guide.md: - Replace outdated Search Engine table (only had Solr, Host, Port fields) with concise pointer to search-engine.md sidebars-turing.ts: - Add Enterprise Search category with search-engine before Management index.md: - Add Enterprise Search section with Search Engine link Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 85792f5 commit f280951

4 files changed

Lines changed: 209 additions & 14 deletions

File tree

‎docs-turing/administration-guide.md‎

Lines changed: 2 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -239,21 +239,9 @@ A searchable table of all JVM properties and environment variables active at run
239239

240240
### Search Engine
241241

242-
#### Configuration
243-
244-
Search Engine is used by Turing to store and retrieve data of Semantic Navigation Sites.
245-
242+
The Search Engine section manages connections to the search backend (Apache Solr, Elasticsearch, or Lucene) and the cores (collections) that each Semantic Navigation Site locale maps to.
246243

247-
It is possible create or edit a Search Engine with following attributes:
248-
249-
| Attribute | Description |
250-
|-----------|-------------|
251-
| Name | Name of Search Engine |
252-
| Description | Description of Search Engine |
253-
| Vendor | Select the Vendor of Search Engine. For now it only supports Solr |
254-
| Host | Host name where the Search Engine service is installed |
255-
| Port | Port of Search Engine Service |
256-
| Enabled | If the Search Engine is enabled |
244+
For full documentation — instance creation, core management, system monitoring, the plugin architecture, and protections — see **[Search Engine](./search-engine.md)**.
257245

258246
### Semantic Navigation
259247

‎docs-turing/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,14 @@ slug: /
3434

3535
---
3636

37+
## Enterprise Search
38+
39+
| Guide | Description |
40+
|---|---|
41+
| [Search Engine](/turing/search-engine) | Manage search backend instances (Solr, Elasticsearch, Lucene), cores, and system monitoring |
42+
43+
---
44+
3745
## Management
3846

3947
| Guide | Description |

‎docs-turing/search-engine.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
sidebar_position: 1
3+
title: Search Engine
4+
description: Configure and manage Search Engine instances in Viglet Turing ES.
5+
---
6+
7+
# Search Engine
8+
9+
The **Search Engine** page (`/admin/se/instance`) manages the search backends that power Semantic Navigation Sites. It is accessible from the **Enterprise Search** section of the sidebar.
10+
11+
Each **Search Engine instance** is a configured connection to a search backend. Semantic Navigation Sites bind to a specific instance when their cores (collections) are created. Turing ES supports three backends via a plugin architecture: **Apache Solr** (recommended), **Apache Lucene** (embedded), and **Elasticsearch**.
12+
13+
---
14+
15+
## Instance Listing
16+
17+
The page displays all configured instances as a grid of cards (title and description). Use the **"New"** button to add an instance. When no instances exist, a blank state guides you to create the first one.
18+
19+
---
20+
21+
## Create / Edit Form
22+
23+
### General Information
24+
25+
| Field | Required | Description |
26+
|---|---|---|
27+
| **Title** | ✅ | Display name for this instance — shown in SN Site dropdowns |
28+
| **Description** | | Free-text notes about this instance |
29+
30+
### Connection Settings
31+
32+
| Field | Required | Description |
33+
|---|---|---|
34+
| **Vendor** | ✅ | Backend type: `SOLR`, `LUCENE`, or `ES` |
35+
| **Endpoint URL** | ✅ | Connection URL for the backend service |
36+
37+
Default endpoint URLs per vendor:
38+
39+
| Vendor | Default Endpoint URL |
40+
|---|---|
41+
| **SOLR** (Apache Solr) | `http://localhost:8983/solr` |
42+
| **LUCENE** (embedded Apache Lucene) | `/data/turing/lucene` |
43+
| **ES** (Elasticsearch) | `http://localhost:9200` |
44+
45+
---
46+
47+
## Instance Detail Pages
48+
49+
After creating an instance, its detail page exposes three navigation sections.
50+
51+
### Settings
52+
53+
Editing form for all fields listed above, plus a **Delete instance** button. An instance cannot be deleted if any SN Site cores are still using it.
54+
55+
---
56+
57+
### Cores (Collections)
58+
59+
Manages the search indices — called **cores** in Solr terminology — within this search engine instance. Each Semantic Navigation Site locale maps to one core.
60+
61+
#### Core Listing
62+
63+
The list shows all cores found in the connected backend:
64+
65+
| Column | Description |
66+
|---|---|
67+
| **Name** | Core identifier (e.g., `my-site_en_US`) |
68+
| **Documents** | Number of indexed documents (`numDocs`) reported by the engine |
69+
| **Sites** | Badges showing each SN Site and locale using this core, with a country flag for quick recognition |
70+
71+
Cores are grouped by locale pattern: `{base}_{lang}_{COUNTRY}` (e.g., `product-docs_pt_BR`). A **search/filter** field at the top narrows the list by core name.
72+
73+
#### Core Actions
74+
75+
| Action | Description |
76+
|---|---|
77+
| **Delete core** | Permanently removes the core and all its indexed data. **Blocked** if the core is in use by any SN Site — the UI shows which sites and locales are preventing deletion. |
78+
| **Clear documents** | Erases all indexed documents from the core without removing the core itself. Useful for a clean re-index without reconfiguring site associations. |
79+
80+
#### Create a New Core
81+
82+
| Field | Required | Description |
83+
|---|---|---|
84+
| **Name / Name Prefix** | ✅ | Core name or prefix |
85+
| **Locale** | ✅ | Language and country (e.g., `en_US`, `pt_BR`) |
86+
| **Append locale to name** | | Toggle — when enabled, the locale is automatically appended to the prefix, generating the canonical name (e.g., prefix `my-site` + locale `en_US` → `my-site_en_US`) |
87+
88+
A **name preview** shows the final core name as you type, before saving.
89+
90+
:::tip Naming convention
91+
Use the `{site-name}_{lang}_{COUNTRY}` pattern consistently. This makes it easy to identify which site and locale each core belongs to when browsing multiple instances.
92+
:::
93+
94+
---
95+
96+
### System Information
97+
98+
Live monitoring panel for the connected backend:
99+
100+
| Item | Description |
101+
|---|---|
102+
| **Status badge** | `UP` (green) or `DOWN` (red) — real-time connectivity check |
103+
| **Engine version** | Solr or Elasticsearch version string |
104+
| **Lucene version** | Underlying Lucene library version |
105+
| **Operating system** | OS name and version of the engine host |
106+
| **Java version** | JVM version running the search engine |
107+
| **JVM memory** | Heap usage reported by the engine |
108+
| **Other properties** | Additional dynamic properties returned by the engine's status API |
109+
110+
---
111+
112+
## Plugin Architecture
113+
114+
Turing ES uses a **plugin architecture** to support multiple search backends with a unified interface. The active plugin is resolved at runtime based on the vendor configured per instance.
115+
116+
```mermaid
117+
graph TD
118+
FACTORY["TurSearchEnginePluginFactory\n(resolves by vendor, fallback → Solr)"]
119+
SOLR["TurSolrSearchEnginePlugin"]
120+
ES["TurElasticsearchSearchEnginePlugin"]
121+
LUCENE["TurLuceneSearchEnginePlugin"]
122+
123+
FACTORY --> SOLR
124+
FACTORY --> ES
125+
FACTORY --> LUCENE
126+
```
127+
128+
The `TurSearchEnginePlugin` interface defines all backend operations in four categories:
129+
130+
**Search**
131+
132+
| Method | Description |
133+
|---|---|
134+
| `retrieveSearchResults()` | Execute a full-text query and return results with facets |
135+
| `retrieveFacetResults()` | Return facet counts for a query |
136+
137+
**Index management**
138+
139+
| Method | Description |
140+
|---|---|
141+
| `createIndex()` | Create a new core / index |
142+
| `deleteIndex()` | Delete a core / index |
143+
| `clearIndex()` | Remove all documents from a core without deleting it |
144+
| `listIndexes()` | List all cores / indices on the backend |
145+
146+
**Schema management**
147+
148+
| Method | Description |
149+
|---|---|
150+
| `addOrUpdateField()` | Add or update a field definition in the schema |
151+
| `deleteField()` | Remove a field from the schema |
152+
| `fieldExists()` | Check whether a field exists in the schema |
153+
154+
**Documents & monitoring**
155+
156+
| Method | Description |
157+
|---|---|
158+
| `indexDocument()` | Index a single document |
159+
| `deIndex()` | Remove a document from the index |
160+
| `commit()` | Flush pending writes (for backends that require explicit commits) |
161+
| `getDocumentTotal()` | Return the total number of indexed documents |
162+
| `getSystemInfo()` | Return backend version, OS, JVM, and memory information |
163+
164+
:::info Fallback behaviour
165+
If a vendor is unrecognised or unavailable, `TurSearchEnginePluginFactory` falls back to the **Solr** plugin. Apache Solr is the primary supported backend with the most complete feature set.
166+
:::
167+
168+
---
169+
170+
## Protections
171+
172+
| Scenario | Behaviour |
173+
|---|---|
174+
| **Delete core in use** | Blocked — the UI displays a list of SN Sites and locales currently using the core |
175+
| **Delete instance in use** | Should be avoided — removing an instance with active sites will break indexing and search for those sites |
176+
177+
Repository-level **caching** is enabled for search engine instances to avoid repeated database reads during high-frequency searches.
178+
179+
---
180+
181+
## Related Pages
182+
183+
| Page | Description |
184+
|---|---|
185+
| [Administration Guide](./administration-guide.md) | Full console reference |
186+
| [Semantic Navigation Concepts](./sn-concepts.md) | How SN Sites use cores and search engines |
187+
| [Architecture Overview](./architecture-overview.md) | Solr, Elasticsearch, and Lucene in the system architecture |
188+
| [Configuration Reference](./configuration-reference.md#solr) | Solr and Elasticsearch timeout settings in `application.yaml` |
189+
190+
---
191+
192+
*Previous: [Administration Guide](./administration-guide.md)*

‎sidebars-turing.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,13 @@ const sidebars: SidebarsConfig = {
2222
"configuration-reference",
2323
"administration-guide",
2424
"developer-guide",
25+
{
26+
type: "category",
27+
label: "Enterprise Search",
28+
items: [
29+
"search-engine",
30+
],
31+
},
2532
{
2633
type: "category",
2734
label: "Management",

0 commit comments

Comments
 (0)