Entities
The Entity feature is an excellent tool for storing data in a tabular format. Unlike the Devices feature, which is optimized for storing sensor data with high-frequency write operations, the Entity feature offers a versatile solution for managing a wider variety of data types with less frequent write operations.
Within an Entity, you can create custom fields similar to columns in a traditional database and define specific data types. Additionally, you can enhance data operations by implementing single or multiple indexes, which improves search and retrieval performance when developing your application. For example, Entities can be used to store diverse data types such as site information, organizational metadata, contact lists, equipment details, and product information.
Once your information is stored, you will be able to easily access the data through Analysis, TagoIO API and, in the near future, Widgets.
Creating an Entity
To create a new entity, navigate to the Entity module on your Admin page. Click on "+ New Entity" where you will be prompted to define a name and add fields. Please note that once an entity is created, its name cannot be changed. However, you can still add or delete fields as needed.
The number of Entities you can have per profile is determined by your Plan. For detailed information, please refer to the Limits and Restrictions section.An entity in TagoIO is composed of several components that define its structure and behavior:
- Name: A unique identifier used to reference the entity in API calls and Dashboards.
- Fields: Customizable parameters or columns that outline the structure of each item in your entity database.
- Indexes: Configurations that specify which fields are searchable and how they are ordered.
- Schema Parser: JavaScript code that executes upon data insertion to validate or normalize the data before it is stored.
- Tags: Labels utilized to identify and connect the appropriate entity with various features within an application. For further information, explore the Tags System.
Mandatory default fields
When creating a new entity you will notice some default fields that cannot be removed or changed. Such fields are detailed below:
| Field | Description |
| id | A Universally Unique Identifier (UUID) for the data entry, automatically generated if not provided |
| created_at | Timestamp of when the data entry was created |
| updated_at | Timestamp of the last time the data was edited |
Managing fields
You can easily manage your fields by accessing the Fields tab within your Entity. Here, you have the option to add, edit and remove fields.
Adding new fields
To add a new field, go to the Fields tab and click on the "+ Add Field" button. When creating an entity, you can specify a field name, select a data type, and determine whether the field is mandatory.
Once a field is created, you can edit its name and required status. However, the data type is fixed and cannot be changed after creation. If necessary, you have the option to delete existing fields and create new ones to suit your needs.
- Name: The reference name of the field used in API calls and data operations
- Data Type: The value type the field will contain
- Required: Defines if the field must have a value or can be empty
The number of fields available per entity is determined by your subscription Plan. For more detailed information, please refer to the Limits and Restrictions section.
Data types
When adding new fields, you have several data types to choose from. It's important to note that once a field is created, its data type cannot be changed. Below is a description of each data type available:
| Data Type | Description |
| String | A variable-length string. Maximum size of 255 characters |
| Integer | An integer number (e.g., 10) |
| Float | A floating-point number (e.g., 10.5) |
| Text | A long text string. Maximum size of 30,000 characters |
| Timestamp | A date/time in ISO-8601 format |
| JSON Data | A JSON object, maximum size of 10 KB |
Indexing fields to improve searching and sorting
In order to optimize search operations and determine the order of results, you can index your data. Indexing is the way to get an unordered table into an order that will maximize the query's efficiency while searching. Indexes play a crucial role in improving database performance and are required for API and Analysis requests.
You can manage indexes by accessing the Fields tab. By default, every entity will have an index for the default field "id".
Adding new indexes
To create a new index, go to the Fields tab and click the "+ Add Index" button. From this menu, you can select the fields you want to include in the index and assign it a name. Please note that indexes cannot be edited once created, but they can be deleted and recreated if necessary.
Since you can add multiple fields to your index, the order of selection is crucial because sorting is only possible by the last field chosen. Additionally, some dashboard functionalities will automatically select the most appropriate index based on the filters applied, unless a specific index is explicitly designated.
Using Indexes
When filtering data, you must provide all filters matching the index from left to right.
- You don't need to use all fields in the index, but you must use them in order, starting from the leftmost field.
- For example, if you have an index with fields (A, B, C):
- You can filter using only field A
- You can filter using fields A and B
- You can filter using fields A, B, and C
- You cannot filter using only B, or B and C, without including A
The number of indexes available per entity is determined by your subscription Plan. For more detailed information, please refer to the Limits and Restrictions section.
Preprocessing data before insertion
Before storing data in your entity, you can preprocess it using the Schema Parser. This tool is especially beneficial for validating, normalizing, or transforming data before storage. The Schema Parser operates as a JavaScript code that executes during data insertion.
To activate it, go to the Schema Parser tab and toggle the "Enable" button. Once activated, you can begin writing your code.
Global Variables
The following global variables are available in the Schema Parser:
| Variable | Description |
| payload | Content of the message being inserted. Usually an Array of data or a string. |
| dayjs | Day.js library for date/time operations. |
Managing the data in your Entity
Once the data is added to your Entity, you can easily manage it by viewing, filtering, inserting, editing and deleting data entries. You can also managed your data through Analysis SDK or TagoIO API.
Additionally, you can completely empty the data of your Entity by going to the 'More' tab and clicking the 'Empty Entity Data' button.
The number of data entries available per entity is determined by your subscription Plan. For more detailed information, please refer to the Limits and Restrictions section.
Best Practices when managing your data.
- Regularly review and clean up outdated or invalid data
- Use Analysis scripts for bulk operations and complex data management tasks
- Implement robust validation in your Schema Parser to ensure data integrity
Limits and Restrictions
The Entity has certain limits based on your TagoIO account plan. These limits apply to the number of entities, fields, indexes, and data entries you can create.
Maximum number of Entity features per Profile
| Feature | Free | Starter | Scale |
| Entities | 5 | 50 | 80 |
| Fields per Entity | 10 | 30 | 30 |
| Indexes per Entity | 2 | 10 | 10 |
| Fields per Index | 5 | 5 | 5 |
| Data Entries | 1,000 | 100,000 | 100,000 |
Rate Limits
Entity operations are subject to the same rate limits (Requests Per Minute) as other mutable operations in your plan. For detailed information on these limits, please refer to the Rate Limits (Hard limits) documentation.
Related Articles
Payload Parser Troubleshooting
When using the Payload Parser on TagoIO, you might run into some common problems that stop the parser from decoding your device data correctly. This means the data won't be saved on TagoIO. These problems are usually related to mistakes in how the ...Form Fields Visibility
Fields Visibility offers the possibility to control the visibility of certain fields in your Input Form widget. By using this feature, you are able to define conditions to hide some fields based on the values of other fields. For example, the field ...Payload Parser
The Payload Parser handles the raw payload sent by the devices in order to extract the measured variables. For example, it can be used to transform an HEX payload sent by a device into temperature and battery levels. You can also use it to handle the ...Filtering Out Variables with Parser Code
When your device sends data from a sensor to TagoIO, a parser code may be added to your device (located in the 'Payload Parser' tab) to extract and create the variables in the Device's data storage using TagoIO format. If you want to save space in ...Building your own parser
In this tutorial, you will learn how to convert (parse) a raw payload sent by a device into actual measurable variables. Data flow structure You can create parses for devices that weren't found in our list of Devices, so that you had to use a ...