> ## Documentation Index
> Fetch the complete documentation index at: https://canopy.wnstn.space/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Core Concepts: The Cano Analytics Data Model Explained
> Understand Cano's data model — workspaces, events, users, properties, dashboards, data sources, and reports — before you start building.
Before you instrument your first event or build your first dashboard, it pays to understand how Cano Analytics models your data. Cano's design is intentionally simple: a small set of well-defined concepts fits together in predictable ways, so the skills you learn on one part of the platform transfer everywhere. This page walks through each concept, explains how they relate, and points you toward the practical guides that put them to use.
***
## Workspace
A **workspace** is the top-level organizational unit in Cano Analytics. Every piece of data — events, users, dashboards, reports, and API keys — belongs to exactly one workspace. Workspaces are completely isolated from one another, so teams or projects that need a strict data boundary should each have their own.
You can invite multiple members to a workspace and assign them roles (Admin, Editor, or Viewer) to control what they can see and change. Most organizations create one workspace per product environment (e.g. `Acme Production` and `Acme Staging`) to keep live and test data separate.
***
## Events
An **event** is a record of something that happened in your product. Every event has three required fields:
| Field | Description |
| ----------- | --------------------------------------------------------------------------------------- |
| `name` | A snake\_case string identifying the action (e.g. `page_viewed`, `purchase_completed`). |
| `timestamp` | The UTC time the action occurred. Set automatically by the SDK, or provided by you. |
| `user_id` | The identifier of the user who performed the action. |
Events are immutable once written — they represent a factual record of what happened. You send events to Cano using the `track()` method in any SDK or by posting to the [Events API endpoint](https://api.canoanalytics.io/v1).
```javascript Tracking an Event theme={null}
cano.track('purchase_completed', {
userId: 'usr_456',
properties: {
order_id: 'ord_789',
amount: 149.00,
currency: 'USD',
items: 3,
},
});
```
***
## Users
A **user** in Cano represents a person (or account) that interacts with your product. You create and update user records by calling `identify()`, which associates a stable `user_id` with a set of **traits** — descriptive attributes like name, email, plan, or signup date.
```python Identifying a User theme={null}
cano.identify(
user_id='usr_456',
traits={
'name': 'Jordan Lee',
'email': 'jordan@example.com',
'plan': 'pro',
'signed_up_at': '2024-01-15T09:00:00Z',
}
)
```
Once you call `identify()`, Cano automatically links every future (and past) event that carries the same `user_id` to that user profile. This lets you segment event data by user traits — for example, *"show me all `purchase_completed` events from users on the Pro plan."*
You don't need to call `identify()` before sending events. If Cano receives an event for an unknown `user_id`, it creates an anonymous user record automatically. You can enrich it with traits later.
***
## Properties
**Properties** are key-value pairs attached to events and users that add context to raw actions. They're the primary way you answer "who did what, and under what circumstances?"
Cano supports four property types:
| Type | Example Value | Use Case |
| --------------- | ------------------------ | ----------------------------- |
| String | `"pro"`, `"organic"` | Plans, sources, categories |
| Number | `149.00`, `3` | Revenue, counts, scores |
| Boolean | `true`, `false` | Feature flags, consent status |
| Date (ISO 8601) | `"2024-05-10T14:32:07Z"` | Timestamps, trial end dates |
Properties on **events** describe the action itself (`amount`, `currency`, `page_url`). Properties on **users** (called traits) describe the person (`plan`, `country`, `company_size`). Both are queried the same way in the dashboard.
***
## Dashboards
A **dashboard** is a collection of charts, each powered by a query against your event data. Dashboards update in real time as new events arrive, and you can pin any number of them to your workspace home screen for at-a-glance monitoring.
Each chart on a dashboard is defined by:
* An **event name** to query (e.g. `purchase_completed`)
* Optional **filters** on event or user properties (e.g. `plan = 'pro'`)
* A **visualization type** (line, bar, funnel, pie, or number)
* A **time range** and **granularity** (hourly, daily, weekly)
Dashboards are shareable — you can give anyone on your team a direct link, or embed a read-only view in an internal tool.
***
## Data Sources
**Data sources** are external systems connected to Cano so their data can enrich your event analytics. Instead of rebuilding everything inside Cano, you bring in context from where it already lives.
Cano supports three categories of data source:
* **Databases** — PostgreSQL, MySQL, BigQuery, Snowflake, Redshift
* **SaaS Tools** — Stripe, Salesforce, HubSpot, Intercom
* **Cloud Storage** — Amazon S3, Google Cloud Storage (CSV/JSON imports)
Once connected, data source tables appear alongside your event data in the query builder, enabling joins like *"show me revenue per user segment from Stripe, broken down by sign-up source from Cano events."*
***
## Reports
A **report** is a saved query or a snapshot of a dashboard, designed for sharing and scheduling. Where dashboards show live data, reports capture a point-in-time view that can be reproduced, versioned, and delivered automatically.
You can:
* **Schedule** a report to run daily, weekly, or monthly and deliver it via email or Slack
* **Share** a report link with stakeholders who don't have a Cano login
* **Export** report data as CSV or JSON for use in other tools
Reports reference the same underlying event data and data sources as dashboards, so there's no duplication of setup work.
***
## How Events, Users, and Properties Relate
The table below summarizes the relationship between the three core data objects you'll work with most often.
| Concept | Belongs To | Linked Via | Example |
| -------------- | ---------- | ------------ | ---------------------------------------- |
| Event | Workspace | `user_id` | `purchase_completed` by `usr_456` |
| User | Workspace | `user_id` | `usr_456` with trait `plan: "pro"` |
| Event Property | Event | Event record | `amount: 149.00` on `purchase_completed` |
| User Trait | User | User record | `country: "US"` on `usr_456` |
Every event is linked to a user through the shared `user_id`. This join is what lets Cano answer questions like *"how many Pro-plan users completed a purchase this week?"* — it's reading event records and filtering by the traits stored on the linked user profiles.
**Data Retention:** By default, Cano retains raw event data for 24 months. Aggregated chart data is retained indefinitely. You can configure custom retention windows in **Settings → Data Management**. Deleting a workspace permanently removes all associated events, users, and reports.
***
## Keep Going
Put these concepts into practice — send your first event and build your first dashboard in 5 minutes.
Learn the full `track()` API: naming conventions, property types, batching, and error handling.