semanticEntity general syntax

The semanticEntity complex type defines an entity and all its attributes.

The semanticEntity 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. 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. 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. A boolean value that specifies whether this entity is active (`true`) or inactive (`false`). 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 status 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.
`definition`	Required. 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 definition can refer to a named state. The definition must include a DEFINE statement that matches the name (`key` attribute) 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. Provides descriptive text about the entity.
`attributes`	Optional. Represents a list of attributes in an entity. The `attributes` element may contain zero or more `semanticAttribute` elements. See below for details.
`metrics`	Optional. 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. Lets you create one or more entity attribute groups. See below for details.
`property`	Optional. 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="SalesArea">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>

Cache re-validation

Entities are re-validated during every cache refill. Any EQL query that uses an invalid entity will generate an error and the entity's isValid flag will be set to false. Note that Endeca Server does validation only on the Definition and the Metrics provided.