Structures & Records¶

Overview¶

Structures and Records are the foundation of data management in Centrali. Think of structures as database schemas or data models, and records as the actual data rows that follow those schemas.

What are Structures?¶

A structure defines the shape and validation rules for your data. It's similar to: - A database table schema - A JSON Schema - A TypeScript interface - A class definition

Key Concepts¶

Properties: Fields that define the data structure - Each property has a type (string, number, boolean, etc.) - Properties can have validation rules - Properties can be required or optional

Validation: Built-in validation for data integrity - Type checking - Required field validation - Format validation (email, URL, etc.) - Custom validation rules

Versioning: Track changes to structure definitions over time

Property Types¶

Centrali supports the following property types:

String¶

Text data with optional validation.

{
  "name": "email",
  "type": "string",
  "format": "email",
  "required": true
}

Formats: - email: Email address validation - url: URL validation - uuid: UUID format - date: ISO 8601 date string - datetime: ISO 8601 datetime string

Number¶

Numeric data (integers or decimals).

{
  "name": "price",
  "type": "number",
  "minimum": 0,
  "required": true
}

Validation options: - minimum: Minimum value - maximum: Maximum value - integer: Force integer values only

Boolean¶

True/false values.

{
  "name": "isActive",
  "type": "boolean",
  "default": true
}

Datetime¶

Date and time values stored as ISO 8601 strings.

{
  "name": "createdAt",
  "type": "datetime",
  "required": true
}

Array¶

List of values (can be any type).

{
  "name": "tags",
  "type": "array",
  "items": {
    "type": "string"
  }
}

Object¶

Nested object with its own properties.

{
  "name": "address",
  "type": "object",
  "properties": {
    "street": { "type": "string" },
    "city": { "type": "string" },
    "zipCode": { "type": "string" }
  }
}

Reference¶

Reference to another record in a different structure.

{
  "name": "author",
  "type": "reference",
  "referenceStructure": "users",
  "required": true
}

Creating a Structure¶

Via API¶

See the complete Structures API Guide for detailed examples.

curl -X POST https://api.centrali.io/workspace/my-workspace/api/v1/structures \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "products",
    "displayName": "Products",
    "properties": [
      {
        "name": "name",
        "type": "string",
        "required": true
      },
      {
        "name": "price",
        "type": "number",
        "minimum": 0,
        "required": true
      },
      {
        "name": "inStock",
        "type": "boolean",
        "default": true
      },
      {
        "name": "tags",
        "type": "array",
        "items": { "type": "string" }
      }
    ]
  }'

Via Console UI¶

1. Navigate to your workspace
2. Click "Structures" in the sidebar
3. Click "Create Structure"
4. Define properties:
5. Add property name and type
6. Configure validation rules
7. Mark required fields
8. Click "Save"

What are Records?¶

Records are instances of data that conform to a structure definition. If structures are the schema, records are the data.

Record Properties¶

Every record has: - id: Unique identifier (UUID) - createdAt: Creation timestamp - updatedAt: Last update timestamp - createdBy: User who created the record - version: Version number (for change tracking) - Custom fields: Your structure properties

Creating Records¶

Single Record¶

curl -X POST https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Laptop",
    "price": 999.99,
    "inStock": true,
    "tags": ["electronics", "computers"]
  }'

Response:

{
  "id": "rec_abc123",
  "name": "Laptop",
  "price": 999.99,
  "inStock": true,
  "tags": ["electronics", "computers"],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z",
  "version": 1
}

Bulk Create¶

curl -X POST https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "name": "Laptop",
        "price": 999.99,
        "inStock": true
      },
      {
        "name": "Mouse",
        "price": 29.99,
        "inStock": true
      }
    ]
  }'

Querying Records¶

Get All Records¶

curl -X GET https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records \
  -H "Authorization: Bearer YOUR_TOKEN"

Filtering¶

Use the query parameter for filtering. See the Query Guide for syntax.

# Records where price > 500
curl -X GET "https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records?query=price>500" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Records where inStock is true
curl -X GET "https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records?query=inStock==true" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Records with specific tag
curl -X GET "https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records?query=tags.includes('electronics')" \
  -H "Authorization: Bearer YOUR_TOKEN"

Pagination¶

curl -X GET "https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"

Sorting¶

# Sort by price descending
curl -X GET "https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records?sort=-price" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Sort by name ascending
curl -X GET "https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records?sort=name" \
  -H "Authorization: Bearer YOUR_TOKEN"

Updating Records¶

Update Single Record¶

curl -X PATCH https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records/rec_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 899.99,
    "inStock": false
  }'

Bulk Update¶

curl -X PATCH https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "inStock==true",
    "updates": {
      "discount": 10
    }
  }'

Deleting Records¶

Delete Single Record¶

curl -X DELETE https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records/rec_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Bulk Delete¶

curl -X POST https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records/bulk-delete \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "inStock==false AND price<50"
  }'

Relationships¶

One-to-Many¶

Use reference properties to create relationships:

Structure: authors

{
  "name": "authors",
  "properties": [
    { "name": "name", "type": "string", "required": true },
    { "name": "email", "type": "string", "format": "email" }
  ]
}

Structure: posts

{
  "name": "posts",
  "properties": [
    { "name": "title", "type": "string", "required": true },
    { "name": "content", "type": "string", "required": true },
    {
      "name": "author",
      "type": "reference",
      "referenceStructure": "authors",
      "required": true
    }
  ]
}

Creating a post with author reference:

curl -X POST https://api.centrali.io/workspace/my-workspace/api/v1/structures/posts/records \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Post",
    "content": "Hello world!",
    "author": "rec_author_123"
  }'

Populating References¶

Fetch records with referenced data expanded:

curl -X GET "https://api.centrali.io/workspace/my-workspace/api/v1/structures/posts/records?populate=author" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response includes full author object instead of just ID:

{
  "records": [
    {
      "id": "rec_post_123",
      "title": "My First Post",
      "content": "Hello world!",
      "author": {
        "id": "rec_author_123",
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  ]
}

Validation¶

Built-in Validation¶

Centrali automatically validates: - Required fields: Must be present in create/update requests - Type checking: Values must match property type - Format validation: Email, URL, UUID formats - Range validation: Min/max for numbers - Array items: All items must match specified type

Validation Errors¶

Invalid data returns a 400 error:

{
  "error": "Validation failed",
  "details": [
    {
      "property": "email",
      "message": "Invalid email format"
    },
    {
      "property": "price",
      "message": "Must be greater than or equal to 0"
    }
  ]
}

Versioning & History¶

Change Tracking¶

Every record update increments the version:

{
  "id": "rec_abc123",
  "name": "Updated Product",
  "version": 5,
  "updatedAt": "2025-01-15T14:30:00Z"
}

View Record History¶

curl -X GET https://api.centrali.io/workspace/my-workspace/api/v1/structures/products/records/rec_abc123/history \
  -H "Authorization: Bearer YOUR_TOKEN"

Response shows all changes:

{
  "history": [
    {
      "version": 1,
      "changes": { "name": "Laptop", "price": 999.99 },
      "changedBy": "user_123",
      "changedAt": "2025-01-15T10:00:00Z"
    },
    {
      "version": 2,
      "changes": { "price": 899.99 },
      "changedBy": "user_123",
      "changedAt": "2025-01-15T12:00:00Z"
    }
  ]
}

Best Practices¶

Structure Design¶

1. Use clear, descriptive names: users, products, orders
2. Mark fields required: Only when truly necessary
3. Set defaults: For boolean and number fields
4. Use references: For relationships between structures
5. Keep it simple: Start with basic properties, add complexity as needed

Record Management¶

1. Validate before creation: Check data on client side
2. Use bulk operations: For multiple records
3. Index frequently queried fields: Improves query performance
4. Use pagination: For large result sets
5. Implement soft deletes: Mark records inactive instead of deleting

Performance¶

1. Use specific queries: Avoid fetching all records
2. Limit populated references: Only populate what you need
3. Use appropriate page sizes: Balance between requests and data volume
4. Cache frequently accessed data: On your application side
5. Monitor usage: Track query performance and optimize

Common Use Cases¶

E-commerce¶

structures:
  - products (name, price, description, images)
  - categories (name, description)
  - orders (customer, items, total, status)
  - customers (name, email, address)

Content Management¶

structures:
  - articles (title, content, author, published_date)
  - authors (name, bio, avatar)
  - categories (name, slug)
  - comments (article, user, content)

Project Management¶

structures:
  - projects (name, description, status)
  - tasks (project, title, assignee, due_date)
  - users (name, email, role)
  - comments (task, user, content)

Related Documentation¶

• Structures API Guide - Complete API reference
• Query Guide - Query syntax and filtering
• Query Cheatsheet - Quick reference
• Compute Functions - Process and transform records

Next Steps¶

1. Create your first structure
2. Learn query syntax
3. Set up compute functions to process records
4. Configure webhooks for record events