Query Structure

Query Structure

OstrichDB CLI uses an intuitive query structure based on CLPs (Command, Location, Parameter) tokens and dot notation syntax. This system provides clear, readable queries that follow the hierarchical data organization.

CLP Token System

Overview

Every OstrichDB query is built using three types of tokens:

1. (C)ommand Token: Specifies the operation to perform
2. (L)ocation Token: Defines the path using dot notation
3. (P)arameter Token: Additional modifiers for the operation

Note: Not all queries require all three token types.

Token Breakdown

NEW foo.bar.baz OF_TYPE []STRING WITH value1,value2,value3
│   │           │              │    │
│   │           │              │    └─ Parameter value
│   │           │              └─ Parameter token
│   │           └─ Parameter token
│   └─ Location token (dot notation path)
└─ Command token

Dot Notation Syntax

Hierarchical Path Structure

OstrichDB uses dot notation to represent the data hierarchy:

collection.cluster.record
│          │       │
│          │       └─ Record name (third level)
│          └─ Cluster name (second level)
└─ Collection name (first level)

Path Examples

# Simple three-level path
users.active.john_doe
│     │      │
│     │      └─ Record: john_doe
│     └─ Cluster: active
└─ Collection: users

# Complex business structure
company.departments.engineering.team_lead
│       │           │           │
│       │           │           └─ Record: team_lead
│       │           └─ Cluster: engineering
│       └─ Cluster: departments
└─ Collection: company

Path Resolution Rules

1. First Level: Always refers to a collection
2. Second Level: Always refers to a cluster within the collection
3. Third Level: Always refers to a record within the cluster
4. Auto-Creation: Missing collections and clusters are created automatically
5. Case Sensitive: Users and users are different paths

Command Tokens

Single-Token Commands

Commands that work independently without additional arguments:

# System commands
VERSION          # Show OstrichDB version
HELP            # Display help information
CLEAR           # Clear the terminal screen
EXIT            # Exit OstrichDB CLI
RESTART         # Restart the program
LOGOUT          # Log out current user

# Data exploration
TREE            # Show entire data structure
HISTORY         # Show command history

# Server operations
SERVE           # Start HTTP server
AGENT           # Start natural language processor

# Maintenance
BENCHMARK       # Run performance tests
DESTROY         # Completely destroy all data (use with caution)

Multi-Token Commands

Commands that require additional tokens to complete the operation:

# Data manipulation
NEW             # Create collections, clusters, records, or users
FETCH           # Retrieve data from any level
ERASE           # Delete collections, clusters, or records
RENAME          # Rename existing objects
SET             # Assign values to records or configurations

# Data analysis
COUNT           # Count objects (COLLECTIONS, CLUSTERS, RECORDS)
SIZE_OF         # Get size in bytes of objects
TYPE_OF         # Get the data type of a record
WHERE           # Search for records or clusters

# Data management
BACKUP          # Create collection backups
PURGE           # Remove data while keeping structure
VALIDATE        # Check collection integrity
ISOLATE         # Quarantine collections
LOCK            # Set collection access modes
UNLOCK          # Remove collection restrictions

# Security
ENC             # Encrypt collections
DEC             # Decrypt collections

# Import/Export
IMPORT          # Import CSV or JSON files

Parameter Tokens

Modifier Tokens

Parameters that modify command behavior:

OF_TYPE         # Specify data type for records
WITH            # Assign value during creation
TO              # Target for rename/assignment operations

Usage Examples

# OF_TYPE: Specify data type
NEW users.staff.employee_name OF_TYPE STRING

# WITH: Assign value during creation
NEW products.electronics.laptop OF_TYPE INTEGER WITH 25

# TO: Rename or reassign
RENAME old_collection TO new_collection
SET CONFIG AUTO_SERVE TO true

# Combined parameters
NEW inventory.books.count OF_TYPE INTEGER WITH 150

Query Construction Patterns

Basic Patterns

Create and Assign

# Pattern: NEW location OF_TYPE type WITH value
NEW blog.posts.title OF_TYPE STRING WITH "My First Post"
NEW inventory.products.stock OF_TYPE INTEGER WITH 100
NEW settings.features.enabled OF_TYPE BOOLEAN WITH true

Fetch Data

# Pattern: FETCH location
FETCH blog.posts.title
FETCH inventory.products
FETCH settings

Rename Objects

# Pattern: RENAME old_location TO new_location
RENAME blog.posts TO blog.articles
RENAME inventory.products.old_item TO inventory.products.new_item

Count Objects

# Pattern: COUNT object_type [IN location]
COUNT COLLECTIONS
COUNT CLUSTERS IN inventory
COUNT RECORDS IN blog.posts

Advanced Patterns

Conditional Operations

# Search and modify
WHERE laptop
RENAME products.electronics.laptop TO products.electronics.notebook

# Validate and backup
VALIDATE important_data
BACKUP important_data

Bulk Operations with Chaining

# Create multiple related records
NEW users.staff.alice OF_TYPE STRING WITH "Alice Johnson" && NEW users.staff.alice_role OF_TYPE STRING WITH "Developer" && NEW users.staff.alice_salary OF_TYPE FLOAT WITH 75000.50

Location Token Deep Dive

Collection Names

Collections are the top-level containers:

# Good collection names
users           # Simple, descriptive
blog_posts      # Underscore separation
company_data    # Clear purpose
inventory_2024  # Version/date inclusion

# Avoid
data            # Too generic
stuff           # Not descriptive
collection1     # Not meaningful

Cluster Names

Clusters organize records within collections:

# Logical cluster organization
users.active            # Status-based
users.inactive
users.administrators

products.electronics    # Category-based
products.books
products.clothing

blog.published_posts    # State-based
blog.draft_posts
blog.archived_posts

Record Names

Records store the actual data:

# Descriptive record names
users.staff.john_doe_email      # Person + attribute
products.laptops.dell_xps_price # Category + model + attribute
blog.posts.welcome_post_title   # Context + identifier + attribute

# Use consistent naming patterns
users.staff.alice_name
users.staff.alice_email
users.staff.alice_department

Query Chaining

Chain Operator

Use && to execute multiple queries in sequence:

# Basic chaining
NEW users.staff.bob OF_TYPE STRING WITH "Bob Smith" && FETCH users.staff.bob

# Complex chaining
NEW company.engineering.team_size OF_TYPE INTEGER WITH 5 && NEW company.engineering.budget OF_TYPE FLOAT WITH 500000.00 && COUNT RECORDS IN company.engineering && TREE

Chaining Best Practices

Related Operations

# Good: Group related operations
NEW project.webapp.name OF_TYPE STRING WITH "Company Website" && NEW project.webapp.status OF_TYPE STRING WITH "In Progress" && NEW project.webapp.deadline OF_TYPE DATE WITH 2024-06-15

# Less efficient: Separate unrelated operations
NEW project.webapp.name OF_TYPE STRING WITH "Company Website" && COUNT COLLECTIONS && HELP NEW

Error Handling in Chains

# If any operation in a chain fails, subsequent operations are skipped
NEW invalid.path.record OF_TYPE INVALID_TYPE WITH value && FETCH valid.path.record
# The FETCH won't execute if NEW fails

Query Examples by Use Case

User Management

# Create user structure
NEW users.active.john_smith OF_TYPE STRING WITH "John Smith"
NEW users.active.john_email OF_TYPE STRING WITH "john@company.com"
NEW users.active.john_role OF_TYPE STRING WITH "developer"
NEW users.active.john_hire_date OF_TYPE DATE WITH 2024-01-15

# Fetch user information
FETCH users.active.john_smith
FETCH users.active

# Manage user status
RENAME users.active.john_smith TO users.inactive.john_smith

Inventory Tracking

# Stock management
NEW inventory.electronics.laptops OF_TYPE INTEGER WITH 25
NEW inventory.electronics.phones OF_TYPE INTEGER WITH 50
NEW inventory.books.programming OF_TYPE INTEGER WITH 100

# Check inventory levels
FETCH inventory.electronics
COUNT RECORDS IN inventory.electronics
SIZE_OF inventory

Project Management

# Project setup
NEW projects.website.status OF_TYPE STRING WITH "Planning"
NEW projects.website.team_members OF_TYPE []STRING WITH "Alice,Bob,Carol"
NEW projects.website.deadline OF_TYPE DATE WITH 2024-08-01
NEW projects.website.budget OF_TYPE FLOAT WITH 75000.00

# Project tracking
FETCH projects.website.status
COUNT RECORDS IN projects.website
WHERE deadline

Content Management

# Blog post creation
NEW blog.posts.welcome_title OF_TYPE STRING WITH "Welcome to Our Blog"
NEW blog.posts.welcome_content OF_TYPE STRING WITH "This is our first blog post..."
NEW blog.posts.welcome_author OF_TYPE STRING WITH "Jane Doe"
NEW blog.posts.welcome_published OF_TYPE DATETIME WITH 2024-01-15T10:00:00

# Content organization
COUNT RECORDS IN blog.posts
BACKUP blog
TREE

Error Prevention

Common Query Mistakes

Invalid Paths

# Wrong: Missing cluster level
NEW users.john_doe OF_TYPE STRING WITH "John"
# Correct: Include all three levels
NEW users.staff.john_doe OF_TYPE STRING WITH "John"

Type Mismatches

# Wrong: Invalid type
NEW products.count OF_TYPE INVALID_TYPE WITH 50
# Correct: Use valid type
NEW products.electronics.count OF_TYPE INTEGER WITH 50

Parameter Order

# Wrong: Parameters in wrong order
NEW users.staff.alice WITH "Alice" OF_TYPE STRING
# Correct: Proper parameter order
NEW users.staff.alice OF_TYPE STRING WITH "Alice"

Validation Queries

# Check before operations
TYPE_OF users.staff.employee_count  # Verify data type
SIZE_OF large_collection             # Check collection size
VALIDATE collection_name             # Verify integrity

Query Optimization

Efficient Querying

# Efficient: Specific paths
FETCH users.staff.specific_record

# Less efficient: Broad fetches followed by filtering
FETCH users
# Then manually looking for specific data

Batch Operations

# Use chaining for related operations
NEW company.dept.engineering OF_TYPE STRING WITH "Engineering Department" && NEW company.dept.engineering_head OF_TYPE STRING WITH "Alice Johnson" && NEW company.dept.engineering_size OF_TYPE INTEGER WITH 15

# Instead of separate queries
NEW company.dept.engineering OF_TYPE STRING WITH "Engineering Department"
NEW company.dept.engineering_head OF_TYPE STRING WITH "Alice Johnson"
NEW company.dept.engineering_size OF_TYPE INTEGER WITH 15

Best Practices

Naming Conventions

1. Use descriptive names: user_email instead of email
2. Be consistent: If you use underscores, use them everywhere
3. Include context: blog_post_title instead of just title
4. Use logical grouping: Group related records in the same cluster

Query Organization

1. Plan your hierarchy: Design your collection/cluster structure before creating data
2. Use appropriate levels: Don’t create unnecessary nesting
3. Group related operations: Use query chaining for related tasks
4. Validate early: Check data types and structure before complex operations

Performance Tips

1. Use specific paths: Avoid broad FETCH operations when possible
2. Chain related queries: Reduce the number of separate operations
3. Regular maintenance: Use VALIDATE and SIZE_OF to monitor collections
4. Clean up: Use ERASE to remove unused data structures

Next Steps

Now that you understand query structure:

1. Explore Commands Reference - Learn all available commands in detail
2. Master Data Types - Understand type system and validation
3. Configure Your Setup - Customize OstrichDB behavior
4. Practice: Use the patterns and examples to build your own queries

The CLP system and dot notation make OstrichDB queries both powerful and readable. Master these concepts to efficiently manage your hierarchical data.