Stand with Ukraine flag
Try it now Pricing
Community Edition
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation > Key concepts > Entities and relations
Getting Started
Devices Library Guides Installation Architecture API FAQ
On this page

Entities and relations

Entities Overview

ThingsBoard provides the user interface and REST APIs to provision and manage multiple entity types and their relations in your IoT application. Supported entities are:

  • Tenants - you can treat the tenant as a separate business-entity: it’s an individual or an organization who owns or produce devices and assets; Tenant may have multiple tenant administrator users and millions of customers, devices and assets;
  • Customers - the customer is also a separate business-entity: individual or organization who purchase or uses tenant devices and/or assets; Customer may have multiple users and millions of devices and/or assets;
  • Users - users are able to browse dashboards and manage entities;
  • Devices - basic IoT entities that may produce telemetry data and handle RPC commands. For example, sensors, actuators, switches;
  • Assets - abstract IoT entities that may be related to other devices and assets. For example factory, field, vehicle;
  • Entity Views - useful if you like to share only part of device or asset data to the customers;
  • Alarms - events that identify issues with your assets, devices, or other entities;
  • Dashboards - visualization of your IoT data and ability to control particular devices through the user interface;
  • Rule Node - processing units for incoming messages, entity lifecycle events, etc;
  • Rule Chain - defines the flow of the processing in the Rule Engine. May contain many rule nodes and links to other rule chains;

Each entity supports:

  • Attributes - static and semi-static key-value pairs associated with entities. For example serial number, model, firmware version;
  • Time-series data - time-series data points available for storage, querying and visualization. For example temperature, humidity, battery level;
  • Relations - directed connections to other entities. For example contains, manages, owns, produces.

Some entities support profiles:

  • Tenant Profiles - contains common settings for multiple tenants: entity, API and rate limits, etc. Each Tenant has the one and only profile at a single point in time.
  • Device Profiles - contains common settings for multiple devices: processing and transport configuration, etc. Each Device has the one and only profile at a single point in time.
  • Asset Profiles - contains common settings for multiple assets: processing configuration, etc. Each Asset has the one and only profile at a single point in time.

This guide provides an overview of the features listed above, some useful links to get more details, and real-life examples of their usage.


Entity relation defines connection between two ThingsBoard entities that belong to the same Tenant. The relation has an arbitrary type: Contains, Manages, Supports, etc. The relation is also directional. You may treat ThingsBoard relations as a Has-a relationship from object-oriented programming.

Relations help to model physical world objects in ThingsBoard. The easiest way to understand them is using the example. Let’s assume we want to build an application that collects data from soil moisture and temperature sensors, visualize this data on the dashboard, detect issues, raise alarms and control the irrigation. Let’s also assume we want to support multiple fields with hundreds of sensors. Fields may be also grouped into the Geo regions.

The following diagram explains how those entities are configured and stored in ThingsBoard:


See “add and delete assets” and “manage asset relations” to learn how to configure this entities via Administration UI. You may also use REST API to create entities and relations programmatically.

Next steps

Assign attributes to the assets and devices

ThingsBoard provides the ability to assign attributes to entities and manage them. You are welcome to learn how to do it here:

Working with device attributes

Upload telemetry data from devices

ThingsBoard provides the ability to work with telemetry data for devices and other entities. You are welcome to learn how to do it here:

Working with telemetry data

Creating Rules for Alarms

ThingsBoard provides the ability to raise alarms using rule engine for devices and other entities. You are welcome to learn how to do it here:

Working with alarms

Design your dashboard

Please import the following dashboard that demonstrates Map, Alarm, Entity Table and Charts widgets.