Manual Query Editor

Manual Query Editor

The Manual Query Editor provides a direct command-line interface to OstrichDB for advanced users who prefer precise control over database operations. This powerful tool allows you to execute database commands using OstrichDB’s native query language.

Overview

What is the Manual Query Editor?

The Manual Query Editor is:

• Command-line interface: Direct access to database operations
• Terminal-style interface: Familiar environment for developers
• Precise control: Exact specification of operations and parameters
• Advanced features: Access to all database capabilities
• Batch operations: Execute multiple commands in sequence
• Scripting support: Save and reuse command sequences

When to Use Manual Queries

Ideal for:

• Performance-critical operations requiring optimization
• Complex conditional logic not easily expressed in NLP
• Advanced filtering and sorting with specific parameters
• Bulk operations on large datasets
• Automated scripting and batch processing
• Precise control over database operations

Consider alternatives for:

• Simple data entry (use Cluster Editor)
• Exploratory queries (use Natural Language Processing)
• Visual data management (use web interface)
• Learning OstrichDB (start with visual tools)

Accessing the Manual Query Editor

Navigation Methods

Method 1: From Project Navigation

1. Navigate to any project
2. Click “Manual Query Editor” in the sidebar
3. Terminal interface opens with project context

Method 2: From Dashboard

1. Click “Advanced Tools” in the main navigation
2. Select “Manual Query Editor”
3. Choose project context from dropdown

Method 3: Direct URL

• Access via direct link: /query-editor
• Bookmark for quick access
• Available from any page within OstrichDB

Interface Layout

The Manual Query Editor includes:

• Command Input: Terminal-style command prompt
• Output Display: Results and feedback area
• Context Indicator: Current project/collection context
• Command History: Previous commands with up/down arrows
• Help Panel: Quick reference for commands
• Execution Status: Success/error indicators

Query Language Syntax

Basic Command Structure

OstrichDB commands follow this general pattern:

COMMAND <target> [parameters] [modifiers]

Example:

NEW users.profiles.john_doe OF_TYPE STRING WITH "John Doe"

Command Categories

Data Creation Commands

NEW - Create new database objects

NEW <location> [OF_TYPE <type>] [WITH <value>]

Examples:
NEW ecommerce                                    # Create project
NEW ecommerce.products                          # Create collection
NEW ecommerce.products.electronics             # Create cluster
NEW ecommerce.products.electronics.laptop      # Create record (defaults to STRING)
NEW users.profiles.age OF_TYPE INTEGER WITH 25 # Create typed record

Data Retrieval Commands

FETCH - Retrieve data from database

FETCH <location> [modifiers]

Examples:
FETCH ecommerce                                 # Get project info
FETCH ecommerce.products                       # Get collection info
FETCH ecommerce.products.electronics          # Get cluster contents
FETCH ecommerce.products.electronics.laptop   # Get specific record

Data Modification Commands

UPDATE - Modify existing data

UPDATE <location> WITH <new_value> [OF_TYPE <type>]

Examples:
UPDATE users.profiles.age WITH 26
UPDATE products.laptop.price WITH 999.99 OF_TYPE FLOAT
UPDATE settings.theme WITH "dark" OF_TYPE STRING

RENAME - Rename database objects

RENAME <old_location> TO <new_location>

Examples:
RENAME users.temp TO users.archived
RENAME products.electronics.old_laptop TO products.electronics.laptop_v1

Data Deletion Commands

ERASE - Delete database objects

ERASE <location>

Examples:
ERASE temp_data                                # Delete collection
ERASE users.archived.old_user                 # Delete specific record
ERASE projects.test_project                    # Delete entire project

Advanced Query Features

Filtering and Search

FIND - Search for records with conditions

FIND <location> WHERE <condition>

Examples:
FIND users.profiles WHERE TYPE = STRING
FIND products.inventory WHERE VALUE > 100
FIND sessions WHERE NAME CONTAINS "active"

COUNT - Count objects with optional conditions

COUNT <object_type> [IN <location>] [WHERE <condition>]

Examples:
COUNT COLLECTIONS                              # Count all collections
COUNT RECORDS IN users.profiles               # Count records in specific cluster
COUNT CLUSTERS WHERE SIZE > 1MB               # Count large clusters

Metadata Operations

SIZE_OF - Get size information

SIZE_OF <location>

Examples:
SIZE_OF ecommerce                              # Project size
SIZE_OF ecommerce.products                    # Collection size
SIZE_OF ecommerce.products.electronics        # Cluster size

TYPE_OF - Get type information

TYPE_OF <location>

Examples:
TYPE_OF users.profiles.age                     # Returns: INTEGER
TYPE_OF products.inventory.laptop              # Returns: record type

INFO - Get detailed metadata

INFO <location>

Examples:
INFO ecommerce                                 # Project metadata
INFO ecommerce.products.electronics           # Cluster details with creation date, size, etc.

Batch Operations

BATCH - Execute multiple commands

BATCH [
  COMMAND1
  COMMAND2
  COMMAND3
]

Example:
BATCH [
  NEW users.batch_test
  NEW users.batch_test.user1 OF_TYPE STRING WITH "Alice"
  NEW users.batch_test.user2 OF_TYPE STRING WITH "Bob"
  FETCH users.batch_test
]

Data Types in Queries

Specifying Types

When creating records, specify types using OF_TYPE:

Basic Types:

NEW record_name OF_TYPE STRING WITH "text value"
NEW record_name OF_TYPE INTEGER WITH 42
NEW record_name OF_TYPE FLOAT WITH 3.14
NEW record_name OF_TYPE BOOLEAN WITH true
NEW record_name OF_TYPE NULL WITH null

Date and Time Types:

NEW record_name OF_TYPE DATE WITH "2024-01-15"
NEW record_name OF_TYPE TIME WITH "14:30:00"
NEW record_name OF_TYPE DATETIME WITH "2024-01-15T14:30:00Z"

Special Types:

NEW record_name OF_TYPE UUID WITH "550e8400-e29b-41d4-a716-446655440000"
NEW record_name OF_TYPE CREDENTIAL WITH "secret_password"

Array Types:

NEW record_name OF_TYPE []STRING WITH ["item1", "item2", "item3"]
NEW record_name OF_TYPE []INTEGER WITH [1, 2, 3, 4, 5]
NEW record_name OF_TYPE []BOOLEAN WITH [true, false, true]

Type Validation

The query editor validates types in real-time:

• Format checking: Ensures values match type requirements
• Syntax validation: Checks command structure
• Reference validation: Verifies locations exist for operations
• Type consistency: Ensures type conversions are valid

Query Examples

Basic CRUD Operations

Create a complete user profile:

# Create the structure
NEW users
NEW users.profiles
NEW users.profiles.john_doe

# Add profile data
NEW users.profiles.john_doe.name OF_TYPE STRING WITH "John Doe"
NEW users.profiles.john_doe.email OF_TYPE STRING WITH "john@example.com"
NEW users.profiles.john_doe.age OF_TYPE INTEGER WITH 30
NEW users.profiles.john_doe.active OF_TYPE BOOLEAN WITH true
NEW users.profiles.john_doe.created OF_TYPE DATETIME WITH "2024-01-15T10:00:00Z"

# Verify the data
FETCH users.profiles.john_doe

Update user information:

# Update individual fields
UPDATE users.profiles.john_doe.age WITH 31
UPDATE users.profiles.john_doe.email WITH "john.doe@newcompany.com"

# Verify changes
FETCH users.profiles.john_doe.age
FETCH users.profiles.john_doe.email

Search and filter operations:

# Find all active users
FIND users.profiles WHERE active = true

# Count total users
COUNT RECORDS IN users.profiles

# Get user information
INFO users.profiles.john_doe
SIZE_OF users.profiles

Advanced Operations

Batch user creation:

BATCH [
  NEW users.profiles.alice.name OF_TYPE STRING WITH "Alice Smith"
  NEW users.profiles.alice.email OF_TYPE STRING WITH "alice@example.com"
  NEW users.profiles.alice.age OF_TYPE INTEGER WITH 28
  NEW users.profiles.bob.name OF_TYPE STRING WITH "Bob Johnson"
  NEW users.profiles.bob.email OF_TYPE STRING WITH "bob@example.com"
  NEW users.profiles.bob.age OF_TYPE INTEGER WITH 35
  NEW users.profiles.charlie.name OF_TYPE STRING WITH "Charlie Brown"
  NEW users.profiles.charlie.email OF_TYPE STRING WITH "charlie@example.com"
  NEW users.profiles.charlie.age OF_TYPE INTEGER WITH 42
]

Data migration example:

# Create new structure
NEW users_v2
NEW users_v2.profiles

# Copy data (manual process in current version)
FETCH users.profiles.john_doe.name
NEW users_v2.profiles.john_doe.name OF_TYPE STRING WITH "John Doe"

# Rename old structure
RENAME users TO users_backup
RENAME users_v2 TO users

# Verify migration
FETCH users.profiles.john_doe

Command Reference

Core Commands

Command	Purpose	Syntax
NEW	Create objects	NEW <location> [OF_TYPE <type>] [WITH <value>]
FETCH	Retrieve data	FETCH <location>
UPDATE	Modify data	UPDATE <location> WITH <value> [OF_TYPE <type>]
ERASE	Delete objects	ERASE <location>
RENAME	Rename objects	RENAME <old> TO <new>

Information Commands

Command	Purpose	Syntax
COUNT	Count objects	COUNT <type> [IN <location>] [WHERE <condition>]
SIZE_OF	Get size	SIZE_OF <location>
TYPE_OF	Get type	TYPE_OF <location>
INFO	Get metadata	INFO <location>

Utility Commands

Command	Purpose	Syntax
HELP	Show help	HELP [command]
VERSION	Show version	VERSION
CLEAR	Clear terminal	CLEAR
HISTORY	Show history	HISTORY

System Commands

Command	Purpose	Syntax
CONNECT	Connect to project	CONNECT <project_name>
STATUS	Show connection status	STATUS
EXIT	Exit editor	EXIT

Error Handling

Common Error Types

Syntax Errors:

❌ NEW users profiles john_doe
✅ NEW users.profiles.john_doe

❌ FETCH users profiles
✅ FETCH users.profiles

Type Errors:

❌ NEW age OF_TYPE INTEGER WITH "twenty-five"
✅ NEW age OF_TYPE INTEGER WITH 25

❌ NEW active OF_TYPE BOOLEAN WITH "yes"
✅ NEW active OF_TYPE BOOLEAN WITH true

Reference Errors:

❌ FETCH nonexistent.collection
Error: Collection 'nonexistent' does not exist

❌ UPDATE users.profiles.missing WITH "value"
Error: Record 'missing' not found in cluster 'profiles'

Error Messages

The query editor provides detailed error information:

• Error type: Syntax, reference, type, or permission error
• Error location: Specific part of command causing the issue
• Suggested fix: Recommended correction for the error
• Context information: Related information to help debug

Recovery Strategies

Command History:

• Use up/down arrows to navigate previous commands
• Edit and retry failed commands
• Save successful command sequences for reuse

Verification Steps:

• Use FETCH to verify data before operations
• Use INFO to check object existence
• Use COUNT to verify bulk operation results

Performance Optimization

Efficient Query Patterns

Batch Operations:

• Group related operations into BATCH commands
• Reduce network round-trips for multiple operations
• Atomic execution ensures consistency

Targeted Queries:

• Use specific paths rather than broad searches
• Filter early to reduce data processing
• Use appropriate data types for better performance

Connection Management:

• Maintain persistent connections for multiple queries
• Use connection pooling for high-frequency operations
• Monitor connection status with STATUS command

Best Practices

Query Organization:

• Structure queries logically with clear intentions
• Use comments (# prefix) to document complex operations
• Test with small datasets before running on production data
• Save frequently used command sequences

Error Prevention:

• Verify paths before performing destructive operations
• Use INFO commands to understand data structure
• Test syntax with simple commands first
• Backup important data before major changes

Keyboard Shortcuts

Navigation

• Up/Down arrows: Navigate command history
• Ctrl/Cmd + L: Clear terminal screen
• Tab: Auto-complete commands and paths
• Ctrl/Cmd + C: Cancel current command

Editing

• Ctrl/Cmd + A: Select entire command line
• Ctrl/Cmd + U: Clear current line
• Ctrl/Cmd + K: Delete from cursor to end of line
• Ctrl/Cmd + W: Delete previous word

Execution

• Enter: Execute current command
• Ctrl/Cmd + Enter: Execute command and keep in editor
• Escape: Cancel current input

Integration with Other Tools

Exporting Query Results

Save to File:

FETCH users.profiles > user_data.json
SIZE_OF ecommerce > project_stats.txt

Copy to Clipboard:

• Results automatically copyable from output area
• Use browser’s copy functionality for formatted results
• Export large datasets via API for external processing

API Integration

Command Generation:

• Manual queries can be converted to API calls
• Use query editor to prototype API operations
• Test complex operations before API implementation

Scripting Support:

• Save command sequences as scripts
• Automate repetitive operations
• Integration with external tools and workflows

Next Steps

Master the Manual Query Editor by:

1. Start Simple: Begin with basic NEW, FETCH, and UPDATE commands
2. Practice Regularly: Use the editor for routine database operations
3. Learn Shortcuts: Master keyboard shortcuts for efficiency
4. Combine Tools: Use with Natural Language Processing for complex workflows
5. API Integration: Apply query knowledge to REST API usage

The Manual Query Editor provides the most direct and powerful interface to OstrichDB. With practice, it becomes an indispensable tool for advanced database management and automation.