Cluster Editor

Cluster Editor

The Cluster Editor is OstrichDB’s visual interface for building and managing data clusters. It provides an intuitive, spreadsheet-like experience for working with your database records without needing to write code or complex queries.

Overview

What is the Cluster Editor?

The Cluster Editor is a powerful visual tool that allows you to:

• Create new clusters with records and data types
• Edit existing clusters by modifying records and values
• Manage data types with visual type selection
• Validate data in real-time as you type
• Bulk operations for efficient data management
• Visual data structure for easy understanding

When to Use the Cluster Editor

Ideal for:

• Creating new data structures
• Adding records to existing clusters
• Modifying data values and types
• Exploring and understanding your data
• Prototyping database schemas
• Learning OstrichDB’s data model

Consider alternatives for:

• Large bulk data imports (use API)
• Complex queries across multiple clusters (use NLP or Manual Query Editor)
• Automated data operations (use API)
• Advanced filtering and analysis (use query interfaces)

Accessing the Cluster Editor

Navigation Methods

Method 1: From Dashboard

1. Navigate to any project
2. Click “Cluster Editor” in the main navigation
3. Select project and collection context

Method 2: From Collection View

1. Navigate to a collection
2. Click “Create Cluster” or “Edit Cluster”
3. Opens directly in the Cluster Editor

Method 3: Direct Link

• Use the “Cluster Editor” link in the sidebar
• Available from anywhere within a project

Interface Layout

The Cluster Editor interface includes:

• Navigation Bar: Project and collection context
• Cluster Selector: Choose existing cluster or create new
• Record Grid: Spreadsheet-like interface for records
• Type Selector: Dropdown for data types
• Action Buttons: Save, cancel, and operation controls
• Validation Panel: Real-time error and warning display

Creating New Clusters

Step-by-Step Cluster Creation

1. Open the Cluster Editor from your chosen navigation method
2. Enter a cluster name in the cluster name field
3. Click “Add Record” to start adding data
4. Configure each record with name, type, and value
5. Click “Confirm Cluster Creation” to save

Cluster Naming Rules

Cluster names must follow these conventions:

• Maximum length: 64 characters
• Allowed characters: Letters, numbers, underscores (_), hyphens (-)
• No spaces: Use underscores or hyphens instead
• Unique within collection: Cannot duplicate existing cluster names
• Case sensitive: “UserData” and “userdata” are different

Valid Examples:

• active_users
• product_inventory
• user-preferences
• session_data_2024

Adding Records to New Clusters

Record Configuration: Each record requires three components:

1. Name: Unique identifier for the record
2. Type: Data type from the supported types list
3. Value: The actual data content

Record Name Rules:

• Must be unique within the cluster
• No spaces allowed (use underscores or hyphens)
• Letters, numbers, underscores, and hyphens only
• Maximum 64 characters
• Case sensitive

Working with Data Types

Available Data Types

The Cluster Editor provides easy access to all OstrichDB data types:

Primitive Types:

• CHAR: Single character values
• STRING: Text of any length
• INTEGER: Whole numbers (-42, 0, 123)
• BOOLEAN: true or false values
• FLOAT: Decimal numbers (3.14, -0.5)
• NULL: Empty or null values

Date & Time Types:

• DATE: YYYY-MM-DD format (2024-01-15)
• TIME: HH:MM:SS format (14:30:00)
• DATETIME: YYYY-MM-DDTHH:MM:SS format (2024-01-15T14:30:00Z)

Special Types:

• UUID: Universally unique identifiers
• CREDENTIAL: Encrypted sensitive data

Array Types:

• []CHAR, []STRING, []INTEGER, []BOOLEAN, []FLOAT
• []DATE, []TIME, []DATETIME, []UUID

Type Selection Interface

Dropdown Selection:

• Click the Type dropdown for any record
• Search for types by typing
• Categories group similar types together
• Tooltips explain each data type
• Examples show expected value formats

Type Validation:

• Real-time validation as you select types
• Format hints appear below the value field
• Error indicators highlight invalid combinations
• Auto-correction suggestions for common mistakes

Data Validation and Entry

Real-Time Validation

The Cluster Editor validates data as you type:

Format Validation:

• STRING: Any text is valid
• INTEGER: Must be whole numbers (-123, 0, 456)
• FLOAT: Must be decimal numbers (3.14, -0.5, 2.0)
• BOOLEAN: Must be exactly “true” or “false”
• DATE: Must match YYYY-MM-DD format
• TIME: Must match HH:MM:SS format
• DATETIME: Must match ISO 8601 format

Array Validation:

• JSON Format: Arrays must be valid JSON syntax
• Type Consistency: All array elements must match the base type
• Bracket Format: Must start with [ and end with ]
• Comma Separation: Elements separated by commas

Validation Examples

Valid Entries:

STRING: "Hello, World!"
INTEGER: 42
FLOAT: 3.14159
BOOLEAN: true
DATE: 2024-01-15
[]STRING: ["apple", "banana", "cherry"]
[]INTEGER: [1, 2, 3, 4, 5]

Invalid Entries (with corrections):

❌ INTEGER: "42" → ✅ INTEGER: 42
❌ BOOLEAN: "yes" → ✅ BOOLEAN: true
❌ DATE: "01/15/2024" → ✅ DATE: "2024-01-15"
❌ []STRING: apple,banana → ✅ []STRING: ["apple", "banana"]

Error Handling

Visual Error Indicators:

• Red borders around invalid fields
• Error messages below problematic entries
• Tooltips with correction suggestions
• Blocked saves until all errors are resolved

Common Error Messages:

• “Invalid integer format” - Use whole numbers only
• “Date must be YYYY-MM-DD format” - Check date format
• “Array must be valid JSON” - Use proper JSON syntax
• “Record name already exists” - Choose a unique name

Editing Existing Clusters

Loading Existing Clusters

1. Open the Cluster Editor
2. Select your project and collection from the context selectors
3. Choose an existing cluster from the cluster dropdown
4. Records load automatically into the editor grid
5. Make your changes and save

Modification Operations

Adding Records:

1. Click “Add Record” button
2. Fill in name, type, and value
3. Validate the new record
4. Save changes to update the cluster

Editing Records:

1. Click on any field to edit (name, type, or value)
2. Make your changes while validation runs in real-time
3. Tab or click away to confirm changes
4. Save the cluster to persist changes

Deleting Records:

1. Click the delete button (❌) next to any record
2. Confirm the deletion in the popup dialog
3. Record is removed from the editor grid
4. Save changes to make deletion permanent

Bulk Operations

Select Multiple Records:

• Shift-click to select ranges
• Ctrl/Cmd-click to select individual records
• Select All checkbox for entire cluster

Bulk Actions:

• Delete Selected: Remove multiple records at once
• Change Type: Update data type for multiple records
• Export Selected: Download selected records as JSON/CSV
• Duplicate Records: Create copies with modified names

Advanced Features

Cluster Templates

Save as Template:

• Create reusable cluster structures
• Export schema without data
• Share templates with team members
• Version control for schema changes

Load from Template:

• Quick start with predefined structures
• Consistent schemas across projects
• Best practices built into templates
• Customizable after loading

Data Import/Export

Import Data:

• CSV Import: Upload CSV files with automatic type detection
• JSON Import: Import structured JSON data
• Paste from Clipboard: Copy-paste from spreadsheets
• Type Mapping: Configure how imported data maps to OstrichDB types

Export Data:

• JSON Export: Complete cluster data with metadata
• CSV Export: Spreadsheet-compatible format
• Schema Export: Structure only, no data
• Filtered Export: Export only selected records

Performance Features

Lazy Loading:

• Large clusters load records in batches
• Smooth scrolling through thousands of records
• Search filtering to find specific records quickly
• Pagination controls for navigation

Auto-Save:

• Draft mode saves changes locally
• Conflict detection if multiple users edit simultaneously
• Version history for tracking changes
• Undo/Redo functionality

Best Practices

Efficient Cluster Design

Record Organization:

• Group related data in the same cluster
• Use consistent naming conventions
• Choose appropriate types for data
• Avoid overly large clusters (consider splitting at 100+ records)

Performance Optimization:

• Index frequently queried records by putting them first
• Use specific types rather than generic STRING when possible
• Normalize data to reduce redundancy
• Regular cleanup of unused records

Data Quality

Validation Best Practices:

• Validate at entry rather than fixing later
• Use consistent formats across similar data
• Document your schema decisions
• Test with real data before production use

Naming Conventions:

• Use descriptive names that indicate purpose
• Be consistent with your naming patterns
• Avoid abbreviations unless they’re clear
• Use prefixes for related records (user_name, user_email, user_age)

Troubleshooting

Common Issues

“Cluster name already exists”

• Solution: Choose a unique name within the collection
• Check: Look at existing cluster names before creating
• Alternative: Add version numbers or descriptive suffixes

“Invalid data format”

• Solution: Check the data type requirements and format your value accordingly
• Reference: Use the format hints and examples provided
• Validation: Pay attention to real-time validation feedback

“Cannot save cluster”

• Solution: Resolve all validation errors before saving
• Check: Look for red borders and error messages
• Required: Ensure all records have names, types, and valid values

“Record name is required”

• Solution: Every record must have a unique name
• Format: Follow naming rules (no spaces, alphanumeric plus underscore/hyphen)
• Uniqueness: Names must be unique within the cluster

Performance Issues

Slow loading with large clusters:

• Solution: Enable pagination in settings
• Alternative: Split large clusters into smaller, focused ones
• Optimization: Use search/filter to work with specific records

Editor becomes unresponsive:

• Solution: Refresh the page to reset the editor
• Prevention: Save frequently when working with large datasets
• Workaround: Use API for very large bulk operations

Keyboard Shortcuts

Navigation

• Tab: Move to next field
• Shift + Tab: Move to previous field
• Enter: Confirm current field and move down
• Escape: Cancel current edit

Editing

• Ctrl/Cmd + S: Save cluster
• Ctrl/Cmd + Z: Undo last action
• Ctrl/Cmd + Y: Redo last action
• Delete: Remove selected records

Selection

• Ctrl/Cmd + A: Select all records
• Shift + Click: Select range of records
• Ctrl/Cmd + Click: Toggle selection of individual records

Next Steps

Once you’re comfortable with the Cluster Editor:

1. Explore Advanced Features: Try templates, import/export, and bulk operations
2. Learn Query Interfaces: Use Natural Language Queries for complex operations
3. API Integration: Connect your applications using the REST API
4. Optimize Performance: Apply best practices for large-scale data management
5. Team Collaboration: Share clusters and templates with team members (Pro/Enterprise)

The Cluster Editor is your primary tool for hands-on data management in OstrichDB. Master it to efficiently build, modify, and maintain your database structures.