Collections & Schemas

Collections are containers for your data, similar to tables in traditional databases. Each collection can have an optional schema that enforces data structure, types, and validation rules.

Collection vs Schema

• Collection - The data container itself
• Schema - The validation rules and structure definition for that collection

Create Collection

Create a new collection with an optional schema.

POST https://{EKODB_API_URL}/api/collections/{collection}
Content-Type: application/json
Authorization: Bearer {ADMIN_TOKEN}

{
  "fields": {
    "name": {
      "type": "string",
      "required": true,
      "max_length": 100
    },
    "email": {
      "type": "string",
      "required": true,
      "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    },
    "age": {
      "type": "number",
      "min": 0,
      "max": 150
    },
    "status": {
      "type": "string",
      "enum": ["active", "inactive", "pending"]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "type": "object"
    }
  }
}

# Response
{
  "status": "success",
  "message": "Collection initialized successfully"
}

Working Examples

Prefer a client library? See examples in Rust, Python, TypeScript, Go, or Kotlin

Want to use the REST API directly? See examples in JavaScript, Python, Go, or Rust

Admin Permission Required

Creating collections requires admin permissions.

First, generate an access token using your API key:

curl -X POST https://{EKODB_API_URL}/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Get Collection Info

Retrieve information about a collection, including statistics and metadata.

GET https://{EKODB_API_URL}/api/collections/{collection}
Authorization: Bearer {YOUR_API_TOKEN}

# Response
{
  "name": "users",
  "record_count": 1234,
  "size_bytes": 5242880,
  "created_at": "2024-01-15T10:30:00Z",
  "last_modified": "2024-01-15T15:45:00Z",
  "has_schema": true,
  "indexes": {
    "query": ["email", "status"],
    "search": ["name", "description"]
  }
}

List All Collections

Get a list of all collections in the database.

GET https://{EKODB_API_URL}/api/collections
Authorization: Bearer {ADMIN_TOKEN}

# Response
{
  "collections": [
    {
      "name": "users",
      "record_count": 1234,
      "size_bytes": 5242880,
      "has_schema": true
    },
    {
      "name": "posts",
      "record_count": 5678,
      "size_bytes": 10485760,
      "has_schema": false
    }
  ],
  "total": 2
}

Delete Collection

Delete an entire collection and all its records permanently.

Warning

This operation is irreversible and deletes all data in the collection. Use with extreme caution.

DELETE https://{EKODB_API_URL}/api/collections/{collection}
Authorization: Bearer {ADMIN_TOKEN}

# Response
{
  "status": "success",
  "message": "Collection deleted successfully"
}

Restore Record from Trash

Restore a previously deleted record from trash. Records remain in trash for 30 days before permanent deletion.

POST https://{EKODB_API_URL}/api/trash/{collection}/{record_id}
Authorization: Bearer {ADMIN_TOKEN}

# Response
{
  "status": "restored",
  "id": "record_id_123",
  "collection": "users"
}

Restore Collection from Trash

Restore all deleted records in a collection from trash.

POST https://{EKODB_API_URL}/api/trash/{collection}
Authorization: Bearer {ADMIN_TOKEN}

# Response
{
  "status": "restored",
  "collection": "users",
  "records_restored": 42
}

Trash Retention

Deleted records are kept in trash for 30 days. After this period, they are permanently deleted and cannot be restored.

Get Schema

Retrieve the current schema for a collection.

GET https://{EKODB_API_URL}/api/schemas/{collection}
Authorization: Bearer {YOUR_API_TOKEN}

# Response
{
  "fields": {
    "name": {
      "type": "string",
      "required": true,
      "max_length": 100
    },
    "email": {
      "type": "string",
      "required": true,
      "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    }
  },
  "version": 1,
  "created_at": "2024-01-15T10:30:00Z",
  "last_modified": "2024-01-15T14:20:00Z",
  "bypass_ripple": false,
  "primary_key_alias": "id"
}

Response Format

Returns the schema object directly, not wrapped in a parent object.

Update Schema Constraints

Update validation constraints for an existing schema.

PUT https://{EKODB_API_URL}/api/schemas/{collection}
Content-Type: application/json
Authorization: Bearer {ADMIN_TOKEN}

{
  "constraints": {
    "name": {
      "required": true,
      "unique": false
    },
    "email": {
      "required": true,
      "unique": true
    }
  }
}

# Response
{
  "status": "success",
  "message": "Schema constraints updated successfully"
}

Schema Updates

Schema updates only affect new records. Existing records are not automatically migrated or validated against the new schema.

Set Primary Key Alias

Configure a custom field to use as the primary key instead of the default id.

PUT https://{EKODB_API_URL}/api/schemas/{collection}/primary-key-alias
Content-Type: application/json
Authorization: Bearer {ADMIN_TOKEN}

{
  "alias": "user_id"
}

# Response
{
  "status": "updated",
  "collection": "users",
  "alias": "user_id"
}

Example - Using Custom Primary Key:

# Insert with custom primary key
curl -X POST https://{EKODB_API_URL}/api/insert/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{
    "user_id": "custom_user_001",
    "name": "John Doe",
    "email": "john@example.com"
  }'

# Retrieve using custom primary key
curl -X GET https://{EKODB_API_URL}/api/find/users/custom_user_001 \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"

Schema Field Types

Supported Data Types

Type	Description	Validation Options
string	Text values	max_length, min_length, pattern
number	Integers and floats	min, max
boolean	True/false values	None
array	Lists of values	items, min_items, max_items
object	Nested JSON objects	properties
datetime	ISO 8601 datetime strings	format
email	Email address (auto-validated)	None
url	URL string (auto-validated)	None

Field Constraints

String Constraints:

{
  "username": {
    "type": "string",
    "required": true,
    "min_length": 3,
    "max_length": 20,
    "pattern": "^[a-zA-Z0-9_]+$"
  }
}

Number Constraints:

{
  "age": {
    "type": "number",
    "min": 0,
    "max": 150
  },
  "price": {
    "type": "number",
    "min": 0.01,
    "max": 999999.99
  }
}

Array Constraints:

{
  "tags": {
    "type": "array",
    "items": {
      "type": "string",
      "max_length": 50
    },
    "min_items": 1,
    "max_items": 10
  }
}

Enum Validation:

{
  "status": {
    "type": "string",
    "enum": ["draft", "published", "archived"],
    "default": "draft"
  }
}

Nested Objects:

{
  "address": {
    "type": "object",
    "properties": {
      "street": {
        "type": "string",
        "required": true
      },
      "city": {
        "type": "string",
        "required": true
      },
      "postal_code": {
        "type": "string",
        "pattern": "^[0-9]{5}$"
      }
    }
  }
}

Complete Example

Here's a complete workflow for creating and managing a collection:

#!/bin/bash

# 1. Create collection with schema
curl -X POST https://{EKODB_API_URL}/api/collections/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ADMIN_TOKEN}" \
  -d '{
    "fields": {
      "sku": {
        "type": "string",
        "required": true,
        "pattern": "^[A-Z0-9-]+$"
      },
      "name": {
        "type": "string",
        "required": true,
        "max_length": 200
      },
      "price": {
        "type": "number",
        "min": 0.01,
        "required": true
      },
      "category": {
        "type": "string",
        "enum": ["electronics", "clothing", "books", "food"]
      },
      "in_stock": {
        "type": "boolean",
        "default": true
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "max_items": 5
      }
    }
  }'

# 2. Set custom primary key
curl -X PUT https://{EKODB_API_URL}/api/schemas/products/primary-key-alias \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ADMIN_TOKEN}" \
  -d '{
    "alias": "sku"
  }'

# 3. Insert product (validates against schema)
curl -X POST https://{EKODB_API_URL}/api/insert/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{
    "sku": "ELEC-001",
    "name": "Wireless Mouse",
    "price": 29.99,
    "category": "electronics",
    "in_stock": true,
    "tags": ["wireless", "bluetooth", "ergonomic"]
  }'

# 4. Get collection info
curl -X GET https://{EKODB_API_URL}/api/collections/products \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"

# 5. Get current schema
curl -X GET https://{EKODB_API_URL}/api/schemas/products \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"

# 6. Update schema constraints
curl -X PUT https://{EKODB_API_URL}/api/schemas/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ADMIN_TOKEN}" \
  -d '{
    "fields": {
      "sku": {
        "type": "string",
        "required": true,
        "pattern": "^[A-Z0-9-]+$"
      },
      "name": {
        "type": "string",
        "required": true,
        "max_length": 300
      },
      "price": {
        "type": "number",
        "min": 0.01,
        "max": 100000
      }
    }
  }'

Best Practices

Schema Design

Start Simple, Evolve Gradually:

# Initial schema - minimal constraints
{
  "fields": {
    "name": {"type": "string", "required": true},
    "email": {"type": "string", "required": true}
  }
}

# Later - add more constraints as requirements clarify
{
  "fields": {
    "name": {
      "type": "string",
      "required": true,
      "min_length": 2,
      "max_length": 100
    },
    "email": {
      "type": "email",
      "required": true
    }
  }
}

Collection Naming

Use Clear, Plural Names:

# Good
/api/collections/users
/api/collections/products
/api/collections/order_items

# Avoid
/api/collections/user
/api/collections/Product
/api/collections/order-item

Schema Validation

Balance Strictness with Flexibility:

{
  "fields": {
    "core_field": {
      "type": "string",
      "required": true,
      "max_length": 100
    },
    "optional_field": {
      "type": "string",
      "required": false
    }
  }
}

Primary Key Strategy

Choose Based on Your Use Case:

Use Case	Primary Key Strategy
Auto-generated IDs	Use default id field
External system sync	Set alias to external ID
Natural keys (SKU, email)	Set alias to natural key
UUIDs	Set alias to UUID field

Validation Errors

When a record violates the schema, you'll receive detailed error messages:

# Invalid insert attempt
POST /api/insert/users
{
  "name": "A",  // Too short
  "email": "invalid-email",  // Invalid format
  "age": 200  // Exceeds max
}

# Error response
{
  "error": "Schema validation failed",
  "details": [
    {
      "field": "name",
      "constraint": "min_length",
      "expected": 2,
      "actual": 1,
      "message": "Field 'name' must be at least 2 characters"
    },
    {
      "field": "email",
      "constraint": "pattern",
      "message": "Field 'email' does not match required pattern"
    },
    {
      "field": "age",
      "constraint": "max",
      "expected": 150,
      "actual": 200,
      "message": "Field 'age' exceeds maximum value of 150"
    }
  ]
}

Related Documentation

• Basic Operations - Insert, query, update, and delete records
• Indexes - Create indexes for query performance
• Authentication - API key and permission management
• Data Types - Detailed data type reference

Example Code

Direct HTTP/REST API Examples

Raw HTTP examples demonstrating the REST API directly:

• JavaScript - collection_management.js
• Python - collection_management.py
• Go - collection_management.go
• Rust - collection_management.rs

Client Library Examples

Production-ready examples using official client libraries:

• Rust - client_collection_management.rs
• Python - client_collection_management.py
• TypeScript - client_collection_management.ts
• Go - client_collection_management.go
• Kotlin - ClientCollectionManagement.kt
• JavaScript - client_collection_management.js