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.
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 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>
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. |
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.
<semanticAttribute name="?" displayName="?" datatype="?" isDimension="?" isKeyColumn="?" description="?"> <property key="?">?</property> </semanticAttribute>
<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> <metric name="?" displayName="?" datatype="?" description="?"> <definition>?</definition> <property key="?">?</property> </metric> </metrics>
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.
<metrics> <metric name="TotalSales" displayName="Total Sale" datatype="mdex:double"> <definition>sum(SalesAmount)</definition> <property key="currency">$</property> </metric> </metrics>
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).
<groups> <group key="?" displayName="?"> <semanticAttributeKey name="?"> <property key="?">?</property> </group> </groups>
<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.
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.
<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>
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.