About entities

Entities provide you with intuitive, conceptual views of various categories in your data. They reflect the relational complexity between categories of data that is present in the Oracle Endeca Server's flat data model, but that is not immediately visible.

An entity (or view, in Studio) represents a logical set of records that are derived from the physical records by aliasing, filtering, and grouping. An entity has its own metadata, which include names, types, and display names of the attributes, and the names and definitions of metrics.

Note: In Studio, entities are known as views. The Entity Configuration Web Service interface is used by Studio to create and manage views. For information on creating and managing views in Studio, see the Oracle Endeca Information Discovery Studio User's Guide.

When you create entities on top of various data categories, you map business concepts to complex data structures, based on how you would like to analyze data. Entities re-establish the relationship between categories of data once all data is loaded into the Oracle Endeca Server.

You define entities by specifying metadata on them, such as their metrics. This allows you, as the data architect, to inform the business analyst about the relationship between different categories in your data, and to suggest metrics that can be requested on the entities. For example, metrics can provide information on which entities are useful to be grouped by, or to be aggregated upon.

Once you create entities, they serve as (aggregated) logical views of your data, allowing business analysts to run analytic queries on them.

You create entities using the putEntity or putEntities operations of the Entity Configuration Web Service. You can only create entities if the underlying attributes are already defined in your schema and exist in your data store.

The semanticEntity complex type of the Entity Configuration Web Service defines an entity and all its attributes. The semanticEntity type includes the following elements and attributes:

Name of element or attribute	Description
`key`	Required attribute. A unique identifier for the entity, which you provide when creating an entity. For example, you may create an entity with the key `Sales`. The key must be based on the NCName format.
`displayName`	Optional attribute. Defines the display name which may be used by the front-end application such as Studio. The display name can use a non-NCName format.
`definition`	Required element. An EQL statement defining the entity. This EQL statement must create (or filter out) a virtual collection of records, based on the EQL expressions included in it. The EQL definition of an entity consists of one or more DEFINE statements separated by semicolons. The name of any of the DEFINE statements should match the name of the entity. For example: <definition>DEFINE Sales AS SELECT FactSales_SalesAmount AS SalesAmount, DimReseller_ProductLine AS ProductLine, DimSalesTerritory_SalesTerritoryCountry AS SalesTerritoryCountry, DimDate_FiscalYear AS FiscalYear, FactSales_SalesOrderNumber AS SaleOrderNumber </definition>
`description`	Optional attribute. Describes an entity.
`attributes`	Optional element. Represents a list of attributes in an entity. The `attributes` element may contain one or more `semanticAttribute` elements. Each attribute in an entity must correspond to an attribute specified in the EQL statement included in `definition`. For each `semanticAttribute` element, specify the following attributes: `name` specifies a unique identifier for the attribute. The identifier must follow the NCName format. `datatype` specifies a valid data type, such as `mdex:string`. Valid types are listed in the `mdex.xsd`. `displayName` is the name of the entity attribute in an easy-to-understand format. The display name can use a non-NCName format. The `isDimension` attribute should be set to `true` on attributes on which it is useful to do a GROUP BY. For example, attributes such as Size, Region, or Category should have `isDimension="true"`, indicating that they are managed attributes containing hierarchy, and are candidates for GROUP BY statements in EQL. This abbreviated example shows one of the several attributes based on which a `Sales` entity is created: <attributes><semanticAttribute name="SalesAmount" displayName="Sales Amount" datatype="mdex:double" isDimension="false"/> ...</attributes>
`metrics`	Optional element. Provides a list of one or more suggested metric elements. You create each `metric` by giving it a name and defining its EQL statement in the `definition` element. The `definition` element must contain an arithmetic formula in EQL used for aggregation when querying against the entity's attributes. Each metric must contain at least one aggregation function, such as `SUM(X)`, or `AVG(Y)`, where `X` and `Y` are attributes defined for the entity. For example, an entity may include the attribute `SalesAmount`, and a metric `TotalSales`, defined as the sum of the values of the `SalesAmount` attribute: <metrics><metric name="TotalSales" displayName="Total Sale" datatype="mdex:double"> <definition>sum(SalesAmount)</definition></metric><metric name="AvgSales" displayName="Average Sale" datatype="mdex:double"><definition>avg(SalesAmount)</definition></metric></metrics>

An example of an entity

To put the previously described portions of an entity definition together, consider the following use case.

When you load a list of sales transactions, you also are loading information about customers, products, and suppliers. You can create entities for each of them. Consider creating a Sales entity as a virtual set of records derived from the following attributes: SalesAmount, ProductLine, and FiscalYear.

When you define the Sales entity, you also provide metrics for it, allowing business analysts to issue queries in EQL against this entity. These metrics could be the TotalSales, defined as a sum of SalesAmount, or the AvgSales, defined as an average of SalesAmount.

This example illustrates a Sales entity defined on top of several entity attributes and listing two metrics that could be used in subsequent analytic queries against this entity:

<semanticEntity key="Sales" displayName="Sales">
  <definition>
   DEFINE Sales AS 
   SELECT FactSales_SalesAmount AS SalesAmount, 
   DimReseller_ProductLine AS ProductLine, 
   DimSalesTerritory_SalesTerritoryCountry AS SalesTerritoryCountry, 
   DimDate_FiscalYear AS FiscalYear, 
   FactSales_SalesOrderNumber AS SaleOrderNumber
  </definition>
  <attributes>
	<semanticAttribute name="SalesAmount" displayName="Sales Amount" datatype="mdex:double" 
isDimension="false"/>
<semanticAttribute name="ProductLine" displayName="Product Line" datatype="mdex:string" 
isDimension="true"/>
<semanticAttribute name="SalesTerritoryCountry" displayName="Sales Territory Country" 
datatype="mdex:string" isDimension="true"/>
<semanticAttribute name="FiscalYear" displayName="Year" datatype="mdex:int" 
isDimension="true"/>
<semanticAttribute name="SaleOrderNumber" displayName="Sale Order Number" 
datatype="mdex:string" isDimension="false"/>
</attributes>
<metrics>
<metric name="TotalSales" displayName="Total Sale" datatype="mdex:double">
<definition>sum(SalesAmount)</definition>
</metric>
<metric name="AvgSales" displayName="Average Sale" datatype="mdex:double">
<definition>avg(SalesAmount)</definition>
  </metric>
 </metrics>
</semanticEntity>

Notes about the base entity

Once records are loaded into the Endeca data store, one single base entity record is created for each of the attributes in the data store. The base entity record is created based on the PDRs defining each of the attributes on your physical records. The base entity provides a convenient way for you to create your own custom entities.

Note: Because the base entity represents records derived from actual attributes that exist in the system, you cannot create, modify, or delete the base entity.