> For the complete documentation index, see [llms.txt](https://docs.buzzy.buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview.md).

# Buzzy Datamodel Overview

## What is the Buzzy Datamodel?

The Buzzy datamodel is the structured data layer behind your app. It defines the datatables, fields, relationships, row access, field access, and Private Data controls that screens, functions, APIs, MCP tools, and widgets use at runtime.

A **datatable** is a record type. For example:

* a Short Stays app might have Property, Guest, Booking, Payment, Review, and Maintenance Request datatables
* a care coordination app might have Client, Care Plan, Visit, Service, Carer, Task, and Incident datatables
* a compliance workflow app might have Request, Finding, Evidence, Review, Approver, and Audit Event datatables

Each datatable contains rows. Each row contains fields. Screens then use those datatables to render views, forms, details, filters, dashboards, and widgets.

```mermaid
flowchart LR
    D["Datatable<br/>Booking"] --> R["Rows<br/>one booking per row"]
    R --> F["Fields<br/>guest, dates, status, amount"]
    F --> S["Screens<br/>list, detail, create, edit"]
    S --> A["Actions<br/>submit, approve, cancel, notify"]
```

Buzzy can also model complex data relationships, including **1:M (one-to-many)** and **N:M (many-to-many)** relationships. You do not need to manually create database foreign keys; Buzzy manages relationship context through datatable configuration, sub-table fields, linked-table fields, and row metadata.

### Core Concepts

**Datatable**: A structured record type made up of fields. Each row in the datatable is one record.

**Fields**: The values and controls on each row. Field types include text, number, date, location, image, file, selection, toggle, rating, formula, viewers, team viewers, sub-table, linked table, and more.

**Rows**: Individual records in a datatable. A Property datatable contains property rows. A Booking datatable contains booking rows.

**Relationships**: Connections between datatables. Use sub-table fields for parent-owned child rows and linked-table fields for references to records in another datatable.

**Screens**: Runtime surfaces that read and update datatables through views, forms, fields, filters, widgets, and actions.

**Organizations and Teams**: Access groups that can be used with Viewers and Team Viewers patterns to separate tenants, departments, review groups, support queues, or other real-world groups.

**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

## How Screens Use Datatables

Datatables are not just storage. They are what screens bind to.

| Screen pattern       | Datamodel dependency                                                                |
| -------------------- | ----------------------------------------------------------------------------------- |
| List screen          | A view component queries a datatable and renders repeated rows.                     |
| Detail screen        | The screen receives or loads one row and displays fields in read or summary mode.   |
| Create screen        | A form captures insert-mode fields and creates a new row.                           |
| Edit screen          | A form displays edit-mode fields for an existing row.                               |
| Dashboard            | Views aggregate, filter, or summarize rows from one or more datatables.             |
| Child table          | A sub-table field shows child rows scoped to the current parent row.                |
| Search/filter screen | Filter fields feed filter context into a view over a datatable.                     |
| Widget-backed screen | A widget or code widget reads or updates app data through the current user context. |

## 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](https://github.com/Buzzy-Buzz/buzzy-docs-gitbook/blob/main/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 Reference](/developing-and-extending-buzzy/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 [security and access-control 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
* **Field view and Field edit**: Control which visible-row fields each user or group can see or change
* **Private Data**: Mask, hide, encrypt, gate attachments, and audit sensitive field access

Row access is the first server-side gate. Field access and Private Data apply after row access is granted.

## 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 Reference](/developing-and-extending-buzzy/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.*