Sub tables
Sub-table fields create one-to-many (1:M) relationships between datatables, where one parent record can have multiple child records. This is one of the most powerful features in Buzzy's datamodel, allowing you to build complex hierarchical data structures.
Overview
A sub-table field automatically manages the relationship between parent and child records using the embeddingRowID
system. When you add a sub-table field to a datatable, child records are automatically linked to their parent record.
Parent Record (e.g., Restaurant Receipt)
βββ _id: "receipt_001"
βββ Restaurant: "Pizza Palace"
βββ Date: "2024-07-03"
βββ Items (Sub-table field)
βββ Item 1
β βββ _id: "item_001"
β βββ embeddingRowID: "receipt_001" β Automatic link to parent
β βββ Name: "Margherita Pizza"
β βββ Price: 18.99
βββ Item 2
βββ _id: "item_002"
βββ embeddingRowID: "receipt_001" β Automatic link to parent
βββ Name: "Caesar Salad"
βββ Price: 12.50
Common Use Cases
1. Invoice and Invoice Lines
Invoice
βββ _id: "inv_001"
βββ Invoice Number: "INV-2024-001"
βββ Customer: "Acme Corp"
βββ Invoice Lines (Sub-table)
βββ Line 1: Web Development - $1,500
βββ Line 2: Design Services - $800
βββ Line 3: Hosting Setup - $200
2. Project and Tasks
Project
βββ _id: "proj_001"
βββ Name: "Website Redesign"
βββ Status: "In Progress"
βββ Tasks (Sub-table)
βββ Task 1: Design Homepage
βββ Task 2: Develop Backend
βββ Task 3: User Testing
3. Order and Order Items
Order
βββ _id: "order_001"
βββ Customer: "John Doe"
βββ Order Date: "2024-07-03"
βββ Order Items (Sub-table)
βββ Item 1: Laptop - Qty: 1
βββ Item 2: Mouse - Qty: 2
βββ Item 3: Keyboard - Qty: 1
Multi-Level Hierarchies
You can create complex multi-level relationships by chaining sub-tables:
Organization (Level 1)
βββ _id: "org_001"
βββ Name: "Tech Solutions Inc"
βββ Departments (Sub-table - Level 2)
βββ Department 1
β βββ _id: "dept_001"
β βββ embeddingRowID: "org_001"
β βββ Name: "Engineering"
β βββ Projects (Sub-table - Level 3)
β βββ Project 1
β β βββ _id: "proj_001"
β β βββ embeddingRowID: "dept_001"
β β βββ Name: "Mobile App"
β β βββ Tasks (Sub-table - Level 4)
β β βββ Task 1: UI Design
β β βββ Task 2: Backend API
β βββ Project 2
β βββ Tasks (Sub-table)
βββ Department 2
βββ Projects (Sub-table)
Combining Sub-tables with Linked Table Fields
Sub-tables become even more powerful when combined with Linked Table Fields:
Invoice
βββ Invoice Lines (Sub-table)
βββ Line 1
β βββ embeddingRowID: "inv_001"
β βββ Quantity: 2
β βββ Product (Linked Table Field): "prod_123" β References Products datatable
β βββ Unit Price: $99.99
βββ Line 2
βββ embeddingRowID: "inv_001"
βββ Quantity: 1
βββ Product (Linked Table Field): "prod_456" β References Products datatable
βββ Unit Price: $149.99
Products Datatable (Referenced by Linked Table Fields)
βββ Product 1
β βββ _id: "prod_123"
β βββ Name: "Premium Widget"
β βββ Category: "Electronics"
β βββ Description: "High-quality widget"
βββ Product 2
βββ _id: "prod_456"
βββ Name: "Deluxe Widget"
βββ Category: "Electronics"
βββ Description: "Top-tier widget"
Displaying Related Data
When displaying records that use sub-tables, you can show data from multiple levels:
Current Row Data
Fields from the current record being displayed
Child Data (Sub-table)
Records from child datatables via sub-table fields
Automatically filtered to show only children of the current record
Linked Data
Data from datatables referenced by Linked Table Fields
Product names, user details, category information, etc.
Parent/Ancestor Data
Data from parent records (via embeddingRowID)
Grandparent and great-grandparent data for breadcrumb navigation
Example: When displaying an Invoice Line, you can show:
Line details (current record)
Product name and image (linked table data)
Invoice number and customer (parent data)
Organization name (grandparent data)
Performance Considerations
Sub-tables are powerful but require careful consideration for performance:
Best Practices
Limit nesting levels: While multiple levels are supported, test performance with realistic data volumes
Use filtering: Apply filters to sub-table views to limit data retrieval
Consider data volume: Large numbers of child records may impact performance
Test with real data: Always test with production-like data volumes
Monitor query performance: Watch for slow-loading screens with complex hierarchies
When to Consider Alternatives
Very large datasets: Consider pagination or alternative data structures
Frequently accessed data: Cache commonly used data
Complex queries: Consider flattening some relationships for performance
Infrastructure Scaling
For high-performance requirements:
Upgrade your Buzzy deployment for more powerful infrastructure
Consider database optimization for large datasets
Implement caching strategies for frequently accessed data
Setup Instructions
1. Create the Parent Datatable
Design your parent datatable with appropriate fields
Consider what child data will be related
2. Create the Child Datatable
Create the child datatable with its own fields
Include any Linked Table Fields for additional relationships
3. Add Sub-table Field to Parent
In the parent datatable, add a new field
Select "Sub-table" as the field type
Configure the target datatable (child datatable)
Set appropriate permissions and display options
4. Configure Display Options
Set how child records should be displayed
Configure sorting and filtering for the sub-table
Set permissions for who can add/edit child records
Working with Sub-tables Programmatically
For detailed API examples and implementation guides for working with sub-tables programmatically, see:
REST API Documentation - Full CRUD operations for external integrations
Async API Documentation - Client-side data operations within Code Widgets
Security and Access Control
Sub-tables inherit security settings but can have additional controls:
Parent-level security: Controls access to the parent record and all children
Child-level security: Additional controls on individual child records
Field-level permissions: Control who can edit specific fields in child records
See Security and Access Control for detailed information.
Real-World Examples
Chat Application
Based on our AI-Powered Chat App:
Chat
βββ Title: "Project Discussion"
βββ Messages (Sub-table)
βββ Message 1: "Let's discuss the timeline"
βββ Message 2: "Sounds good!"
βββ Message 3: "When can we start?"
Project Management
Project
βββ Name: "Website Redesign"
βββ Status: "Active"
βββ Tasks (Sub-table)
βββ Task 1
β βββ Title: "Design Homepage"
β βββ Assignee (Linked Table Field): User A
β βββ Status: "In Progress"
βββ Task 2
βββ Title: "Develop Backend"
βββ Assignee (Linked Table Field): User B
βββ Status: "Not Started"
Related Documentation
Buzzy Datamodel Overview - Complete guide to Buzzy's datamodel
Linked Table Fields - Many-to-many relationships
Datatable to Datatable Relationships - All relationship types
Security and Access Control - Protecting your data
REST API - Programmatic data access
Async API - Code Widget integration
App Examples - Real-world implementations
Last updated