Quick Start Guide

Quick Start Guide

This guide will get you up and running with OstrichDB quickly, covering the basic operations you need to start using the database.

Prerequisites

Make sure you have completed the Installation guide and have OstrichDB running on your system.

Understanding the Hierarchy

OstrichDB organizes data in a hierarchical structure:

Projects
  └── Collections
      └── Clusters
          └── Records

Each level serves a specific purpose:

• Projects: Top-level containers for organizing related data
• Collections: Groups of related clusters, can be encrypted
• Clusters: Groups of related records
• Records: Individual data items with types and values

Basic Operations

1. Create a Project

Projects are the top-level containers in OstrichDB:

curl -X POST http://localhost:8042/api/v1/projects/my-first-project

2. List Projects

View all projects:

curl http://localhost:8042/api/v1/projects

3. Create a Collection

Collections group related data within a project:

curl -X POST http://localhost:8042/api/v1/projects/my-first-project/collections/users

4. Create a Cluster

Clusters organize records within collections:

curl -X POST http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users

5. Create Records

Records store the actual data with specified types and values:

# Create a string record
curl -X POST "http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records/username?type=STRING&value=john_doe"

# Create an integer record
curl -X POST "http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records/age?type=INTEGER&value=25"

# Create a boolean record
curl -X POST "http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records/is_active?type=BOOLEAN&value=true"

6. Retrieve Data

Get records from a cluster:

curl http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records

Get a specific record:

curl http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records/username

Working with Different Data Types

OstrichDB supports various data types:

Basic Types

# String
curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/name?type=STRING&value=Alice"

# Integer
curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/count?type=INTEGER&value=42"

# Float
curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/price?type=FLOAT&value=19.99"

# Boolean
curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/enabled?type=BOOLEAN&value=false"

Date and Time Types

# Date
curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/created_date?type=DATE&value=2024-01-15"

# DateTime
curl -X POST "http://localhost:8042/api/v1/projects/demo/collections/test/clusters/data/records/timestamp?type=DATETIME&value=2024-01-15T10:30:00Z"

Searching and Filtering

OstrichDB provides powerful search and filtering capabilities:

Filter by Type

curl "http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records?type=STRING"

Search by Name Pattern

curl "http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records?search=user"

Filter by Value

curl "http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records?value=true"

Sorting and Pagination

# Sort by name, descending order
curl "http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records?sortBy=name&sortOrder=desc"

# Pagination
curl "http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records?limit=10&offset=0"

Updating and Deleting Data

Update a Record

curl -X PUT "http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records/age?value=26"

Delete a Record

curl -X DELETE http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users/records/age

Delete a Cluster

curl -X DELETE http://localhost:8042/api/v1/projects/my-first-project/collections/users/clusters/active-users

Example Workflow

Here’s a complete example of creating a simple user management system:

# 1. Create project
curl -X POST http://localhost:8042/api/v1/projects/user-management

# 2. Create collections
curl -X POST http://localhost:8042/api/v1/projects/user-management/collections/profiles
curl -X POST http://localhost:8042/api/v1/projects/user-management/collections/settings

# 3. Create clusters
curl -X POST http://localhost:8042/api/v1/projects/user-management/collections/profiles/clusters/admins
curl -X POST http://localhost:8042/api/v1/projects/user-management/collections/profiles/clusters/regular-users

# 4. Add admin user data
curl -X POST "http://localhost:8042/api/v1/projects/user-management/collections/profiles/clusters/admins/records/name?type=STRING&value=Administrator"
curl -X POST "http://localhost:8042/api/v1/projects/user-management/collections/profiles/clusters/admins/records/email?type=STRING&value=admin@example.com"
curl -X POST "http://localhost:8042/api/v1/projects/user-management/collections/profiles/clusters/admins/records/role?type=STRING&value=admin"
curl -X POST "http://localhost:8042/api/v1/projects/user-management/collections/profiles/clusters/admins/records/created?type=DATETIME&value=2024-01-15T09:00:00Z"

# 5. Query admin data
curl http://localhost:8042/api/v1/projects/user-management/collections/profiles/clusters/admins/records

Next Steps

Now that you understand the basics:

1. Explore the Architecture to understand how OstrichDB works internally
2. Read the API Reference for complete endpoint documentation
3. Learn about Security features for production use
4. Review Configuration options for customizing your setup