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 reestablish 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 domain.

semanticEntity general syntax

The semanticEntity complex type defines an entity and all its attributes. Its syntax is:
<semanticEntity key="?" displayName="?" isActive="?">
   <definition>?</definition>
   <description>?</description>
   <attributes>
      <semanticAttribute name="?" displayName="?" datatype="?" 
         isDimension="?" isKeyColumn="?" description="?">
         <property key="?">?</property>
      </semanticAttribute>
   </attributes>
   <metrics>
      <metric name="?" displayName="?" datatype="?" description="?">
         <definition>?</definition>
         <property key="?">?</ns:property>
      </metric>
   </metrics>
   <groups>
      <group key="?" displayName="?">
         <semanticAttributeKey name="?"/>
         <property key="?">?</property>
      </group>
   </groups>
   <property key="?">?</property>
</semanticEntity>
The meanings of its elements and attributes is as follows:
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 name must be in 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.
isActive Required element. A boolean value (true or false) that specifies whether this entity is active or inactive. An Inactive entity's definition is not evaluated as part of a put operation or as an EQL query, and that definition is not concatenated onto queries. An inactive state thus this allows you to save entities with invalid or incomplete EQL definitions (which you will later correct) or to save the entity for later use (at which time you will activate it). An entity must be active if other EQL queries refer to it. When saving an entity, isActive must be explicitly set. Note that the Base entity is always active.
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 statement should match the name of the entity.

For example, the DEFINE statement for the Sales entity might be:
<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. Provides descriptive text about the entity.
attributes Optional element. Represents a list of attributes in an entity. The attributes element may contain zero or more semanticAttribute elements. See below for details.
metrics Optional element. Provides a list of one or more suggested metric elements. The metrics element may contain zero or more metric elements. See below for details.
groups Optional element. Lets you create one or more entity attribute groups. See below for details.
property Optional element (note that this is the property element for the entire semanticEntity). Lets you specify a string metadata global property for the entire entity. The key name must be in the NCName format.

attributes element

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. Each semanticAttribute element defines a member attribute of the entity.

The syntax of the semanticAttribute element is:
<semanticAttribute name="?" displayName="?" datatype="?" 
   isDimension="?" isKeyColumn="?" description="?">
   <property key="?">?</property>
</semanticAttribute>
For each semanticAttribute element, specify the following:
  • name specifies a unique identifier for the attribute. The identifier must follow the NCName format.
  • displayName is the name of the entity attribute in an easy-to-understand format. The display name can use a non-NCName format.
  • datatype specifies a valid data type, such as mdex:string. Valid types are listed in the mdex.xsd.
  • isDimension is 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 a hierarchy, and are candidates for GROUP BY statements in EQL.
  • isKeyColumn is set to true if this attribute is part of the entity's composite key. The composite key on an entity is the set of entity attributes with isKeyColumn set to true. The default is false.
  • description provides a brief description of the attribute.
  • property sets the name (key) and value of the string metadata for this attribute. The key name must be in the NCName format.
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" isKeyColumn="true" description="sales info">
     <property key="locale">EN</property>
  </semanticAttribute>
  ...
</attributes>

metrics element

The metrics element can contain one or more metric elements. The syntax of the metric element is:
<metrics>
  <metric name="?" displayName="?" datatype="?" description="?">
     <definition>?</definition>
     <property key="?">?</property>
  </metric>
</metrics>
Specify these attributes for the metric element:
  • name specifies a unique identifier for the metric. The identifier must follow the NCName format.
  • displayName is the name of the metric in an easy-to-understand format. The display name can use a non-NCName format.
  • datatype specifies a valid data type, such as mdex:double.
  • description provides a brief description of the metric.
  • definition is an EQL statement defining the metric. The definition element must contain an arithmetic formula in EQL used for aggregation when querying against the entity's attributes.
  • property sets the name (key) and value of the string metadata for this metric. The key name must be in the NCName format.

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>
    <property key="currency">$</property>
  </metric>
</metrics>

groups element

An entity attribute group (also called a view attribute group) consists of a set of entity attributes (which have been set via semanticAttribute elements).

The entity attribute group can also have a set of properties (key-value pairs) that are associated with the group. These properties let you provide metadata for the group, which can then be used by your front-end application (such as Studio). For example, you can use this metadata for order control (i.e., specifying which attribute will be used to sort the results).

Each group is defined by a group element and consists of attributes from this entity. The syntax of the metric element is:
<groups>
  <group key="?" displayName="?">
     <semanticAttributeKey name="?">
     <property key="?">?</property>
  </group>
</groups>
The meanings of the group attributes are:
  • group key is a unique identifier for the entity attribute group. The identifier does not have to follow the NCName format.
  • displayName lets you specify a more user-friendly name for the group.
  • semanticAttributeKey (via its name attribute) specifies which entity attribute is added to the group. Thus, the name attribute of semanticAttributeKey corresponds to the name attribute of the semanticAttribute element described above.
  • property sets the name (key) and value of the string metadata for this group. The key name must be in the NCName format.
This example creates an entity named Product, which has an entity attribute group named ProdDescription:
<semanticEntity key="Product" displayName="Product" isActive = "true">
   <definition>
    DEFINE Product AS SELECT productId AS productId, description AS description, price AS price
   </definition>
   <attributes>
      <semanticAttribute name="productId" datatype="mdex:string" 
         isDimension="true" isKeyColumn="true">
      </semanticAttribute>
      <semanticAttribute name="description" datatype="mdex:string" 
         isDimension="true" isKeyColumn="false">
      </semanticAttribute>
      <semanticAttribute name="price" datatype="mdex:double" 
         isDimension="true" isKeyColumn="false">
         <property key="currency">$</property>
      </semanticAttribute>
   </attributes>
   <metrics/>
   <groups>
      <group key="ProdDescription" displayName="ProductId and Description Group">
         <semanticAttributeKey name="productId"/>
         <semanticAttributeKey name="description"/>
         <property key="sortBy">productId</property>
      </group>
   </groups>
   <property key="sales_area">North America</property>
</semanticEntity>

The group has two entity attributes as members ("productId" and "description"). It also has a metadata property (named "sortBy") whose value can be used to sort the results by the "productId" attribute.

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 Transactions" isActive="true">
<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>Sales transaction information</description>
<attributes>
  <semanticAttribute name="SalesAmount" displayName="Sales Amount" 
      datatype="mdex:double" isDimension="false" isKeyColumn="true">
      <property key="locale">EN</property>
  </semanticAttribute>
  <semanticAttribute name="ProductLine" displayName="Product Line" 
      datatype="mdex:string" isDimension="true" isKeyColumn="false">
  </semanticAttribute>
  <semanticAttribute name="SalesTerritoryCountry" displayName="Sales Territory Country"
      datatype="mdex:string" isDimension="true" isKeyColumn="false">
  </semanticAttribute>
  <semanticAttribute name="FiscalYear" displayName="Year" datatype="mdex:int"
      isDimension="true" isKeyColumn="false">
  </semanticAttribute>
  <semanticAttribute name="SaleOrderNumber" displayName="Sale Order Number" 
      datatype="mdex:string" isDimension="false" isKeyColumn="false">
  </semanticAttribute>
</attributes>
<metrics>
  <metric name="TotalSales" displayName="Total Sale" datatype="mdex:double">
    <definition>sum(SalesAmount)</definition>
    <property key="currency">$</property>
  </metric>
  <metric name="AvgSales" displayName="Average Sale" datatype="mdex:double">
    <definition>avg(SalesAmount)</definition>
  </metric>
</metrics>
</groups>
<property key="SalesArea">North America</property>
</semanticEntity>

Notes about the Base entity

Once records are loaded into the Endeca data domain, one single base entity record is created for each of the attributes in the data domain. 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.