Add VE use case docs

content/en/docs/refguide/modeling/app-explorer/app/app-settings/_index.md

@@ -204,6 +204,14 @@ This table presents the results of rounding the input to one digit with the give
 | -2.5 | -3 | -2 |
 | -5.5 | -6 | -6 |
 
+### OQL version 2 {#oql-version-2}
+
+If this option is set to **Yes**, your app will use version 2 of the OQL syntax. This setting must be enabled to use [view entities](/refguide/view-entities/). Make sure your app is ready to use the new syntax before making the switch. 
+
+For more information about the differences, see [OQL Version 2 Features](/refguide/oql-v2/).
+
+Default: *No*
+
 ### Multiple Sessions per User {#multiple-sessions}
 
 If this option is enabled, users can sign in multiple times through different clients (for example, desktop browser and tablet). Otherwise, an existing session for a user is signed out when the user signs in somewhere else.

content/en/docs/refguide/modeling/domain-model/_index.md

@@ -13,11 +13,16 @@ The **domain model** describes the information (or data) used by your app in a v
 
 The domain model is central to the architecture of your application. Each [module](/refguide/modules/) has its own domain model which describes the data used in that module. All modules in an app can use data from all the domain models within the app.
 
-A domain model consists of [entities](/refguide/entities/) with their relationships to other entities represented by [associations](/refguide/associations/). Entities can be one of three types:
+A domain model consists of [entities](/refguide/entities/) with their relationships to other entities represented by [associations](/refguide/associations/). Entities can be one of four types:
 
 * Persistable (blue) – entities which hold app information which needs to be held permanently or shared with other end-users of the app (see [Implementation of Persistable Entities](#implementation), below, for information on how these are implemented)
 * Non-persistable (orange) – entities which hold app information which is needed while the end-user is using the app but can then be thrown away
 * External (purple) – entities, described in the [Mendix Catalog](/catalog/), which contain data which belongs to another app or service and is needed while the end-user is using the app but isn't stored in the database of the app
+* View (green) – entities which are the result of a stored OQL query on persistable entities or other view entities (this feature is in beta)
+
+{{% alert color="info" %}}
+[View entities](/refguide/view-entities/) were introduced in [Studio Pro 10.19](/releasenotes/studio-pro/10.19/) as a beta feature. To enable this feature in your app, set the OQL version to version 2 by clicking **App** > **Settings** > **Runtime**.
+{{% /alert %}}
 
 You can also add [annotations](/refguide/annotations/) to your domain model to remind yourself, and other team members, how it is to be used.
 

content/en/docs/refguide/modeling/domain-model/entities/_index.md

@@ -26,20 +26,28 @@ The rows in the table are CDs. The type of the two rows is *CD* and this is the
 
 ## Types of Entities {#entity-types}
 
-The entity type defines how the data is handled and there are three types:
+{{% alert color="info" %}}
+View entities were introduced in [Studio Pro 10.19](/releasenotes/studio-pro/10.19/) as a beta feature. 
+{{% /alert %}}
+
+The entity type defines how the data is handled and there are four types:
 
 * Persistable entity
     * When an entity is declared persistable, a database table is created for the entity. These type of entities are colored *blue* in the domain model.
 * Non-persistable entity
     * Non-persistable entities are stored in the runtime memory and never get committed to the database. These type of entities are colored *orange* in the domain model.
 * External entity
     * External entities represent the link to datasets that are made available through shared data sources registered in Mendix Catalog. These type of entities are colored *purple* in the domain model. 
+* View entity (beta)
+    * View entities represent the result sets of stored OQL queries on one or more entities, similar to database viewsn, and are read-only. These entities are colored *green* in the domain model.
+
+{{< figure src="/attachments/refguide/modeling/domain-model/entities/type-of-entities.jpg" class="no-border" width=="300" >}}
 
-{{< figure src="/attachments/refguide/modeling/domain-model/entities/type-of-entities.jpg" class="no-border" >}}
+The structure of persistable, non-persistable, and view entities are defined within your app. This page describes how to add and update persistable and non-persistable entities. For more information on persistable entities, see [Persistability](/refguide/persistability/). 
 
-The structure of Persistable and Non-persistable entities are defined within your app. This page describes how to add and update Persistable and Non-persistable entities. For more information on persistable entities, see [Persistability](/refguide/persistability/).
+The structure of an external entity is defined in the source system where the underlying data (objects) is stored. For more information on external entities and how to add them to your app, see [External Entities](/refguide/external-entities/).
 
-The structure of an External entity is defined in the source system where the underlying data (objects) is stored. For more information on external entities and how to add them to your app, see [External Entities](/refguide/external-entities/).
+View entities are defined by their underlying OQL queries, which run on one or more persistable entities or other view entities. For more information, see [View Entities](/refguide/view-entities/).
 
 ## Properties {#properties}
 

content/en/docs/refguide/modeling/domain-model/entities/view-entities/_index.md

@@ -0,0 +1,56 @@
+---
+title: "View Entities"
+url: /refguide/view-entities/
+weight: 17
+#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details.
+---
+
+{{% alert color="info" %}} This feature is currently in beta. For more information, see [Beta and Experimental Releases](/releasenotes/beta-features/). {{% /alert %}}
+
+## Introduction
+
+A view entity represents the result set of a stored [OQL query](/refguide/oql/) and can be used similarly to a [persistable entity](/refguide/persistability/#persistable). This concept is similar to the function of views in general database technology. Whenever a view entity is retrieved via a page or a microflow, the corresponding OQL query executes to fetch the relevant data. Consequently, the result set of a view entity is not stored as a separate table in the database (like a materialized view). Instead, the query runs each time the view entity is accessed, dynamically retrieving the data.
+
+During modeling, changes to the underlying entities used in the OQL query affect the options available within the query. At runtime, any changes to the data in the underlying entities immediately impact the data available through the view entity.
+
+View entities can also reference other view entities, allowing for more complex structures and better data organization. 
+
+{{% alert color="info" %}} View entities are read-only. To change the resulting data of a view entity retrieval, the source data should be modified. For this purpose, you can set up a microflow to map a view object to object (or objects) of their corresponding source entity/entities and commit those. {{% /alert %}}
+
+## Enabling OQL Version 2 
+
+Your app must use OQL version 2 to use view entities. You can change this setting by clicking **App** > **Settings** > **Runtime** and setting [OQL version 2](/refguide/app-settings/#oql-version-2) to **Yes**. You can also drag a new view entity from the toolbar or **Toolbox** to the domain model, in which Studio Pro will confirm setting the OQL version to 2. 
+
+## Properties 
+
+After adding a view entity, you can specify the OQL query by double-clicking the entity to open the view entity properties dialog:
+
+{{< figure src="/attachments/refguide/modeling/domain-model/use-view-entities/customer-with-address.png" width="500" >}}
+
+### General
+
+The **General** field contains the **OQL editor** and the **Preview data** table.
+
+The **OQL editor** allows you to write the query that defines this view entity. While writing this query, the editor suggests names of the entities and attributes in your domain model, as well as allowed clauses, operators, and functions. If the query is not valid, a list of validation errors will be displayed underneath the editor with the line and column number of the place where the error was found.
+
+The resulting names and types of the attributes will be displayed as column headers in the **Preview data** table. You can view the resulting data set of your OQL query by clicking **Run Query**, which enables Studio Pro to retrieve the data from the database that is configured in your app settings. The database type of the active configuration is also listed in the header of the section. To use this functionality, your app must be running.
+
+{{% alert color="warning" %}}
+The **Preview data** table tries to retrieve the data using your OQL query from the running app. This means if you have changed your domain model since you last started the app, you can run into errors when the OQL query uses attributes or entities that do not yet exist in the version of the app that is running.
+{{% /alert %}}
+
+### Access Rules
+
+When the security level of the app is set to **Production**, the **Access rules** tab becomes available in the view entity properties.
+
+Assigning write access to an attribute allows the selected module role to edit the in-memory representation of the query result, but not the underlying source entity. The access level set on the view entity is the sole determining factor for whether a role can read or write to it. The access levels of underlying entities are not considered. This is crucial to prevent unintended exposure of data that is restricted at the source entity level.
+
+Direct writing from the view entity to its source entities is not supported, but you can set up a microflow to retrieve and update the source entities to achieve this functionality.
+
+### Documentation
+
+You can add any local information about the view entity in this tab. This is also available to other users working on the app.
+
+## Using a View Entity
+
+After creating a view entity in the domain model, it can be used in microflows and pages like any other entity. For more information, see [Use View Entities](/refguide/use-view-entities/).

content/en/docs/refguide/modeling/domain-model/entities/view-entities/abstracting-data.md

@@ -0,0 +1,54 @@
+---
+title: "Abstracting Data of Add-On Modules"
+url: /refguide/abstracting-view-entity-data/
+weight: 100
+---
+
+## Introduction
+
+Add-on modules allow you to abstract your domain model and use view entities to only show the user select details. Add-ons are commonly used for building connectors to other systems, which allows you to abstract away the caching mechanism from outside the module, so users who use the add-on do not have to consider it.
+
+## Use Case
+
+For this purpose of this use case, the following domain model is used:
+
+{{< figure src="/attachments/refguide/modeling/domain-model/view-entities/abstracting-data/domain-model.png" width="500" >}}
+
+You have a module that manages the inventory and stock of your shop products. You want to export this module so you can reuse it in different projects. To increase security, you do not want to expose the persistable entities, so you want to create view entities that represent the data you want to share outside the module. 
+
+## Create an Add-On Module
+
+1. Create a new module.
+2. Open the module **Settings** and click the **Export** tab.
+3. Select **Add-on module** as the module type, then click **OK**. 
+
+  {{< figure src="/attachments/refguide/modeling/domain-model/view-entities/abstracting-data/module-settings.png" width="500" >}}
+
+  With the add-on enabled, you should see an additional configurable property in the documents and other elements of your module called **Export level**. This is set to Hidden by default, which means users of your add-on cannot access them. 
+
+  {{< figure src="/attachments/refguide/modeling/domain-model/view-entities/abstracting-data/export-level.png" width="500" >}}
+
+## Create a View Entity
+
+You want to make an interface that shows products, where you can filter the results by category. Do this by creating a view entity what joins the Product and Category entities. Follow the steps below:
+
+1. Open your domain model and create a new view entity named *ProductCategoryVE*.
+2. Add the following query to the OQL editor:
+
+  ```sql
+  SELECT
+    p.ProductId as ProductId
+    , p.ProductName as ProductName
+    , p.QuantityPerUnit as QuantityPerUnit
+    , p.Discontinued as Discontinued
+    , c.CategoryName as Category
+    , c.CategoryId as CategoryId
+  FROM ShopAddOn.Product as p
+    JOIN p/ShopAddOn.Product_Category/ShopAddOn.Category as c
+  ```
+
+3. Double-click **ProductCategoryVE** and set the export level to **Usable**. 
+
+    {{< figure src="/attachments/refguide/modeling/domain-model/view-entities/abstracting-data/usable.png" width="500" >}}
+
+4. Export the add-on module by right-clicking it > **Export add-on module package**.

content/en/docs/refguide/modeling/domain-model/entities/view-entities/charting-with-view-entities.md

@@ -0,0 +1,76 @@
+---
+title: "Charting with View Entities"
+url: /refguide/charting-with-view-entities/
+weight: 40
+---
+
+## Introduction
+
+You can use view entities to create charts in Studio Pro. This process uses aggregated data. 
+
+## Use Case
+
+For this purpose of this use case, the following domain model is used:
+
+{{< figure src="/attachments/refguide/modeling/domain-model/view-entities/charting-with-view-entities/domain-model.png" width="500" >}}
+
+For example, you own a small business. To keep track of what is being sold, you want to visualize your sales. You want to see how much you make in sales each year, and how each product category contributes to the number. You would like your chart to look similar to the one below:
+
+{{< figure src="/attachments/refguide/modeling/domain-model/view-entities/charting-with-view-entities/chart-example.png" width="500" >}}
+
+### Create a View Entity
+
+Mendix charts do not take associations, so you usually have to take extra steps to use a non-persistable entity as a source. Using view entities is a faster and simpler way to create a chart.
+
+For the chart, you want the year on the X axis, and the total sales on the Y axis. Create a view entity that groups this data by product category. To do this, follow the steps below:
+
+1. Open your domain model and create a new view entity named *YearlySalesByCategoryVE*. 
+2. Add the following query to the OQL editor:
+
+```sql
+SELECT
+  CAST(DATEPART(YEAR, o.OrderDate) as INTEGER) as OrderYear
+  , c.CategoryId as CategoryId
+  , c.CategoryName as CategoryName
+  , SUM(ol.Quantity * ol.UnitPrice * (1 - ol.Discount)) as TotalSales
+FROM SalesDashboard."Order" as o
+  JOIN SalesDashboard.OrderLine_Order/SalesDashboard.OrderLine as ol
+  LEFT JOIN SalesDashboard.OrderLine_Product/SalesDashboard.Product as p
+  LEFT JOIN SalesDashboard.Product_Category/SalesDashboard.Category as c
+GROUP BY c.CategoryId, c.CategoryName, CAST(DATEPART(YEAR, o.OrderDate) as INTEGER)
+``` 
+
+{{% alert color="info" %}}
+
+View entities allow you to calculate and aggregate the total sales in a single line. You can also take the year by using `DateTime`. 
+{{% /alert %}}
+
+### Create the Chart
+
+Use the new view entity to create a chart. Follow the steps below:
+
+1. Create a new page or open an existing page.
+2. Navigate to the **Toolbox** and add a **Column chart** to the page. 
+3. Double-click the chart and in the **Data Source** field, click **New**. 
+4. Configure the chart by filling out the following:
+
+* Data set - **Multiple series**
+* Data source - **YearlySalesByCategoryVE**
+* Group by - **CategoryId** 
+* X axis attribute - **OrderYear**
+* Y axis attribute - **TotalSales*
+
+5. Set the series name to reflect the category name. Do the following:
+
+   * In the **Series name** field, click **Edit** and add **{1}** in the **Template** field. 
+   * In the **Parameters** field, click **New** > **Select** > **CategoryName** > **Select** > **OK**.
+
+        {{< figure src="/attachments/refguide/modeling/domain-model/view-entities/charting-with-view-entities/series-name.png" >}}
+
+ The chart should be configured as seen below: 
+
+{{< figure src="/attachments/refguide/modeling/domain-model/view-entities/charting-with-view-entities/chart-final.png" >}}
+
+6. Click **OK** to save.
+
+7. Run your app locally and you should see the chart populated with your data. 

content/en/docs/refguide/modeling/domain-model/entities/view-entities/create-pivot-table.md

@@ -0,0 +1,79 @@
+---
+title: "Create a Pivot Table with View Entities"
+url: /refguide/view-entity-pivot-table/
+weight: 70
+---
+
+## Introduction
+
+Use a view entity to create a pivot table. A pivot table is a table that contains a summary of another, more extensive table.
+
+## Use Case
+
+For this purpose of this use case, the following domain model is used:
+
+{{< figure src="/attachments/refguide/modeling/domain-model/view-entities/pivot-table-view-entities/domain-model.png" >}}
+
+In this example, you run a business and this is your shop's domain model. It includes:
+
+* A *Product* entity that stores information of all the products sold
+* An *Order* entity, which holds information about individual orders
+* An *OrderLine* entity, which is a single item in an order
+
+You want to analyze seasonal sales volumes, which is how much your business makes from sales in each quarter per year. You want your table to resemble the following:
+
+| Year | TotalSales_Q1 | TotalSales_Q2 | TotalSales_Q3 | TotalSales_Q4| 
+|------|---------------|---------------|---------------|---------------|
+| 1996 | $ …           | $ …           |  $ …          |  $ …          |   
+| 1997 | $ …           | $ …           |  $ …          |  $ …          | 
+| 1998 | $ …           | $ …           |  $ …          |  $ …          | 
+| ...  | …             | …             |  …            |  …            |
+
+## Create a Pivot Table
+
+Create a view entity that shows each order together with its total value, calculated from the *OrderLine* entity. To do this, follow the steps below:
+
+1. Open your domain model and add a new view entity. Name this entity *OrderVE*.
+2. Add the following query to the OQL editor:
+
+  ```sql
+  SELECT
+    o.OrderId as OrderId
+    , CAST(DATEPART(QUARTER, o.OrderDate) as INTEGER) as OrderQuarter
+    , CAST(DATEPART(YEAR, o.OrderDate) as INTEGER) as OrderYear
+    , o.RequiredDate as RequiredDate
+    , o.ShippedDate as ShippedDate
+    , SUM(ol.UnitPrice * ol.Quantity * (1 - ol.Discount)) as TotalOrderValue
+    , SUM(ol.Quantity) as TotalProductCount
+    , COUNT(*) as UniqueProductCount
+  FROM Shop."Order" as o
+    JOIN o/Shop.OrderLine_Order/Shop.OrderLine as ol
+  GROUP BY o.OrderId, o.OrderDate, o.RequiredDate, o.ShippedDate
+  ```
+
+{{% alert color="info" %}}
+
+With view entities, you can take the relevant component of `DateTime` as a column using the `DATEPART` function. For more information, see the [`DATEPART` and `DATEDIFF`](/refguide/oql-v2/#date-validations) section of *OQL Version 2 Features*.
+
+{{% /alert %}}
+
+3. Add another view entity to the domain model and name it *OrderQuarterlyPivotVE*. This entity will show a table, similar to the format above.
+4. Add the following query to the OQL editor:
+
+  ```sql
+  SELECT
+      o.OrderYear as OrderYear,
+      SUM(CASE WHEN o.OrderQuarter = 1 THEN o.TotalOrderValue ELSE 0 END) as TotalSales_Q1,
+      SUM(CASE WHEN o.OrderQuarter = 2 THEN o.TotalOrderValue ELSE 0 END) as TotalSales_Q2,
+      SUM(CASE WHEN o.OrderQuarter = 3 THEN o.TotalOrderValue ELSE 0 END) as TotalSales_Q3,
+      SUM(CASE WHEN o.OrderQuarter = 4 THEN o.TotalOrderValue ELSE 0 END) as TotalSales_Q4
+  FROM Shop.OrderVE o
+  GROUP BY o.OrderYear
+```
+
+5. Click **Run Query** to preview the data.
+
+  {{< figure src="/attachments/refguide/modeling/domain-model/view-entities/pivot-table-view-entities/orderpivotve.png" >}}
+
+6. Click **OK** save. 
+7. Create a page that shows the pivot table by right-clicking the new entity > **Generate overview pages**.