# Entities and data actions: Configure your app's data model
<a name="data"></a>

**Entities** are data tables in App Studio. Entities interact directly with tables in data sources. Entities include fields to describe the data in them, queries to locate and return data, and mapping to connect the entity's fields to a data source's columns.

**Topics**
+ [Best practices when designing data models](data-model-best-practices.md)
+ [Creating an entity in an App Studio app](data-entities-create.md)
+ [Configuring or editing an entity in an App Studio app](data-entities-edit.md)
+ [Deleting an entity](data-entities-delete.md)
+ [Managed data entities in AWS App Studio](managed-data-entities.md)

# Best practices when designing data models
<a name="data-model-best-practices"></a>

Use the following best practices to create a robust, scalable, and secure relational data model in AWS for use in your App Studio application that meets your application's requirements and ensures the long-term reliability and performance of your data infrastructure.
+ **Choose the right AWS data service: ** Depending on your requirements, choose the appropriate AWS data service. For example, for an Online Transaction Processing (OLTP) application, you could consider a database (DB) such as Amazon Aurora which is a cloud-native, relational, and fully-managed database service that supports various database engines like MySQL and PostgreSQL. For a full list of Aurora versions supported by App Studio, see [Connect to Amazon Aurora](connectors-aurora.md). On the other hand, for Online Analytical Processing (OLAP) use cases, consider using Amazon Redshift, which is a cloud data warehouse that lets you run complex queries against very large datasets. These queries can often take time (many seconds) to complete, making Amazon Redshift less suitable for OLTP applications that require low-latency data access.
+ **Design for scalability: **Plan your data model with future growth and scalability in mind. Consider factors like expected data volume, access patterns, and performance requirements when choosing an appropriate data service and database instance type and configuration (such as provisioned capacity).
  + For more information about scaling with Aurora serverless, see [Performance and scaling for Aurora Serverless V2](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless-v2.setting-capacity.html).
+ **Normalize your data: **Follow the principles of database normalization to minimize data redundancy and improve data integrity. This includes creating appropriate tables, defining primary and foreign keys, and establishing relationships between entities. In App Studio, when querying data from one entity, you can retrieve related data from another entity by specifying a `join` clause on the query.
+ **Implement appropriate indexing: **Identify the most important queries and access patterns, and create appropriate indexes to optimize performance.
+ **Leverage AWS data services features: **Take advantage of the features offered by the AWS data service you choose, such as automated backups, multi-AZ deployments, and automatic software updates.
+ **Secure your data: **Implement robust security measures, such as IAM (AWS Identity and Access Management) policies, creation of database users with restricted permissions to tables and schemas, and enforce encryption at rest and in transit.
+ **Monitor and optimize performance: **Continuously monitor your database's performance and make adjustments as needed, such as scaling resources, optimizing queries, or tuning database configurations.
+ **Automate database management: **Utilize AWS services like Aurora Autoscaling, Performance Insights for Aurora, and AWS Database Migration Service to automate database management tasks and reduce operational overhead.
+ **Implement disaster recovery and backup strategies: **Ensure that you have a well-defined backup and recovery plan, leveraging features like Aurora Automated Backups, point-in-time recovery, and cross-region replica configurations.
+ **Follow AWS best practices and documentation: **Stay up-to-date with the latest AWS best practices, guidelines, and documentation for your chosen data service to ensure that your data model and implementation are aligned with AWS recommendations.

For more detailed guidance from each AWS data service, see the following topics:
+ [Best practices with Amazon Aurora](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.BestPractices.html)
+ [Best practices with Amazon Aurora MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.BestPractices.html)
+ [Amazon Redshift query performance tuning](https://docs.aws.amazon.com/redshift/latest/dg/c-optimizing-query-performance.html)
+ [Best practices for querying and scanning data in Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-query-scan.html)

# Creating an entity in an App Studio app
<a name="data-entities-create"></a>

There are four methods for creating an entity in an App Studio app. The following list contains each method, its benefits, and a link to the instructions for using that method to create and then configure the entity.
+ [Creating an entity from an existing data source](#data-entities-create-existing-data-source): Automatically create an entity and its fields from an existing data source table and map the fields to the data source table columns. This option is preferable if you have an existing data source that you want to use in your App Studio app.
+ [Creating an entity with an App Studio managed data source](#data-entities-create-managed-data-source): Create an entity and a DynamoDB table that App Studio manages for you. The DynamoDB table is automatically updated as you update your entity. With this option, you don't have to manually create, manage, or connect a third-party data source, or designate mapping from entity fields to table columns. All of your app's data modeling and configuration is done in App Studio. This option is preferable if you don't want to manage your own data sources and a DynamoDB table and its functionality is sufficient for your app.
+ [Creating an empty entity](#data-entities-create-empty): Create an empty entity entirely from scratch. This option is preferable if you don't have any existing data sources or connectors created by an admin, and you want to flexibly design your app's data model without being constrained by external data sources. You can connect the entity to a data source after creation.
+ [Creating an entity with AI](#data-entities-create-with-ai): Generate an entity, fields, data actions, and sample data based on the specified entity name. This option is preferable if you have an idea of the data model for your app, but you want help translating it into an entity.

## Creating an entity from an existing data source
<a name="data-entities-create-existing-data-source"></a>

Use a table from a data source to automatically create an entity and its fields, and map the entity fields to the columns of the table. This option is preferable if you have an existing data source that you want to use in your App Studio app.

1. If necessary, navigate to your application.

1. Choose the **Data** tab at the top of the canvas.

1. If there are no entities in your app, choose **\$1 Create entity**. Otherwise, in the left-side **Entities** menu, choose **\$1 Add**.

1. Select **Use a table from an existing data source**.

1. In **Connector**, select the connector that contains the table you want to use to create your entity.

1. In **Table**, choose the table you want to use to create your entity.

1. Select the **Create data actions** checkbox to create data actions.

1. Choose **Create entity**. Your entity is now created, and you can see it in the left-hand **Entities** panel.

1. Configure your new entity by following the procedures in [Configuring or editing an entity in an App Studio app](data-entities-edit.md). Note that because your entity was created with an existing data source, some properties or resources have already been created, such as fields, the connected data source, and field mapping. Also, your entity will contain data actions if you selected the **Create data actions** checkbox during creation.

## Creating an entity with an App Studio managed data source
<a name="data-entities-create-managed-data-source"></a>

Create a managed entity and corresponding DynamoDB table that is managed by App Studio. While the DynamoDB table exists in the associated AWS account, when changes are made to the entity in the App Studio app, the DynamoDB table is updated automatically. With this option, you don't have to manually create, manage, or connect a third-party data source, or designate mapping from entity fields to table columns. This option is preferable if you don't want to manage your own data sources and a DynamoDB table and its functionality is sufficient for your app. For more information about managed entities, see [Managed data entities in AWS App Studio](managed-data-entities.md).

You can use the same managed entities in multiple applications. For instructions, see [Creating an entity from an existing data source](#data-entities-create-existing-data-source).

1. If necessary, navigate to your application.

1. Choose the **Data** tab at the top of the canvas.

1. If there are no entities in your app, choose **\$1 Create entity**. Otherwise, in the left-side **Entities** menu, choose **\$1 Add**.

1. Select **Create App Studio managed entity**.

1. In **Entity name**, provide a name for your entity.

1. In **Primary key**, provide a name for the primary key of your entity. The primary key is the unique identifier of the entity and cannot be changed after the entity is created.

1. In **Primary key data type**, select the data type of primary key of your entity. The data type cannot be changed after the entity is created.

1. Choose **Create entity**. Your entity is now created, and you can see it in the left-hand **Entities** panel.

1. Configure your new entity by following the procedures in [Configuring or editing an entity in an App Studio app](data-entities-edit.md). Note that because your entity was created with managed data, some properties or resources have already been created, such as the primary key field, and the connected data source.

## Creating an empty entity
<a name="data-entities-create-empty"></a>

Create an empty entity entirely from scratch. This option is preferable if you don't have any existing data sources or connectors created by an admin. Creating an empty entity offers flexibility, as you can design your entity within your App Studio app without being constrained by external data sources. After you design your app's data model, and configure the entity accordingly, you can still connect it to an external data source later.

1. If necessary, navigate to your application.

1. Choose the **Data** tab at the top of the canvas.

1. If there are no entities in your app, choose **\$1 Create entity**. Otherwise, in the left-side **Entities** menu, choose **\$1 Add**.

1. Select **Create an entity**.

1. Choose **Create entity**. Your entity is now created, and you can see it in the left-hand **Entities** panel.

1. Configure your new entity by following the procedures in [Configuring or editing an entity in an App Studio app](data-entities-edit.md).

## Creating an entity with AI
<a name="data-entities-create-with-ai"></a>

Generate an entity, fields, data actions, and sample data based on the specified entity name. This option is preferable if you have an idea of the data model for your app, but you want help translating it into an entity.

1. If necessary, navigate to your application.

1. Choose the **Data** tab at the top of the canvas.

1. If there are no entities in your app, choose **\$1 Create entity**. Otherwise, in the left-side **Entities** menu, choose **\$1 Add**.

1. Select **Create an entity with AI**.

1. In **Entity name**, provide a name for your entity. This name is used to generate the fields, data actions, and sample data of your entity.

1. Select the **Create data actions** checkbox to create data actions.

1. Choose **Generate an entity**. Your entity is now created, and you can see it in the left-hand **Entities** panel.

1. Configure your new entity by following the procedures in [Configuring or editing an entity in an App Studio app](data-entities-edit.md). Note that because your entity was created with AI, your entity will already contain generated fields. Also, your entity will contain data actions if you selected the **Create data actions** checkbox during creation.

# Configuring or editing an entity in an App Studio app
<a name="data-entities-edit"></a>

Use the following topics to configure an entity in an App Studio application.

**Topics**
+ [Editing the entity name](data-entities-edit-name.md)
+ [Adding, editing, or deleting entity fields](data-entities-edit-fields.md)
+ [Creating, editing, or deleting data actions](data-entities-edit-data-actions.md)
+ [Adding or deleting sample data](data-entities-edit-sample-data.md)
+ [Add or edit connected data source and map fields](data-entities-edit-connection.md)

# Editing the entity name
<a name="data-entities-edit-name"></a>

1. If necessary, navigate to the entity you want to edit.

1. In the **Configuration** tab, in **Entity name**, update the entity name and choose outside of the text box to save your changes.

# Adding, editing, or deleting entity fields
<a name="data-entities-edit-fields"></a>

**Tip**  
You can press CTRL\$1Z to undo the most recent change to your entity.

1. If necessary, navigate to the entity you want to edit.

1. In the **Configuration** tab, in **Fields**, you view a table of your entity's fields. Entity fields have the following columns:
   + **Display name:** The display name is similar to a table header or form field and is viewable by application users. It can contain spaces and special characters but must be unique within an entity.
   + **System name:** The system name is a unique identifier used in code to reference a field. When mapping to a column in an Amazon Redshift table, it must match the Amazon Redshift table column name.
   + **Data type:** The type of data that will be stored within this field, such as `Integer`, `Boolean`, or `String`.

1. To add fields:

   1. To use AI to generate fields based on entity name and connected data source, choose **Generate more fields**.

   1. To add a single field, choose **\$1 Add field**.

1. To edit a field:

   1. To edit the display name, enter the desired value in the **Display name** text box. If the system name of the field hasn't been edited, it will be updated to the new value of the display name.

   1. To edit the system name, enter the desired value in the **System name** text box.

   1. To edit the data type, choose the **Data type** dropdown menu and select the desired type from the list.

   1. To edit the field's properties, choose the gear icon of the field. The following list details the field properties:
      + **Required**: Enable this option if the field is required by your data source.
      + **Primary key**: Enable this option if the field is mapped to a primary key in your data source.
      + **Unique**: Enable this option if the value of this field must be unique.
      + **Use data source default**: Enable this option if the value of the field is provided by the data source, such as using auto-increment, or an event timestamp.
      + **Data type options**: Fields of certain data types can be configured with data type options such as minimum or maximum values.

1. To delete a field, choose the trash icon of the field you want to delete.

# Creating, editing, or deleting data actions
<a name="data-entities-edit-data-actions"></a>

Data actions are used in applications to run actions on an entity's data, such as fetching all records, or fetching a record by ID. Data actions can be used to locate and return data matching specified conditions to be viewed in components such as tables or detail views.

**Contents**
+ [Creating data actions](#data-entities-data-action-add)
+ [Editing or configuring data actions](#data-entities-data-action-edit)
+ [Data action condition operators and examples](#data-entities-data-action-operators)
  + [Condition operator support by database](#data-entities-data-action-operators-support)
  + [Data action condition examples](#data-entities-data-action-operators-examples)
+ [Deleting data actions](#data-entities-data-action-delete)

## Creating data actions
<a name="data-entities-data-action-add"></a>

**Tip**  
You can press CTRL\$1Z to undo the most recent change to your entity.

1. If necessary, navigate to the entity for which you want to create data actions.

1. Choose the **Data actions** tab.

1. There are two methods for creating data actions:
   + (Recommended) To use AI to generate data actions for you, based on your entity name, fields, and connected data source, choose **Generate data actions**. The following actions will be generated:

     1. `getAll`: Retrieves all the records from an entity. This action is useful when you need to display a list of records or perform operations on multiple records at once.

     1. `getByID`: Retrieves a single record from an entity based on its unique identifier (ID or primary key). This action is useful when you need to display or perform operations on a specific record.
   + To add a single data action, choose **\$1 Add data action**.

1. To view or configure the new data action, see the following section, [Editing or configuring data actions](#data-entities-data-action-edit).

## Editing or configuring data actions
<a name="data-entities-data-action-edit"></a>

1. If necessary, navigate to the entity for which you want to create data actions.

1. Choose the **Data actions** tab.

1. In **Fields** configure the fields to be returned by the query. By default, all of the configured fields in the entity are selected.

   You can also add **Joins** to the data action by performing the following steps:

   1. Choose ** \$1 Add Join** to open a dialog box.

   1. In **Related entity**, select the entity you want to join with the current entity.

   1. In **Alias**, optionally enter a temporary alias name for the related entity.

   1. In **Join type**, select the desired join type.

   1. Define the join clause by selecting the fields from each entity.

   1. Choose **Add** to create the join.

   Once created, the join will be displayed in the **Joins** section, making additional fields available in the **Fields to Return** dropdown. You can add multiple joins, including chained joins across entities. You can also filter and sort by fields from joined entities.

   To delete a join, choose the trash icon next to it. This will remove any fields from that join and break any dependent joins or constraints using those fields.

1. In **Conditions**, add, edit, or remove rules that filter the output of the query. You can organize rules into groups, and you can chain together multiple rules with `AND` or `OR` statements. For more information about the operators you can use, see [Data action condition operators and examples](#data-entities-data-action-operators).

1. In **Sorting**, configure how the query results are sorted by choosing an attribute and choosing ascending or descending order. You can remove the sorting configuration by choosing the trash icon next to the sorting rule.

1. In **Transform results**, you can enter custom JavaScript to modify or format results before they are displayed or sent to automations.

1. In **Output preview**, view a preview table of the query output based on the configured fields, filters, sorting, and JavaScript.

## Data action condition operators and examples
<a name="data-entities-data-action-operators"></a>

You can use condition operators to compare a configured expression value with an entity column to return a subset of database objects. The operators that you can use depend on on the data type of the column, and the type of database that the entity is connected to, such as Amazon Redshift, Amazon Aurora, or Amazon DynamoDB.

The following condition operators can be used with all database services:
+ `=` and `!=`: Available for all data types (excluding primary key columns).
+ `<=`, `>=`, `<`, and `>=`: Available only to numerical columns.
+ `IS NULL` and `IS NOT NULL`: Used to match columns that have null or empty values. Null values are often interpreted differently in each database, however in App Studio, the `NULL` operator matches and returns records that have null values in the connected database table.

The following condition operators can only be used in entities that are connected to database services that support them:
+ `LIKE` and `NOT LIKE`(Redshift, Aurora): Used for performing pattern-based queries in the connected database. The `LIKE` operator provides flexibility in search functionality because it finds and returns records that fit the specified patterns. You define the patterns using wildcard characters that match any character or sequence of characters within the pattern. Each database management system has a unique set of wildcard characters, but the two most popular are `%` to represent any number of characters (including 0), and `_` to represent a single character.
+ `Contains` and `Not Contains` (DynamoDB): Used for performing a case-sensitive search to determine whether the given text is found within the column values. 
+ `Starts With` and `Not Starts With` (DynamoDB): Used for performing a case-sensitive search to determine whether the given text is found at the beginning of the column values. 

### Condition operator support by database
<a name="data-entities-data-action-operators-support"></a>

The following table shows which data action condition operators are supported by each database that can connect to App Studio.


|  | =, \$1=, <, >, <=, >= | LIKE, NOT LIKE | Contains, Not Contains | Starts With, Not Starts With | IS NULL, IS NOT NULL | 
| --- | --- | --- | --- | --- | --- | 
|  **DynamoDB**  |  Yes  |  No  |  Yes  |  Yes  |  Yes  | 
|  **Aurora**  |  Yes  |  Yes  |  No  |  No  |  Yes  | 
|  **Redshift**  |  Yes  |  Yes  |  No  |  No  |  Yes  | 

### Data action condition examples
<a name="data-entities-data-action-operators-examples"></a>

Consider the following database table, which includes multiple items with `name`, `city`, and `hireDate` fields.


| name | city | hireDate | 
| --- | --- | --- | 
|  Adam  |  Seattle  |  2025-03-01  | 
|  Adrienne  |  Boston  |  2025-03-05  | 
|  Bob  |  Albuquerque  |  2025-03-06  | 
|  Carlos  |  Chicago  |  2025-03-10  | 
|  Caroline  |  NULL  |  2025-03-12  | 
|  Rita  |  Miami  |  2025-03-15  | 

Now, consider creating data actions in App Studio that return the `name` field for items that match specified conditions. The following list contains condition examples and the values that the table returns for each. 

**Note**  
The examples are formatted as SQL examples– they may not appear as they do in App Studio, but are used to illustrate the behavior of the operators.
+ `WHERE name LIKE 'Adam'`: Returns `Adam`.
+ `WHERE name LIKE 'A%'`: Returns `Adam` and `Adrienne`.
+ `WHERE name NOT LIKE 'B_B'`: Returns `Adam`, `Adrienne`, `Carlos`, `Caroline`, and `Rita`.
+ `WHERE contains(name, 'ita')`: Returns `Rita`.
+ `WHERE begins_with(name, 'Car')`: Returns `Carlos` and `Caroline`.
+ `WHERE city IS NULL`: Returns `Caroline`.
+ `WHERE hireDate < "2025-03-06"`: Returns `Adam` and `Adrienne`.
+ `WHERE hireDate >= DateTime.now().toISODate()`: Note that `DateTime.now().toISODate()` returns the current date. In a scenario where the current date is 2025-03-10, the expression returns `Carlos`, `Caroline`, and `Rita`.

**Tip**  
For more information about comparing dates and times in expressions, see [Date and time](expressions.md#expressions-date-time).

## Deleting data actions
<a name="data-entities-data-action-delete"></a>

Use the following procedure to delete data actions from an App Studio entity.

1. If necessary, navigate to the entity for which you want to delete data actions.

1. Choose the **Data actions** tab.

1. For each data action you want to delete, choose the dropdown menu next to **Edit** and choose **Delete**.

1. Choose **Confirm** in the dialog box.

# Adding or deleting sample data
<a name="data-entities-edit-sample-data"></a>

You can add sample data to entities in an App Studio application. Because application's don't communicate with external services until they are published, sample data can be used to test your application and entity in preview environments.

1. If necessary, navigate to the entity you want to edit.

1. Choose the **Sample data** tab.

1. To generate sample data, choose **Generate more sample data**.

1. To delete sample data, select the checkboxes of the data you want to delete, and press the Delete or Backspace key. Choose **Save** to save the changes.

# Add or edit connected data source and map fields
<a name="data-entities-edit-connection"></a>

**Tip**  
You can press CTRL\$1Z to undo the most recent change to your entity.

1. If necessary, navigate to the entity you want to edit.

1. Choose the **Connection** tab to view or manage the connection between the entity and a data source table where data is stored when your application is published. Once a data source table is connected, you can map the entity fields to the columns of the table.

1. In **Connector**, choose the connector that contains a connection to the desired data source table. For more information about connectors, see [Connect App Studio to other services with connectors](connectors.md).

1. In **Table**, choose the table you want to use as a data source for the entity.

1. The table shows the fields of entity, and the data source column they are mapped to. Choose **Auto map** to automatically map your entity fields with your data source columns. You can also map fields manually in the table by choosing the data source column in the dropdown for each entity field.

# Deleting an entity
<a name="data-entities-delete"></a>

Use the following procedure to delete an entity from an App Studio application.

**Note**  
Deleting an entity from an App Studio app does not delete the connected data source table, including the corresponding DynamoDB table of managed entities. The data source tables will remain in the associated AWS account and will need to be deleted from the corresponding service if desired.

**To delete an entity**

1. If necessary, navigate to your application.

1. Choose the **Data** tab.

1. In the left-hand **Entities** menu, choose the ellipses menu next to the entity you want to delete and choose **Delete**.

1. Review the information in the dialog box, enter **confirm** and choose **Delete** to delete the entity.

# Managed data entities in AWS App Studio
<a name="managed-data-entities"></a>

Typically, you configure an entity in App Studio with a connection to an external database table, and you must create and map each entity field with a column in the connected database table. When you make a change to the data model, both the external database table and the entity must be updated, and the changed fields must be remapped. While this method is flexible and enables the use of different types of data sources, it takes more up-front planning and ongoing maintenance.

A *managed entity* is a type of entity for which App Studio manages the entire data storage and configuration process for you. When you create a managed entity, a corresponding DynamoDB table is created in the associated AWS account. This ensures secure and transparent data management within AWS. With a managed entity, you configure the entity's schema in App Studio, and the corresponding DynamoDB table is automatically updated as well.

## Using managed entities in multiple applications
<a name="managed-data-entities-other-applications"></a>

Once you create a managed entity in an App Studio app, that entity can be used in other App Studio apps. This is helpful for configuring data storage for apps with identical data models and schemas by providing a single underlying resource to maintain.

When using a managed entity in multiple applications, all schema updates to the corresponding DynamoDB table must be made using the original application in which the managed entity was created. Any schema changes made to the entity in other applications will not update the corresponding DynamoDB table.

## Managed entity limitations
<a name="managed-data-entities-limitations"></a>

**Primary key update restrictions**: You cannot change the entity's primary key name or type after it is created, as this is a destructive change in DynamoDB, and would result in loss of existing data.

**Renaming columns**: When you rename a column in DynamoDB, you actually create a new column while the original column remains with original data. The original data is not automatically copied to the new column or deleted from the original column. You can rename managed entity fields, known as the *system name*, but you will lose access to the original column and its data. There is no restriction with renaming the display name.

**Changing data type**: Though DynamoDB allows flexibility to modify column data types after table creation, such changes can severely impact existing data as well as query logic and accuracy. Data type changes require transforming all existing data to conform to the new format, which is complex for large, active tables. Additionally, data actions may return unexpected results until data migration is complete. You can switch data types of fields, but the existing data will not be migrated to the new data type.

**Sorting Column**: DynamoDB enables sorted data retrieval through Sort Keys. Sort Keys must be defined as part of composite Primary Keys along with the Partition Key. Limitations include mandatory Sort Key, sorting confined within one partition, and no global sorting across partitions. Careful data modeling of Sort Keys is required to avoid hot partitions. We will not be supporting Sorting for Preview milestone.

**Joins**: Joins are not supported in DynamoDB. Tables are denormalized by design to avoid expensive join operations. To model one-to-many relationships, the child table contains an attribute referencing the parent table's primary key. Multi-table data queries involve looking up items from the parent table to retrieve details. We will not be supporting native Joins for Managed entities as part of the Preview milestone. As a workaround, we will introduce an automation step that can perform a data merge of 2 entities. This will be very similar to a one level look-up. We will not be supporting Sorting for Preview milestone.

**Env Stage**: We will allow publishing to test but use the same managed store across both environments