Buzzy Datamodel Overview

A comprehensive guide to understanding Buzzy's datamodel, including datatables, fields, relationships, and how to work with data programmatically.

What is the Buzzy Datamodel?

Buzzy has the ability to model complex data relationships, including 1:M (one-to-many) and N:M (many-to-many) relationships. This powerful datamodel allows you to build sophisticated applications without worrying about creating foreign keys or managing complex database schemas—it's all handled automatically.

Core Concepts

Datatable: A database table made up of fields. Each row in the datatable has multiple fields. Think of it as a structured way to store and organize your application's data.

Fields: Include basic types like text, number, date, as well as advanced relationship fields that connect datatables together.

Metadata: Every row automatically includes system-generated metadata:

• _id: Unique identifier, automatically generated for each row

• embeddingRowID: Foreign key from a "child" row to a "parent" row in another datatable

• author: Name of the user who created the row (automatically populated)

• userID: User ID of the user who created the row (automatically populated)

• viewers: Field that stores a list of users who may view secured data

• teamViewers: Field that stores a list of user teams who may view secured data

Understanding Relationships

1:M (One-to-Many) Relationships

A single parent record can have multiple child records. For example, one Invoice can have many Invoice Lines.

Invoice (Parent Datatable)
├── _id: "inv_001"
├── Invoice Number: "INV-2024-001"
├── Customer: "Acme Corp"
└── Invoice Lines (Sub-table field)
    ├── Line 1
    │   ├── _id: "line_001"
    │   ├── embeddingRowID: "inv_001" ← Links to parent Invoice
    │   ├── Description: "Web Development"
    │   └── Amount: 1500
    └── Line 2
        ├── _id: "line_002"
        ├── embeddingRowID: "inv_001" ← Links to parent Invoice
        ├── Description: "Design Services"
        └── Amount: 800

How to set up: In the Invoice datatable, add a Sub-table field pointing to the Invoice Lines datatable. Buzzy automatically manages the embeddingRowID relationships.

N:M (Many-to-Many) Relationships

Multiple records from one datatable can relate to multiple records in another datatable. For example, Invoice Lines can reference Products, where each Product can appear in many invoice lines.

Invoice Lines ←→ Products (Many-to-Many via Linked Table Field)

Invoice Line 1
├── _id: "line_001"
├── embeddingRowID: "inv_001"
├── Quantity: 2
└── Product (Linked Table Field): "prod_123" ← References Product datatable

Invoice Line 2
├── _id: "line_002"
├── embeddingRowID: "inv_001"
├── Quantity: 1
└── Product (Linked Table Field): "prod_456" ← References Product datatable

Product "prod_123"
├── _id: "prod_123"
├── Name: "Premium Widget"
├── Price: 99.99
└── Category: "Electronics"

Product "prod_456"
├── _id: "prod_456"
├── Name: "Standard Widget"
├── Price: 49.99
└── Category: "Electronics"

How to set up: In the Invoice Lines datatable, add a Linked Table Field to the Products datatable.

Multi-Level Relationships

You can create complex hierarchies by combining 1:M and N:M relationships:

Organization (Level 1)
├── _id: "org_001"
├── Name: "Tech Solutions Inc"
└── Invoices (Sub-table)
    ├── Invoice 1
    │   ├── _id: "inv_001"
    │   ├── embeddingRowID: "org_001"
    │   └── Invoice Lines (Sub-table)
    │       ├── Line 1 → Product A (Linked Table Field)
    │       └── Line 2 → Product B (Linked Table Field)
    └── Invoice 2
        ├── _id: "inv_002"
        ├── embeddingRowID: "org_001"
        └── Invoice Lines (Sub-table)
            └── Line 1 → Product C (Linked Table Field)

Practical Examples

Example 1: Chat Application (Simple 1:M)

Based on our AI-Powered Chat App example:

Chat (Parent)
├── _id: "chat_001"
├── Title: "Project Discussion"
└── Messages (Sub-table)
    ├── Message 1
    │   ├── _id: "msg_001"
    │   ├── embeddingRowID: "chat_001"
    │   ├── Content: "Let's discuss the project timeline"
    │   └── Author: "[email protected]"
    └── Message 2
        ├── _id: "msg_002"
        ├── embeddingRowID: "chat_001"
        ├── Content: "Sounds good, when can we start?"
        └── Author: "[email protected]"

Example 2: Project Management (Complex Relationships)

Projects
├── _id: "proj_001"
├── Name: "Website Redesign"
└── Tasks (Sub-table)
    ├── Task 1
    │   ├── _id: "task_001"
    │   ├── embeddingRowID: "proj_001"
    │   ├── Title: "Design Homepage"
    │   ├── Assignee (Linked Table Field): "user_123"
    │   └── Status: "In Progress"
    └── Task 2
        ├── _id: "task_002"
        ├── embeddingRowID: "proj_001"
        ├── Title: "Develop Contact Form"
        ├── Assignee (Linked Table Field): "user_456"
        └── Status: "Not Started"

Users (Referenced by Tasks)
├── User 1
│   ├── _id: "user_123"
│   ├── Name: "Alice Designer"
│   └── Role: "Designer"
└── User 2
    ├── _id: "user_456"
    ├── Name: "Bob Developer"
    └── Role: "Developer"

Displaying Related Data

When you display data in Buzzy, you can automatically show related information:

1. Child data: Include a sub-table field on a screen to show all related child records

2. Linked data: Add fields from linked datatables to display related information

3. Parent data: Reference parent, grandparent, or great-grandparent fields for breadcrumb navigation

For example, when displaying an Invoice Line, you can show:

• The Invoice Number (from parent Invoice)

• The Organization Name (from grandparent Organization)

• The Product Name and Price (from linked Product datatable)

Working with Data Programmatically

Buzzy provides comprehensive APIs for working with your datamodel programmatically. For detailed examples and implementation guides, see:

• REST API Documentation - Full CRUD operations for external integrations

• Async API Documentation - Client-side data operations within Code Widgets

Security and Access Control

Buzzy's datamodel includes sophisticated security features:

• Viewers Field: Control who can see specific records

• Team Viewers Field: Combine team-based and user-based access

• Organizations Pattern: Multi-tenant SaaS security model

• Personal Data Pattern: User-specific data access

Performance Considerations

When designing your datamodel:

1. Limit nesting levels: While you can create multiple levels of relationships, test for performance with your expected data volumes

2. Use filtering: Apply filters to sub-tables and views to limit data retrieval

3. Consider indexing: For large datasets, consider how your queries will perform

4. Upgrade infrastructure: For high-performance needs, consider upgrading your Buzzy deployment

Best Practices

1. Plan your relationships: Sketch out your datamodel before implementation

2. Use consistent naming: Follow clear naming conventions for datatables and fields

3. Test with real data: Verify performance with realistic data volumes

4. Document your model: Keep track of relationships for team members

5. Start simple: Begin with basic relationships and add complexity as needed

Related Documentation

• Introduction to Fields

• Sub-tables

• Linked Table Fields

• Datatable to Datatable Relationships

• Security and Access Control

• REST API Documentation

• Async API Documentation

• App Examples

---

This documentation provides a comprehensive overview of Buzzy's datamodel capabilities. For specific implementation details, refer to the linked documentation sections above.