# 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](/the-building-blocks/datatables-fields-and-data/advanced-fields/sub-tables.md) 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](/the-building-blocks/datatables-fields-and-data/advanced-fields/linked-table-field.md) 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](/working-with-buzzy/buzzy-app-examples/buzzy-ai-chat-app.md) 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](/rest-api/buzzy-rest-api/rest-api.md) - Full CRUD operations for external integrations
* [Async API Documentation](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components.md) - Client-side data operations within Code Widgets

## Security and Access Control

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

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

***

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.