{"section":"tutorials","requestedLocale":"en","requestedSlug":"data-entity","locale":"en","slug":"data-entity","path":"docs/en/tutorials/master-data/master-data-basics/data-entity.md","branch":"main","content":"A data entity is a representation of a set of information about a given concept. Each entity includes fields with information that makes up the entity.\n\nFor example, imagine a system that controls a library. This system controls books that customers can borrow. Thus, we can notice that these three concepts (book, customer, borrowing) are entities that contain information about each one. \n\n![data-entity-en](https://cdn.statically.io/gh/vtexdocs/help-center-content/refs/heads/main/docs/en/tutorials/master-data/master-data-basics/data-entity_1.png)\n\nWith these concepts in mind, you can set up several data control scenarios in Master Data. By default, the following data entities are considered: customer, address, stores, etc. You can create as many data entities as you want to develop a customized environment tailored to your store's needs.\n\n> ℹ️ Data entities created by your operation are considered custom entities and are subject to a monthly charge. Learn more in [Custom data entities](/docs/tutorials/master-data).\n\n> ⚠️ This article outlines the Master Data v1 operation. You should evaluate which Master Data version meets your needs or is in use in your operation. Learn more: \n\n> ⚠️ Deleting a data entity through the Master Data v1 interface does not remove the documents (records) already stored. The billed volume remains unchanged until the records are removed via the API. To delete documents and reduce billing, see the [Deleting documents in Master Data v1](https://developers.vtex.com/docs/guides/deleting-documents-in-master-data-v1) guide on the Developers Portal.\n\n## Data types\n\nThe data entity consists of fields that have a type. This type identifies the information characteristics stored in the field and enables validations, filters, and calculations based on the selected value.\n\nWhen creating a field, the following types are displayed:\n\n| Field type | Description\n| - | - |\n| **Auto Increment** | Stores integers and is automatically incremented, which means that for each new record, this field receives the value of the previous record + 1. |\n| **Boolean** | Stores true or false information, which means it will always be completed as `true` or `false`. |\n| **CEP** | Stores a CEP (postal code in Brazil). |\n| **CPF / CNPJ** | Stores the CPF and CNPJ information (taxpayer registration number and company registration number in Brazil, respectively). |\n| **Currency** | Stores information in currency format. |\n| **Date** | Stores date information. |\n| **Date and Time** | Stores date and time. |\n| **Decimal** | Stores numbers with the fractional part always set to 2. This field will always store 2 digits as decimal places of the value entered. |\n| **Email** | Stores an email. |\n| **File** | Stores a file. The maximum size accepted must be set up in the field’s options via the gear icon button. |\n| **Integer** | Stores integers, i.e., numbers without the fractional part. It stores whole numbers between `-2147483648` and `2147483647`. |\n| **Long** | Similar to **Integer** but can store more numbers. Stores from `-2⁶³` to `2⁶³-1`. |\n| **Percent** | Stores information in a percentage format. |\n| **Phone** | Stores information in a phone number format. |\n| **Relationship** | Creates a relationship with another entity. The term relationship refers to displaying an entity’s information in another entity. For example, in the library example, the **Customer** may also appear in the **Borrowing** record.

To do so, you just have to establish a relationship between **Borrowing** and **Customer** by using the **Name** field under **Borrowing** and selecting the **Relationship** type in the settings. The **Customer** field to be displayed must also be selected for the **Name** field to be selected. |\n| **Score2** | Field consisting of key, value, and expiration date. For example: This can be used to control purchases made by each customer, storing the amount and quantity of purchases. This field needs to be completed through the [Update scores](https://developers.vtex.com/docs/api-reference/masterdata-api#put-/api/dataentities/-acronym-/documents/-id-/score) or the [Update score by field](https://developers.vtex.com/docs/api-reference/masterdata-api#put-/api/dataentities/-acronym-/documents/-id-/score/-field-name-) endpoint from [Master Data API v1](https://developers.vtex.com/docs/api-reference/masterdata-api). |\n| **Text** | Stores numbers, letters, and special characters, without a character limit. |\n| **Time** | Stores time information. |\n| **URL** | Stores a URL. |\n| **User Login** | Automatically selects the user logged in. This is used to record the email of the user who performs an action on an entity record. |\n| **Varchar 10** | Stores numbers, letters, and special characters, limited to 10 characters. |\n| **Varchar 100** | Stores numbers, letters, and special characters, limited to 100 characters. |\n| **Varchar 50** | Stores numbers, letters, and special characters, limited to 50 characters. |\n| **Varchar 750** | Stores numbers, letters, and special characters, limited to 750 characters. |\n\n## Creating data entities\n\nFollow the steps below to configure a new data entity.\n\n1. In the VTEX Admin, go to **Store Settings** > **Storefront** > **Master Data.**\n2. In Master Data, click **Applications** > **Advanced Settings** > **Data structure.**\n3. Click the **Data Entities** tab.\n4. Click the `Add` button.\n5. Complete the **Acronym** field with 2 letters that identify the data entity. These letters will be the initials of the field that identifies the record. For example: use the acronym SP for identifier SP-0001.\n6. Complete the **Name** of the data entity you want to create.\n7. Select the type of primary key, which can be:\n\n - **GUID**: A unique sequence of numbers and characters that identifies a record.\n - **Primary key must be given using the 'ID' property**: This key does not automatically create an identifier field, which must be created manually and named **ID**.\n8. If you need to consult records without a filter and without authentication, check the option **Allow all document query without filter**. Note: This setting is critical because it allows all the records in the database to be listed via the API.\n9. Complete the **Fields** tab with the fields you want to include in the new data entity, indicated as follows.\n10. Complete the **Name** column with the field's identification value. Do not insert spaces or special characters. Example: CustomerName.\n11. Complete the **Display Name** column with the name that will be displayed on the form. Example: Customer name.\n12. Select the field type based on the options described in the [Data types](#data-typed) section.\n13. Click the gear icon to open the field configuration options.\n14. Complete the **General settings**:\n\n \t- **Is nullable?:** Check this option to create or edit a record with a blank (void) field. If this option is unchecked, you cannot create a record without a value in this field.\n \t- **Make readable without credentials:** Check this option to allow the field data to be read without authentication, using the Master Data API.\n \t- **Allow editing without credentials:** Check this option to allow data to be entered into the field without the need for authentication, using the Master Data API.\n \t- **Allow filtering without credentials:** Check this option to filter field data without the need for authentication, using the Master Data API.\n\n15. Complete the **Search and filter settings**:\n\n\t- **Is searchable?**: If this field is used for searching in the form and via API.\n\t- **Is filterable?:** If this field is used to filter the form and via API.\n16. Add a field description.\n17. To add more fields, click the `New Field` button and repeat steps 10 to 16.\n18. At the end of the field definition, click the `Save` button to complete or `Save and New` to create a new data entity.\n\n\tYou will be redirected back to the **Data Entity** tab.\n\n19. In the row of the newly created entity, click the diskette button to publish the created data entity.\n20. Click `OK`.\n21. Click the **Applications** tab to return to the Master Data homepage. \n22. Click the `Reload Applications` button.\n\n> ℹ️ After creating the data entity, [create the form for adding, changing, and displaying data in Master Data](/en/docs/tutorials/creating-form-in-master-data)."}