README.md

Open-Ostrich

Open-source implementation of the OstrichDB database backend written in Odin.

Overview

Open-Ostrich is the open-source version of OstrichDB, a hierarchical NoSQL database system designed for efficient data organization and retrieval. This implementation provides the core database engine functionality with a RESTful API server, written entirely in the Odin programming language.

Note: This is the open-source reference implementation. The production OstrichDB backend is closed-source and may contain additional enterprise features.

Architecture

OstrichDB uses a hierarchical data structure organized as:

Projects
  Collections
     Clusters
        Records

Core Components

• Engine (src/core/engine/): Core database engine and data processing logic
• Server (src/core/server/): HTTP server with RESTful API endpoints
• Data Layer (src/core/engine/data/): Data structures and file operations for Collections, Clusters, and Records
• Security (src/core/engine/security/): Encryption, decryption, and key management
• Configuration (src/core/config/): Configuration management and dynamic path handling
• Projects (src/core/engine/projects/): Project lifecycle and user isolation
• Library (src/library/): Common types, utilities, and shared functionality

Features

Data Management

• Hierarchical Organization: Projects contain Collections, which contain Clusters of Records
• Rich Data Types: Support for strings, integers, floats, booleans, dates, arrays, and more
• Flexible Querying: Search, filter, and sort records with query parameters
• User Isolation: Multi-tenant architecture with user-specific project spaces

Security

• End-to-End Encryption: Collections can be encrypted with user-specific master keys
• JWT Authentication: Token-based authentication for API access
• Access Control: User-based project ownership and access verification
• Secure Operations: Automatic encrypt/decrypt cycles for data operations

API & Server

• RESTful API: Complete REST API with /api/v1/ endpoints
• CORS Support: Configurable cross-origin resource sharing
• Health Monitoring: Built-in health check and server monitoring
• Request Logging: Comprehensive logging and audit trails

API Endpoints

Projects

• GET /api/v1/projects - List user's projects
• POST /api/v1/projects/{name} - Create new project
• PUT /api/v1/projects/{name}?rename={newname} - Rename project
• DELETE /api/v1/projects/{name} - Delete project

Collections

• GET /api/v1/projects/{project}/collections - List collections in project
• POST /api/v1/projects/{project}/collections/{name} - Create collection
• GET /api/v1/projects/{project}/collections/{name} - Get collection info
• PUT /api/v1/projects/{project}/collections/{name}?rename={newname} - Rename collection
• DELETE /api/v1/projects/{project}/collections/{name} - Delete collection

Clusters

• GET /api/v1/projects/{project}/collections/{collection}/clusters - List clusters
• POST /api/v1/projects/{project}/collections/{collection}/clusters/{name} - Create cluster
• GET /api/v1/projects/{project}/collections/{collection}/clusters/{name} - Get cluster data
• PUT /api/v1/projects/{project}/collections/{collection}/clusters/{name}?rename={newname} - Rename cluster
• DELETE /api/v1/projects/{project}/collections/{collection}/clusters/{name} - Delete cluster

Records

• GET /api/v1/projects/{project}/collections/{collection}/clusters/{cluster}/records - List records
• POST /api/v1/projects/{project}/collections/{collection}/clusters/{cluster}/records/{name}?type={TYPE}&value={value} - Create record
• GET /api/v1/projects/{project}/collections/{collection}/clusters/{cluster}/records/{id_or_name} - Get specific record
• PUT /api/v1/projects/{project}/collections/{collection}/clusters/{cluster}/records/{name}?{update_params} - Update record
• DELETE /api/v1/projects/{project}/collections/{collection}/clusters/{cluster}/records/{name} - Delete record

Filtering & Search

Records support advanced querying with parameters:

• ?type=STRING - Filter by data type
• ?search=pattern - Search in record names
• ?value=exact - Match exact values
• ?valueContains=partial - Partial value matching
• ?sortBy=name|value|type|id - Sort results
• ?sortOrder=asc|desc - Sort direction
• ?limit=N&offset=N - Pagination

Configuration

The server uses JSON configuration files in the config/ directory:

• development.json - Development environment settings
• production.json - Production environment settings

Key configuration sections:

• Server: Port, host, connection limits
• Database: Storage paths, file size limits, backup settings
• Security: Encryption, authentication, rate limiting
• CORS: Cross-origin request handling
• Logging: Log levels, file rotation, audit trails

Getting Started

Prerequisites

• Odin compiler installed
• Basic understanding of hierarchical database concepts

Building and Running

1. Clone the repository

   git clone <repository-url>
   cd Open-Ostrich

2. Build and run the project

   ./scripts/local_build.sh

The build script will compile the project and start the server on localhost:8042 by default (configurable in config/development.json).

First-Time Setup

Uncomment the setup functions in main/main.odin for initial user and project creation:

// create_test_user()
// test_project_creation()

Data Types

OstrichDB supports rich data types for records:

Basic Types:

• STRING / STR / CHAR
• INTEGER / INT
• FLOAT / FLT
• BOOLEAN / BOOL
• DATE, TIME, DATETIME
• UUID
• NULL
• CREDENTIAL (encrypted)

Array Types:

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

Development

Contributing

This is the open-source reference implementation of OstrichDB. Contributions are welcome for:

• Bug fixes and stability improvements
• Performance optimizations
• Documentation enhancements
• Additional query features
• Security improvements

Architecture Notes

• Memory Management: Manual memory management with defer cleanup
• Error Handling: Custom error system with location tracking
• Security: Automatic encryption/decryption for secure operations

License

Copyright (c) 2025-Present Marshall A Burns and Archetype Dynamics, Inc.

Licensed under the Apache License, Version 2.0. See LICENSE.md for details.

---

Note: This open-source version provides the core OstrichDB functionality. For enterprise features and support, please contact Archetype Dynamics, Inc.

OstrichDB Frontend Docs

OstrichDB User Documentation

Overview

OstrichDB is a modern NoSQL database management system that combines the simplicity of SQLite, the flexibility of MongoDB, and the security of enterprise-grade solutions. Built with the Odin programming language, OstrichDB provides a hierarchical data structure, strong typing, built-in encryption, and natural language query capabilities.

Key Features

• Hierarchical Organization: Projects → Collections → Clusters → Records
• Strong Typing: Every record must have an explicit type at creation time
• Built-in Security: AES-256 encryption per collection (no enterprise upsells)
• Natural Language Queries: Ask questions in plain English
• Native Performance: Compiled to native code for maximum speed
• Zero Configuration: Start building immediately without setup

Getting Started

1. Account Creation and Authentication

Sign Up:

1. Visit the OstrichDB homepage
2. Click "Start Building Free" or "Sign Up"
3. Complete registration using Clerk authentication
4. Verify your email address

Sign In:

1. Click "Sign In" on the homepage
2. Enter your credentials
3. You'll be redirected to your dashboard

2. Dashboard Overview

After signing in, you'll see your personalized dashboard showing:

• Projects: Top-level containers for your databases
• Quick Actions: Create new projects, collections, and clusters
• Account Status: Your current tier (Free, Pro, or Enterprise)
• Backend Connection Status: Green indicator shows active connection

Data Hierarchy

OstrichDB uses a 4-level hierarchical structure:

Project
├── Collection (Database)
    ├── Cluster (Data Group)
        ├── Record (Individual Data Entry)
            ├── Name: unique identifier
            ├── Type: explicit data type
            └── Value: the actual data

Working with Projects

Creating a Project

1. From the dashboard, click "Create New Project"
2. Enter a project name (letters, numbers, underscores, hyphens only)
3. Set a password (optional but recommended)
4. Click "Create Project"

Project Naming Rules:

• Maximum 32 characters
• Only letters, numbers, underscores (_), and hyphens (-)
• No spaces allowed
• Must be unique within your account

Managing Projects

Rename a Project:

1. Click the three-dot menu (⋮) on any project card
2. Select "Rename Project"
3. Enter the new name
4. Click "Rename Project"

Delete a Project:

1. Click the three-dot menu (⋮) on any project card
2. Select "Delete Project"
3. Type the exact project name to confirm
4. Click "Delete Project"

⚠️ Warning: Deleting a project permanently removes all collections, clusters, and records.

Project Sorting

Sort your projects by:

• Alphabetical (A-Z): Default sorting
• Number of Collections: Projects with most collections first
• Project Size: Largest projects first
• Last Modified: Most recently modified first

Working with Collections

Collections are equivalent to databases in traditional systems. Each collection can contain multiple clusters of related data.

Creating a Collection

1. Navigate to a project
2. Click "Create New Collection"
3. Enter a collection name (same naming rules as projects)
4. Click "Create Collection"

Collection Features

Automatic Encryption:

• All collections use AES-256 encryption by default
• No additional setup required
• No enterprise fees for encryption

Collection Metadata:

• Creation date
• Last modified date
• Total size
• Number of clusters

Managing Collections

Rename a Collection:

1. Click the three-dot menu (⋮) on any collection card
2. Select "Rename Collection"
3. Enter the new name
4. Click "Rename Collection"

Delete a Collection:

1. Click the three-dot menu (⋮) on any collection card
2. Select "Delete Collection"
3. Type the exact collection name to confirm
4. Click "Delete Collection"

Working with Clusters

Clusters group related records together, similar to tables in relational databases but with more flexibility.

Creating a Cluster

Method 1: From Collection Overview

1. Navigate to a collection
2. Click "Create Cluster"
3. This opens the Cluster Editor

Method 2: From Cluster Editor

1. Navigate to any project/collection
2. Click "Cluster Editor" in the navigation
3. Search for existing clusters or create new ones

Cluster Editor

The Cluster Editor is a visual interface for building and managing data clusters:

Creating a New Cluster:

1. Enter a cluster name
2. Click "Add Record" to start adding data
3. Configure each record with:
   • Name: Unique identifier for the record
   • Type: Data type from available options
   • Value: The actual data content
4. Click "Confirm Cluster Creation" to save

Editing Existing Clusters:

1. Search for and select a cluster
2. Modify records, types, or values
3. Add or remove records as needed
4. Click "Confirm Changes" to save

Data Types

OstrichDB supports strongly-typed records with these data types:

Primitive Types:

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

Date & Time:

• DATE: YYYY-MM-DD format
• TIME: HH:MM:SS format
• DATETIME: YYYY-MM-DDTHH:MM:SS format

Identifiers:

• UUID: Universally unique identifier

Array Types:

• []CHAR: Array of characters
• []STRING: Array of text strings
• []INTEGER: Array of whole numbers
• []BOOLEAN: Array of boolean values
• []FLOAT: Array of decimal numbers
• []DATE, []TIME, []DATETIME, []UUID: Arrays of respective types

Record Validation

Records are validated in real-time:

• Name validation: Must be unique, no spaces, letters/numbers/underscores/hyphens only
• Type validation: Must select from available types
• Value validation: Must match the selected type format

Examples:

• STRING: "Hello, World!"
• INTEGER: 42
• BOOLEAN: true
• DATE: 2025-01-15
• []STRING: ["apple", "banana", "cherry"]

Managing Clusters

Rename a Cluster:

1. From the collection overview, click the cluster options menu
2. Select "Rename Cluster"
3. Enter the new name
4. Click "Rename Cluster"

Delete a Cluster:

1. From the collection overview, click the cluster options menu
2. Select "Delete Cluster"
3. Type the exact cluster name to confirm
4. Click "Delete Cluster"

Query Interfaces

OstrichDB provides multiple ways to interact with your data:

1. Natural Language Processing (NLP)

Transform database operations into conversational interactions:

Accessing NLP:

1. Navigate to any project
2. Click "Natural Language Query Processor" in the sidebar
3. Or use the direct NLP link in project navigation

Using NLP:

1. Type your request in plain English
2. Examples:
   • "Create a new collection called 'user-data'"
   • "Delete all records in the 'temp' cluster"
   • "Show me all users created this month"
   • "Find records where status is active"
3. Review the AI's understanding of your request
4. Click "Confirm & Execute" to proceed

NLP Features:

• Available on Pro and Enterprise plans
• 50 requests per day on Pro plan
• Unlimited requests on Enterprise plan
• Supports complex data operations
• Batch operations for multiple changes

2. Manual Query Editor

For advanced users who prefer direct database commands:

Accessing Manual Query:

1. Navigate to any project/collection
2. Click "Manual Query Editor" in the sidebar

Query Commands:

• NEW <location> [OF_TYPE <type>] [WITH <value>] - Create collections/clusters/records
• FETCH <location> - Retrieve data
• ERASE <location> - Delete data structures
• RENAME <old> TO <new> - Rename objects
• COUNT <COLLECTIONS|CLUSTERS|RECORDS> - Count objects
• SIZE_OF <location> - Get object size
• TYPE_OF <location> - Get record type
• HELP [command] - Show help information
• VERSION - Show version info
• CLEAR - Clear terminal

Query Examples:

NEW ecommerce
NEW ecommerce.products
NEW ecommerce.products.laptop OF_TYPE STRING WITH "MacBook Pro"
FETCH ecommerce.products.laptop
COUNT COLLECTIONS

3. Visual Interface

The primary interface for most users:

• Cluster Editor: Visual record management
• Collection Overview: Dashboard with statistics
• Project Dashboard: High-level project management

Collaboration Features

Current Status: Collaboration features are in development

Planned Features (Pro/Enterprise):

• Multi-user access
• Permission management
• Shared projects
• Real-time collaboration
• Team workspaces

Data Import/Export

Current Capabilities:

• Manual data entry through Cluster Editor
• Programmatic access via API
• Raw format viewing for data structure

Planned Features:

• CSV import/export
• JSON import/export
• Excel file support
• Bulk data operations

API Access

OstrichDB provides a RESTful API for programmatic access:

Base URL

http://localhost:8042/api/v1/

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer <your-token>

Common Endpoints

Projects:

• GET /projects - List all projects
• POST /projects/{name} - Create project
• PUT /projects/{name}?rename={newName} - Rename project
• DELETE /projects/{name} - Delete project

Collections:

• GET /projects/{project}/collections - List collections
• POST /projects/{project}/collections/{name} - Create collection
• PUT /projects/{project}/collections/{name}?rename={newName} - Rename collection
• DELETE /projects/{project}/collections/{name} - Delete collection

Clusters:

• GET /projects/{project}/collections/{collection}/clusters - List clusters
• POST /projects/{project}/collections/{collection}/clusters/{name} - Create cluster
• PUT /projects/{project}/collections/{collection}/clusters/{name}?rename={newName} - Rename cluster
• DELETE /projects/{project}/collections/{collection}/clusters/{name} - Delete cluster

Records:

• GET /projects/{project}/collections/{collection}/clusters/{cluster}/records - List records
• POST /projects/{project}/collections/{collection}/clusters/{cluster}/records/{name}?type={type}&value={value} - Create record
• PUT /projects/{project}/collections/{collection}/clusters/{cluster}/records/{name} - Update record
• DELETE /projects/{project}/collections/{collection}/clusters/{cluster}/records/{name} - Delete record

Pricing Plans

Free Tier

• 1 user
• 1 project
• 1 collection maximum
• 500MB storage
• 1 backup per day
• Community support

Pro Tier ($25/month)

• 3 users
• 3 projects
• 3 collections maximum
• 3GB storage
• 5 backups per day
• Private support channels
• Collaboration features
• NLP queries (50/day)

Enterprise Tier (Custom pricing)

• 50 users
• 30 projects
• 100 collections maximum
• 64TB storage
• 10 backups per day
• Collaboration features
• Unlimited NLP queries
• On-call support
• Priority support

Account Management

Theme Settings

• Toggle between light and dark themes
• Auto-detection of system preference
• Settings persist across sessions

Profile Management

• Update profile information
• View account tier and usage
• Access billing information (Pro/Enterprise)

Security

• Two-factor authentication (recommended)
• Session management
• Activity monitoring

Backup and Recovery

Automatic Backups:

• Free: 1 backup per day
• Pro: 5 backups per day
• Enterprise: 10 backups per day

Manual Backups:

• Export cluster data via Raw view
• API-based data exports
• Scheduled backup configuration (Pro/Enterprise)

Performance and Limits

Free Tier Limits

• 500MB total storage
• 1 project maximum
• 1 collection per project
• Community support only

Pro Tier Limits

• 3GB total storage
• 3 projects maximum
• 3 collections per project
• 50 NLP requests per day

Enterprise Tier

• 64TB total storage
• 30 projects maximum
• 100 collections per project
• Unlimited NLP requests

Best Practices

Project Organization

• Use descriptive project names
• Separate development, staging, and production environments
• Group related data logically

Collection Design

• Keep collections focused on related data
• Don't make collections too large (consider splitting at 50+ different record types)
• Use consistent naming conventions

Record Management

• Choose appropriate data types for each record
• Use validation to ensure data quality
• Document your data structure

Security

• Use strong passwords for projects
• Enable two-factor authentication
• Regularly review access permissions
• Keep sensitive data in separate collections

Troubleshooting

Connection Issues

• Check the backend status indicator (green dot = connected)
• Refresh the page if connection shows as disconnected
• Clear browser cache if problems persist

Data Validation Errors

• Ensure record names follow naming rules (no spaces, special characters)
• Check that values match the selected data type
• Verify array values are properly formatted JSON

Performance Issues

• Large datasets may take longer to load
• Consider breaking large clusters into smaller ones
• Use appropriate data types for better performance

Common Error Messages

• "Record name is required" - Enter a name for the record
• "Invalid data type" - Select a valid data type from the dropdown
• "Value doesn't match type" - Ensure the value format matches the selected type
• "Cluster name already exists" - Choose a unique cluster name

Support and Resources

Getting Help

• Community Support: Discord server for all users
• Documentation: Comprehensive guides and references
• Private Support: Pro/Enterprise users get private Discord channels
• On-call Support: Enterprise users only

Contact Information

• Email: admin@archetype-dynamics.com
• Discord: https://discord.gg/FPd7SmMMmk
• GitHub: https://github.com/Archetype-Dynamics/OstrichDB.com

Additional Resources

• API documentation
• Video tutorials
• Community examples
• Best practices guides

---

This documentation covers the current features of OstrichDB as of 2025. Features and pricing are subject to change. Check the website for the most up-to-date information.

OstrichDB CLI documentation

OstrichDB CLI

Built from scratch, the OstrichDB engine powers the OstrichDB CLI—a lightweight yet powerful database management tool for your terminal. Written in Odin, it features an intuitive query structure, hierarchical data organization, and built-in security systems, making it ideal for anyone seeking an easy-to-use, flexible, high-performance database solution.

---

Key Features

• Three Ways To Interact:
  • Manually enter queries via the Command-line Interface
  • Enable the built-in HTTP server and interact via a client in your favorite language
  • (Experimental) Use natural language queries to quickly interact with your data!(Requries a bit of setup)
• User Authentication
• User Role-Based Access
• Database permissions
• Database encryption & decryption
• Custom Hierarchical Data Structure
• .CSV & .JSON file importing
• Dot Notation Syntax when using the serverless CLI
• Query Chaining
• Built-in benchmarking, configurations, and user query history
• macOS & Linux Support

Installation

Prerequisites:

• A Unix-based system (macOS, Linux).
• The Go programming language installed, and properly set in the systems PATH. Ideal Go version: go1.23.1
• The Odin programming language installed, built, and properly set in the system's PATH. Ideal Odin Version: dev-2024-11:764c32fd3 Note: You can achieve the previous step by following the Odin Installation Guide

Building and Running The OstrichDB CLI Locally:

Steps:

1. Clone the Repository:

   git clone https://github.com/Solitude-Software-Solutions/OstrichDB.git

2. Navigate to the root directory of the OstrichDB CLI project:

   cd path/to/OstrichDB

3. Make the Build, Run & Restart Scripts Executable:

   chmod +x scripts/local_build_run.sh && chmod +x scripts/local_build.sh && chmod +x scripts/restart.sh

4. Run The Build Script:

   ./scripts/local_build_run.sh

Building and Running The OstrichDB CLI in a Docker Container:

Steps:

1. Ensure that you have Docker installed: https://docs.docker.com/engine/install/

2. Navigate to the root directory of the OstrichDB CLI project:

   cd /path/to/OstrichDB

3. Build the Docker container:

   docker compose build

   Alternatively, build and run the container in detached mode

   docker compose up -d

4. Run the OstrichDB CLI

   docker exec -it ostrichdb /app/main.bin

*Note: You can find data for OstrichDB in .ostrichdb/data in the project's directory, which is mapped to /data inside the container. You can also change the port mapping to the host machine by updating the docker-compose.yml file in case port 8080 is already in use, i.e.

ports:
  - "8089:8080"

---

Data Structure Overview

OstrichDB organizes data into three levels:

• Records: The smallest unit of data. e.g user_name, age, email. Format: [name] :[type]: [value]
• Clusters: Groups of related records. Given a name and an id upon creation.
• Collections: Database files containing clusters, Have the '.ostrichdb' extension.

---

Query Structure (CLPs)

From the OstrichDB CLI, queries are typically broken into three types of tokens, called CLPs, to improve readability and ensure clear instructions.

Note: Not all queries require all 3 tokens.

1. (C)ommand Token: Specifies the operation to perform (e.g., NEW, ERASE, RENAME).
2. (L)ocation Token: The path using dot notation that the query will be performed on (e.g., foo.bar.baz).
3. (P)arameter Token(s): Additional parameters that change the behavior of the query (e.g., TO, OF_TYPE).

---

Query Walkthrough

NEW foo.bar.baz OF_TYPE []STRING

Explanation:

• NEW: Create a new data structure (Command token).
• foo: The first data structure always points to a collection. (Location token).
• bar: The second data structure always to a cluster within the collection. (Location token).
• baz: The third data structure is always a record within the cluster. (Location token).
• OF_TYPE: Specifies the data type of the record (Parameter token). Note: Only records are given data types.
• []STRING: Token mapped to the Parameter token that precedes it. The record will be an array of strings.

---

Supported Command Tokens

Single-Token Operations

These tokens perform a task without any additional arguments.

• AGENT: Starts the OstrichDB natural language processor. Requires the server to be running in another terminal.
• VERSION: Displays the current version of OstrichDB.
• LOGOUT: Logs out the current user.
• EXIT: Ends the session and closes the DBMS.
• RESTART: Restarts the program.
• REBUILD: Rebuilds the DBMS and restarts the program.
• SERVE/SERVER: Turns on the OstrichDB server allowing http requests to be made.
• HELP: Displays general help information or detailed help when chained with specific tokens.
• TREE: Displays the entire data structure in a tree format.
• CLEAR: Clears the console screen.
• HISTORY: Shows the current users command history.
• DESTROY: Completeley destorys the entire DBMS. Including all databases, users, configs, and logs.
• BENCHMARK: Runs a benchmark test on the DBMS to test performance. Can be run with or without parameters.

---

Multi-Token Tokens

These tokens are used to construct queries and require one or more additional tokens.

• NEW: Create a new collection, cluster, record, or user.
• ERASE: Delete a collection, cluster, or record.
• RENAME: Rename an existing object.
• FETCH: Retrieve data from a collection, cluster, or record.
• SET: Assign a value to a record or configuration.
• BACKUP: Create a backup of a specific collection.
• PURGE: Removes all data from an object while maintaining the object structure.
• COUNT: Returns the number of objects within a scope. Paired with the plural form of the object type (e.g., RECORDS, CLUSTERS).
• SIZE_OF: Returns the size in bytes of an object.
• TYPE_OF: Returns the type of a record.
• CHANGE_TYPE: Allows you to change the type of a record.
• HELP: Displays help information for a specific token.
• ISOLATE: Quarantines a collection file. Preventing any further changes to the file
• WHERE: Searches for the location of a single or several record(s) or cluster(s). DOES NOT WORK WITH COLLECTIONS.
• VALIDATE: Validates a collection file for any errors or corruption.
• BENCHMARK: Runs a benchmark test on the DBMS to test performance. Can be run with or without parameters.
• LOCK: Used to change the access mode of a collection. Using LOCK {collection_name} -r sets a collection to Read-Only. Removing the -r will set a collection to Inaccessible.
• UNLOCK: Changes the access mode of a collection to the default Read-Write.
• ENC : Encrypts a collection.
• DEC : Decrypts a currently encrypted collection. Use at own discretion.
• IMPORT: Allows the user to import a .csv or .json files into OstrichDB.

---

Parameters

Modifiers adjust the behavior of queries. The current supported modifiers are:

• OF_TYPE: Specifies the type of a new record (e.g., INT, STR, []BOOL)
• WITH: Used to assign a value to a record in the same command you are creating it(e.g NEW {collection_name}.{cluster_name}.{record_name} OF_TYPE {record_type} WITH {record_value})
• TO: Used to assign a new value or name to a data structure or config(e.g RENAME {old_collection_name} to {new_collection_name})

Query Chaining

OstrichDB supports query chaining, allowing you to execute multiple queries in sequence with a single input. To chain queries together add the && operator at the end of each valid query, and they will be executed in the order they appear.

Example:

RENAME foo.bar.baz TO goob && FETCH fetch foo.bar.goob

Supported Record Data Type Tokens

When setting a record value, you must specify the records data type by using the OF_TYPE modifier. Some types have a shorthand notation for convenience.

Primary data types include:

• INTEGER: Integer values. Short-hand: INT.
• STRING: Any text value longer than 1 character. Short-hand: STR.
• FLOAT: Floating-point numbers. Short-hand: FLT.
• BOOLEAN: true or false values. Short-hand: BOOL.
• CHAR: Single character values. No short-hand.

Complex data types include:

NOTE: When setting array values, separate each element with a comma WITHOUT spaces.

• []STRING: String arrays. Short-hand: []STR.
• []INTEGER: Integer arrays. Short-hand: []INT.
• []FLOAT: Float arrays. Short-hand: []FLT.
• []BOOLEAN: Boolean arrays. Short-hand: []BOOL.
• []CHAR: Character arrays. No short-hand.

Other supported data types include:

• DATE: Must be in YYYY-MM-DD format. No short-hand.

• TIME: Must be in HH:MM:SS format. No short-hand.

• DATETIME: Must be in YYYY-MM-DDTHH:MM:SS format. No short-hand.

• []DATE: Date arrays. Each value must follow the above format. No short-hand.

• []TIME: Time arrays. Each value must follow the above format. No short-hand.

• []DATETIME: Date and time arrays. Each value must follow the above format. No short-hand.

• NULL: Null value. No short-hand.

  Note: UUIDs can only have 0-9 and a-f characters and must be in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

• UUID: Universally unique identifier. Must follow the above format. No short-hand.

• []UUID: UUID arrays. Each value must follow the above format. No short-hand.

---

Usage Examples

# Create a new record:
# Note: If collection staff and cluster engineering do not exist
# Don't worry, that will be created all at once!
NEW staff.engineering.team_one OF_TYPE []STRING WITH "John","Ana","Wayne"
# Fetch the record value:
FETCH staff.engineers.team_one
# Rename a cluster:
RENAME staff.engineering TO HR
# Get the size of a cluster:
SIZE_OF staff.HR
# Erase a record:
ERASE staff.HR.team_one
# Get a count of all collections in the database:
COUNT COLLECTIONS
#Get help information for a specific token:
HELP {TOKEN_NAME}
# Get general help information
HELP
# Create a new user
NEW USER

---

Configs

OstrichDB has a configuration file that allows the user to customize certain aspects of the DBMS to their liking.

• HELP_IS_VERBOSE: Decide whether help information is simple or verbose. Default is false
• SUPPRESS_ERRORS: Show or hide error messages. Default is false
• LIMIT_HISTORY: Ensure whether a users query history does or does not exceed the built in limit(100) Default is true
• AUTO_SERVE: Determines if the built-in OstrichDB server automatically starts the moment the user logs in. Default is true
• LIMIT_SESSION_TIME: Determines if the CLI session timer is enabled or disabled. If enabled a user can only be logged in for 24hrs. Default is true

Note: ALL configs must be set using the following query: Config values can only be true or false

SET CONFIG {CONFIG_NAME} TO {VALUE}

---

Future Plans

• A new and improved engine!
• More configuration options
• Several new Command tokens:
  • EXPORT: Export data to various formats
  • RESTORE: Restores a collection backup in the place of the original collection
  • MERGE: Combine multiple collections or clusters into one
• OstrichDB web application
• Windows support
• External API support for even more programming languages!
• Integration with the planned Feather query language!

---

Contributing

Please refer to the CONTRIBUTING.md for detailed guidelines on how to contribute.

---

License

OstrichDB is released under the Apache License 2.0. For the full license text, see Apache License 2.0.