Complete guide for using the OpenSearch Index Manager plugin.
- Getting Started
- Index Selection
- Document Management
- Nested Field Editing
- Search Functionality
- Mapping Viewer
- Tips and Tricks
- Troubleshooting
- Log in to your OpenSearch Dashboards instance
- Look for "OpenSearch Plugins" in the left navigation sidebar
- Click on "Index Manager" to open the plugin
When you open the plugin, you'll see:
┌─────────────────────────────────────────────────────────────────┐
│ OpenSearch Index Manager │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Select Index: [Choose an index... ▼] │
│ │
│ [Create Document] [Toggle Mapping] │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Search: [ 🔍] │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ Select an index to view documents │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- Click the "Select Index" dropdown
- You'll see a list of all available indices in your OpenSearch cluster
- Choose the index you want to work with
The dropdown shows:
- Index name: The name of the index
- Document count: Number of documents (shown as badge)
- Health status: Green (healthy), Yellow (warning), or Red (critical)
The index list refreshes automatically when you open the dropdown. To manually refresh:
- Close and reopen the dropdown
- Reload the page (F5)
Once you select an index, the document list appears:
┌─────────────────────────────────────────────────────────────────┐
│ Documents (1-20 of 1,247) [Refresh]│
├──────────┬──────────┬──────────┬──────────┬────────────┬────────┤
│ _id │ title │ status │ created │ Actions │ ... │
├──────────┼──────────┼──────────┼──────────┼────────────┼────────┤
│ doc_001 │ ... │ active │ ... │ [Edit][Del]│ │
│ doc_002 │ ... │ pending │ ... │ [Edit][Del]│ │
│ doc_003 │ ... │ active │ ... │ [Edit][Del]│ │
├──────────┴──────────┴──────────┴──────────┴────────────┴────────┤
│ [← Previous] Page 1 of 63 [Next →] [20 ▼] per page │
└─────────────────────────────────────────────────────────────────┘
The table automatically shows common fields:
_id: Document IDtitle,name: Common identifier fieldsstatus,state: Status fieldscreated,timestamp: Date fields
Additional fields can be viewed by scrolling horizontally.
- Use Previous / Next buttons to navigate pages
- Change items per page: 20, 50, 100, or 1000
- Current position shown as: "1-20 of 1,247"
- Click the "Create Document" button
- The document editor opens:
┌─────────────────────────────────────────────────────────────┐
│ Create Document [X] │
├─────────────────────────────────────────────────────────────┤
│ │
│ Document ID (optional): │
│ [my-custom-id ] │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Fields │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ [+ Add Field] │ │
│ │ │ │
│ │ Field Name Type Value │ │
│ │ [title ] [text ▼] [Hello World ] [🗑️] │ │
│ │ [status ] [keyword▼] [active ] [🗑️] │ │
│ │ [count ] [long ▼] [42 ] [🗑️] │ │
│ │ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ [Switch to JSON Mode] │
│ │
│ [Cancel] [Save Document] │
└─────────────────────────────────────────────────────────────┘
-
Document ID (optional):
- Leave blank for auto-generated ID
- Enter custom ID if needed
- Must be unique within the index
-
Add Fields:
- Click "+ Add Field" to add a new field
- Enter field name
- Select field type:
text- For full-text searchkeyword- For exact matchinglong/integer- For numbersdouble/float- For decimalsboolean- For true/falsedate- For datesobject- For nested objectsnested- For nested arrays
-
Enter Values:
- Type the value in the value field
- For objects, click the + icon to add child fields
- For arrays, click Add Item
-
Save:
- Click "Save Document" to create
- Or "Cancel" to discard
For complex documents, switch to JSON mode:
[Switch to Form Mode]
┌──────────────────────────────────────────────────────────────┐
│ { │
│ "title": "Hello World", │
│ "status": "active", │
│ "metadata": { │
│ "created_by": "user123", │
│ "tags": ["important", "review"] │
│ } │
│ } │
└──────────────────────────────────────────────────────────────┘
- Find the document in the list
- Click the "Edit" button (pencil icon)
- The editor opens with current values
Simple Fields (text, keyword, numbers):
- Click the value field
- Make changes
- Press Tab or click elsewhere to confirm
Boolean Fields:
- Toggle the checkbox
Date Fields:
- Use the date picker
- Or enter ISO format:
2024-01-15T10:30:00Z
Object Fields:
- Click the arrow to expand
- Edit child fields
- Click + to add new fields to the object
Array Fields:
- Each item shown with index
- Click Add Item to append
- Click 🗑️ to remove an item
- Click "Save Document" to persist changes
- Click "Cancel" to discard changes
- Validation errors will be shown inline
- Find the document in the list
- Click the "Delete" button (trash icon)
- Confirm deletion in the dialog:
┌─────────────────────────────────────────┐
│ Confirm Delete [X] │
├─────────────────────────────────────────┤
│ │
│ Are you sure you want to delete │
│ document "doc_001"? │
│ │
│ This action cannot be undone. │
│ │
│ [Cancel] [Delete] │
└─────────────────────────────────────────┘
The plugin provides specialized support for nested JSON structures.
Given this document structure:
{
"user": {
"profile": {
"name": "John Doe",
"address": {
"street": "123 Main St",
"city": "New York"
}
},
"preferences": {
"notifications": true
}
}
}-
Navigate the tree:
- Click arrows to expand/collapse levels
- Each level shows its own fields
-
Edit values:
▼ user (object) ▼ profile (object) name: [John Doe ] ▼ address (object) street: [123 Main St ] city: [New York ] ▼ preferences (object) notifications: [✓] -
Add nested fields:
- Click + on the parent object
- Enter field name and type
- For deeply nested objects, select type "object"
For array fields:
▼ tags (array)
[0]: [important ] [🗑️]
[1]: [review ] [🗑️]
[+ Add Item]
Array of Objects:
▼ items (array of objects)
▼ [0]
name: [Product A ]
price: [29.99 ]
▼ [1]
name: [Product B ]
price: [49.99 ]
[+ Add Item]
The editor supports up to 10 levels of nesting (configurable). Deep nesting warning:
⚠️ Maximum nesting depth (10) reached.
Use JSON mode for deeper structures.
- Collapse unused branches: Click ▼ to collapse sections you're not editing
- Use breadcrumbs: The editor shows your current path (user > profile > address)
- Search within document: Use Ctrl+F to find fields
- Copy path: Right-click a field to copy its full path
Enter text in the search box for basic query:
Search: [laptop 🔍]
This searches across all text fields in the documents.
Click the "Advanced" link to use OpenSearch Query DSL:
┌─────────────────────────────────────────────────────────────┐
│ Advanced Search [X] │
├─────────────────────────────────────────────────────────────┤
│ │
│ Query DSL: │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ { │ │
│ │ "query": { │ │
│ │ "bool": { │ │
│ │ "must": [ │ │
│ │ { "match": { "status": "active" } }, │ │
│ │ { "range": { "price": { "gte": 100 } } } │ │
│ │ ] │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ [Cancel] [Search] │
└─────────────────────────────────────────────────────────────┘
Match Query:
{
"query": {
"match": {
"title": "search terms"
}
}
}Term Query (exact match):
{
"query": {
"term": {
"status": "active"
}
}
}Range Query:
{
"query": {
"range": {
"created_at": {
"gte": "2024-01-01",
"lte": "2024-12-31"
}
}
}
}Bool Query (combined):
{
"query": {
"bool": {
"must": [
{ "match": { "title": "laptop" } }
],
"filter": [
{ "term": { "status": "active" } },
{ "range": { "price": { "lte": 1000 } } }
]
}
}
}Results are displayed with:
- Highlighted matches: Matching terms highlighted
- Score: Relevance score (for text search)
- Total hits: Number of matching documents
- Took: Query execution time
Frequently used searches can be saved:
- Run your search
- Click "Save Search"
- Give it a name
- Access from Saved Searches dropdown
Click "Toggle Mapping" to see the index structure:
┌─────────────────────────────────────────────────────────────┐
│ Index Mapping [X] │
├─────────────────────────────────────────────────────────────┤
│ │
│ [Tree View] [JSON View] │
│ │
│ ▼ my-index │
│ ▼ properties │
│ ▼ title │
│ type: text │
│ ▼ status │
│ type: keyword │
│ ▼ metadata (object) │
│ ▼ properties │
│ ▼ created_by │
│ type: keyword │
│ ▼ tags │
│ type: text │
│ │
└─────────────────────────────────────────────────────────────┘
Hierarchical view showing:
- Field names
- Field types
- Nested structure
- Multi-field mappings
Raw mapping JSON for advanced use:
{
"my-index": {
"mappings": {
"properties": {
"title": { "type": "text" },
"status": { "type": "keyword" }
}
}
}
}| Type | Description | Use Case |
|---|---|---|
text |
Analyzed text | Full-text search |
keyword |
Exact value | Filtering, sorting |
long / integer |
Whole numbers | IDs, counts |
float / double |
Decimals | Prices, measurements |
boolean |
true/false | Flags |
date |
Date/time | Timestamps |
object |
Nested object | Complex data |
nested |
Array of objects | Parent-child |
| Shortcut | Action |
|---|---|
Ctrl + S |
Save document (in editor) |
Ctrl + F |
Find in page |
Esc |
Close modal / Cancel |
Enter |
Confirm dialog |
Tab |
Next field |
Shift + Tab |
Previous field |
Currently, the plugin focuses on single-document operations. For bulk operations:
- Export documents: Use OpenSearch API
- Bulk update: Use OpenSearch
_bulkAPI - Re-import: Create documents individually
For Large Indices:
- Use smaller page sizes (20-50)
- Apply filters before viewing
- Avoid expanding all nested fields
- Use specific searches instead of browsing
For Complex Documents:
- Use JSON mode for bulk changes
- Collapse unused branches
- Save work frequently
Adding Timestamp:
{
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}Status Workflow:
{
"status": "draft",
"status_history": [
{ "status": "draft", "timestamp": "..." }
]
}Nested Categories:
{
"category": {
"primary": "electronics",
"sub": "laptops",
"path": "electronics.laptops"
}
}Cause: User doesn't have permissions or cluster is empty
Solution:
- Check OpenSearch Security permissions
- Verify indices exist:
GET /_cat/indices - Check user roles in OpenSearch Dashboards
Cause: Index doesn't exist or mapping issue
Solution:
- Verify index name is correct
- Check OpenSearch cluster health
- Review OSD logs for errors
Cause: Version conflict or validation error
Solution:
- Refresh the page and try again
- Check if document was modified by another user
- Verify field types match mapping
Cause: Field type mismatch or depth limit
Solution:
- Check field type in mapping viewer
- Use JSON mode for complex changes
- Verify max nested depth setting
| Error | Meaning | Solution |
|---|---|---|
index_not_found_exception |
Index doesn't exist | Check index name |
document_missing_exception |
Document was deleted | Refresh list |
version_conflict_engine_exception |
Concurrent modification | Refresh and retry |
mapper_parsing_exception |
Invalid field value | Check field type |
illegal_argument_exception |
Invalid operation | Check parameters |
If you encounter issues:
- Check browser console (F12 → Console) for JavaScript errors
- Review OSD logs for server-side errors
- Test OpenSearch directly using Dev Tools
- File an issue with:
- Error message
- Steps to reproduce
- Environment details
- Screenshots if applicable
Enable debug logging in opensearch_dashboards.yml:
logging.verbose: true
logging.events.log: ['debug', 'info', 'warning', 'error']For more help, visit our GitHub Discussions or Issues.