# Buzzy Datamodel Overview

## 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](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/advanced-fields/sub-tables) 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](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/advanced-fields/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](https://docs.buzzy.buzz/working-with-buzzy/buzzy-app-examples/buzzy-ai-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: "john@example.com"
    └── Message 2
        ├── _id: "msg_002"
        ├── embeddingRowID: "chat_001"
        ├── Content: "Sounds good, when can we start?"
        └── Author: "jane@example.com"
```

### 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](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api) - Full CRUD operations for external integrations
* [Async API Documentation](https://docs.buzzy.buzz/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components) - Client-side data operations within Code Widgets

## Security and Access Control

Buzzy's datamodel includes sophisticated [security features](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/security-and-access-control):

* **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](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/introduction-to-fields)
* [Sub-tables](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/advanced-fields/sub-tables)
* [Linked Table Fields](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/advanced-fields/linked-table-field)
* [Datatable to Datatable Relationships](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/datatable-to-datatable-relationships)
* [Security and Access Control](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/security-and-access-control)
* [REST API Documentation](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api)
* [Async API Documentation](https://docs.buzzy.buzz/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components)
* [App Examples](https://docs.buzzy.buzz/working-with-buzzy/buzzy-app-examples)

***

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