Collections Management

Collections in OstrichDB are equivalent to databases in traditional systems. They provide logical grouping for related data and serve as encryption boundaries. This guide covers everything you need to know about working with collections.

Understanding Collections

What is a Collection?

A collection in OstrichDB is:

Database equivalent: Similar to a database in traditional SQL systems
Encryption boundary: Each collection can be independently encrypted
Data container: Holds multiple clusters of related information
Organization unit: Groups related data logically together
Security perimeter: Access control and permissions applied at collection level

Collection Hierarchy

Project (Application/Service)
├── Collection (Database/Domain)
    ├── Cluster (Table/Category equivalent)
        ├── Record (Row/Document equivalent)
            ├── Name: unique identifier
            ├── Type: explicit data type
            └── Value: the actual data

Creating Collections

Step-by-Step Collection Creation

Navigate to a project from your dashboard
Click “Create New Collection” button
Enter a collection name following naming conventions
Configure encryption settings (optional)
Click “Create Collection” to finalize

Collection Naming Rules

Collections must follow strict naming conventions:

Maximum length: 64 characters
Allowed characters: Letters (a-z, A-Z), numbers (0-9), underscores (_), hyphens (-)
No spaces: Use underscores or hyphens for separation
Unique within project: Must be unique within the parent project
Case sensitive: “UserData” and “userdata” are different collections

Valid Examples:

user_profiles
product-inventory
session_data
analytics_v2
customer_orders_2024

Invalid Examples:

user profiles (contains space)
data@2024 (contains special character @)
super-long-collection-name-that-definitely-exceeds-the-maximum-allowed-limit (too long)

Collection Features

Automatic Encryption

Default Security:

AES-256 encryption applied to all collections automatically
No additional setup required for encryption
No enterprise fees for encryption features
User-specific master keys derived from project passwords
Transparent operations - automatic encrypt/decrypt

Encryption Benefits:

Data at rest: All stored data is encrypted
Data in transit: API communications are encrypted
Key isolation: Each user has separate encryption keys
Enterprise-grade: Military-grade AES-256 encryption
Zero-trust: Encryption enabled by default, not optional

Collection Metadata

Each collection automatically tracks:

Creation Information:

Creation date: When the collection was first created
Created by: User who created the collection
Project context: Parent project information

Usage Statistics:

Total size: Storage space used by the collection
Number of clusters: Count of clusters within the collection
Record count: Total number of individual records
Last modified: Most recent update timestamp
Last accessed: When the collection was last queried

Performance Metrics:

Query frequency: How often the collection is accessed
Average response time: Performance statistics
Storage growth: Trend data for capacity planning

Managing Collections

Collection Operations

Each collection card in the project view displays an actions menu (⋮) with these options:

Viewing Collection Details

Click on the collection card to view detailed information
See all clusters within the collection
View metadata and statistics
Access management options

Renaming a Collection

Click the three-dot menu (⋮) on the collection card
Select “Rename Collection”
Enter the new name (following naming rules)
Click “Rename Collection” to confirm

Important Notes:

Renaming affects all API endpoints and references
Clusters and records within remain unchanged
Update any external applications that reference this collection
The operation is atomic - either succeeds completely or fails

Deleting a Collection

Click the three-dot menu (⋮) on the collection card
Select “Delete Collection”
Type the exact collection name to confirm deletion
Click “Delete Collection” to permanently remove

⚠️ Critical Warning:

Deletion is permanent and irreversible
Removes all clusters and records within the collection
Cannot be undone - ensure you have backups
Consider exporting data before deletion
All API endpoints for this collection will become invalid

Collection Information Display

Collection Cards show:

Collection Name: Unique identifier
Cluster Count: Number of clusters contained
Total Records: Sum of all records across clusters
Storage Size: Space used by the collection
Last Modified: Most recent update timestamp
Encryption Status: Always shows encrypted (✅)

Detailed View includes:

Creation metadata: When and by whom
Access patterns: Usage statistics and trends
Performance data: Query response times
Relationship mapping: Connections to other collections
Backup status: Last backup timestamp and status

Collection Organization

Naming Conventions

Recommended Patterns:

By Domain:

users - User account information
products - Product catalog data
orders - Transaction and order data
analytics - Metrics and reporting data

By Function:

auth_data - Authentication and authorization
session_store - Session management
cache_layer - Temporary cached data
audit_logs - Security and compliance logs

By Environment:

dev_users - Development environment users
staging_products - Staging product data
prod_analytics - Production analytics

Versioning:

user_profiles_v1 - First version of user profiles
api_responses_v2 - Second iteration of API data
schema_2024 - Year-based versioning

Best Practices for Collection Design

Logical Grouping:

Group related data together (users, user_preferences, user_sessions)
Separate different domains (don’t mix users and products)
Consider access patterns (frequently accessed together)
Plan for scalability (avoid overly large collections)

Security Considerations:

Sensitive data in separate collections for better access control
Public data can share collections for efficiency
Compliance requirements may dictate separation
User data separate from system data

Performance Optimization:

Frequently accessed data in optimized collections
Archive old data to separate collections
Index planning based on query patterns
Size management to prevent performance degradation

Collection Limits by Plan

Free Tier

Maximum Collections: 1 collection per project
Storage per Collection: 500MB total across all collections
Clusters per Collection: Unlimited (within storage limit)
Backup Frequency: 1 backup per day

Pro Tier

Maximum Collections: 3 collections per project
Storage per Collection: 3GB total across all collections
Clusters per Collection: Unlimited (within storage limit)
Backup Frequency: 5 backups per day
Multi-user Access: 3 users can access collections

Enterprise Tier

Maximum Collections: 100 collections per project
Storage per Collection: 64TB total across all collections
Clusters per Collection: Unlimited
Backup Frequency: 10 backups per day
Multi-user Access: 50 users with role-based permissions

Working with Collection Data

Data Access Patterns

Direct Access:

Navigate through Project → Collection → Cluster hierarchy
Use Cluster Editor for visual data management
API endpoints for programmatic access

Query Interfaces:

Natural Language Processing for conversational queries (Pro/Enterprise)
Manual Query Editor for direct database commands
REST API for application integration

Bulk Operations:

Export entire collections as JSON or CSV
Import data from external sources
Batch modifications across multiple clusters
Migration tools for moving between collections

Collection-Level Operations

Backup and Recovery:

Automatic backups based on your plan
Manual backup triggers for important changes
Point-in-time recovery for accidental changes
Cross-collection restoration for complex recoveries

Analytics and Monitoring:

Usage patterns and access frequency
Performance metrics and response times
Storage trends and growth projections
Error rates and reliability statistics

Integration and API Access

REST API Endpoints

Collection Management:

GET /api/v1/projects/{project}/collections
POST /api/v1/projects/{project}/collections/{name}
GET /api/v1/projects/{project}/collections/{name}
PUT /api/v1/projects/{project}/collections/{name}?rename={newName}
DELETE /api/v1/projects/{project}/collections/{name}

Collection Metadata:

GET /api/v1/projects/{project}/collections/{name}/info
GET /api/v1/projects/{project}/collections/{name}/stats
GET /api/v1/projects/{project}/collections/{name}/clusters

Authentication and Security

API Access:

JWT tokens required for all collection operations
Project ownership verified for each request
Collection-level permissions enforced
Rate limiting applied based on plan tier

Encryption Handling:

Automatic encryption/decryption for all API operations
Key management handled transparently
No additional headers needed for encrypted collections
Performance optimization for encryption operations

Troubleshooting Collections

Common Issues

“Collection name already exists”

Solution: Choose a unique name within the project
Check: Review existing collection names first
Alternative: Use versioning or descriptive suffixes

“Cannot create collection - limit reached”

Solution: You’ve reached your plan’s collection limit
Options: Delete unused collections or upgrade your plan
Workaround: Reorganize data to use fewer collections

“Collection access denied”

Solution: Verify you have proper permissions for the project
Check: Ensure you’re logged into the correct account
Contact: Reach out to project owner for access

“Collection appears empty but shows data size”

Solution: Check if clusters are properly loaded
Refresh: Try refreshing the page or clearing cache
API: Use API endpoints to verify actual data presence

Performance Issues

Slow collection loading:

Large collections may take time to load metadata
Network issues can cause delays
Browser cache problems may cause issues
Solution: Try refreshing or using incognito mode

Collection operations timing out:

Large datasets require more processing time
Complex operations may exceed timeout limits
Solution: Break operations into smaller chunks or use API

Next Steps

Once you understand collections:

Explore Clusters: Learn about Cluster Management within collections
Data Management: Use the Cluster Editor for visual data work
API Integration: Connect applications using REST API
Advanced Queries: Try Natural Language Processing for complex operations
Security Planning: Review Authentication and access control

Collections are the foundation of your data organization in OstrichDB. Proper collection design and management are crucial for building scalable, maintainable database applications.