> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gainable.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Data models
> How Gainable organizes and stores your application data
## Understanding data in Gainable
When you describe data in your prompts, Gainable creates **data models** — structured definitions of what information your app stores. Think of a data model as a template for each type of thing you're tracking.
Data models are also used to **merge and normalize** external data from multiple sources into a single unified output. When you need to combine contacts from HubSpot and Google Sheets by email, or normalize field names across systems, you create a data model with merge keys and field mappings, then include it in a [dataset](/building/data-connectors).
## What is a data model?
A data model defines:
* **What fields** each item has (name, email, status, etc.)
* **What type** each field is (text, number, date, etc.)
* **How items relate** to other items (belongs to, has many)
When you say "track deals with name, amount, and status", Gainable creates a Deal model:
| Field | Type | Description |
| --------- | ------- | -------------------------------- |
| name | Text | The deal name |
| amount | Number | The deal value |
| status | Options | Selected from predefined choices |
| createdAt | Date | Automatically added |
| updatedAt | Date | Automatically added |
## Collection types
The **Data** tab in your app groups collections into 3 categories:
| Aspect | App Collections | Data Collections | Core Collections |
| ------------ | ----------------------- | ------------------------------------ | -------------------------- |
| Source | Created in your app | Synced via datasets | Built-in system models |
| Editable | Yes | Read-only (managed via datasets) | Read-only |
| Examples | companies, deals, tasks | HubSpot contacts, Google Sheets rows | users, agents, connections |
| Chat enabled | Yes | No | No |
### App Collections
Custom collections created when you describe data models. Fully editable and specific to your app. These are what you build.
### Data Collections
External data synced via [datasets](/building/data-connectors) (HubSpot, Sheets, Stripe, etc.). They appear automatically when you attach a dataset to your app. Read-only from the app, managed through the datasets interface.
### Core Collections
Built-in system collections present in every app: users, agents, email templates, email logs, user field metadata, and connections. Read-only, managed by the platform.
## Field types
When describing your data, you can specify field types to get exactly what you need:
### Text fields
For names, descriptions, and other text content.
```text theme={null}
Prompt: "title (text)" or just "title"
Stores: Any text content
Example: "Enterprise License Renewal"
```
### Number fields
For quantities, amounts, and measurements.
```text theme={null}
Prompt: "quantity (number)" or "amount"
Stores: Numeric values
Example: 42, 3.14, 1000000
```
### Currency fields
For money values with proper formatting.
```text theme={null}
Prompt: "price (currency)" or "amount in dollars"
Stores: Numeric value
Displays: $1,234.56
```
### Date fields
For dates and timestamps.
```text theme={null}
Prompt: "due date" or "created date"
Stores: Date and time
Displays: Formatted date
```
### Option fields (Enums)
For selecting from a predefined list.
```text theme={null}
Prompt: "status (new, in progress, done)"
Stores: One of the specified options
Displays: Dropdown or badges
```
### Yes/No fields (Boolean)
For true/false values.
```text theme={null}
Prompt: "is active (yes/no)" or "completed (checkbox)"
Stores: True or false
Displays: Checkbox or toggle
```
### Reference fields
For linking to other data models.
```text theme={null}
Prompt: "assigned to (user)" or "belongs to company"
Stores: Link to another item
Displays: Name or selector
```
## Relationships between data
### One-to-Many
One item has multiple related items.
```text theme={null}
"Each project has many tasks"
"Tasks belong to a project"
```
This creates:
* Project model (parent)
* Task model with a "project" field linking to Project
### Many-to-One
Multiple items link to one item.
```text theme={null}
"Contacts belong to a company"
"Deals are linked to a contact"
```
### Self-referential
Items that reference the same type.
```text theme={null}
"Each employee has a manager (another employee)"
"Tasks can have subtasks"
```
## Automatic fields
Every data model automatically includes:
| Field | Purpose |
| ----------- | ------------------------------- |
| `_id` | Unique identifier for each item |
| `createdAt` | When the item was created |
| `updatedAt` | When the item was last modified |
You don't need to ask for these - they're always there.
## Merging data from multiple sources
When the same type of data lives in different systems — for example, contacts in both HubSpot and a Google Sheet — you can create a data model that merges them into a single unified output.
### How merging works
1. **Connect each source** to the data model
2. **Define a merge key** — a shared field (like email) used to match records across sources
3. **Set source priority** — choose which source takes precedence when the same field has different values
4. **Map fields** — select which columns to include, rename fields, and set types
The merged output can then be included in a [dataset](/building/data-connectors) alongside your raw source data.
You have contacts in HubSpot (with deal history) and a Google Sheet (with custom scoring). Both share an email column.
1. Create a **Contacts** data model
2. Connect HubSpot and Google Sheets as sources
3. Set **email** as the merge key
4. Set HubSpot as the primary source (higher priority)
5. Include the data model in your dataset
After sync, each contact has deal data from HubSpot and scoring from Google Sheets, matched by email. If both sources have a "company" field with different values, HubSpot's value is used because it has higher priority.
## Best practices
### Be explicit about fields
```text Good theme={null}
Build a contact manager with:
- Full name
- Email address
- Phone number
- Company
- Job title
- Notes
```
```text Vague theme={null}
Build a contact manager
```
### Specify options for status fields
```text Good theme={null}
Status options: draft, pending, approved, rejected
```
```text Vague theme={null}
Add a status field
```
### Name relationships clearly
```text Good theme={null}
Each task belongs to one project
Each project has many tasks
Tasks can be assigned to one user
```
```text Confusing theme={null}
Tasks, projects, and users are related
```
### Use meaningful field names
```text Good theme={null}
closeDate, expectedRevenue, primaryContact
```
```text Confusing theme={null}
date1, field2, ref
```
## Viewing your data
Once your app is built, you can:
* **See all items** in list views
* **Add new items** through forms
* **Edit items** by clicking on them
* **Delete items** with confirmation
* **Filter and search** to find specific items
## Data persistence
All data in Gainable apps is:
* **Automatically saved** when you create or edit items
* **Persistent** across sessions and users
* **Backed up** regularly
* **Accessible** via API endpoints
You don't need to worry about "saving" - data is stored as soon as you submit a form or complete an action.
## Learn more
Group external data sources and attach them to your app
How your data is displayed
Live data updates