Sample entity requests

This topic includes examples of requests for listing, adding, deleting, and validating entities.

Listing entities

The following example of the request lists all entities that are present in the corpus:

<listEntities>
   <language>en</language>
</listEntities>

The response to this request returns a list of entities that are already added. The following listEntitiesResponse shows one sample entity:

<ns3:listEntitiesResponse xmlns:ns2="http://www.endeca.com/MDEX/eql_parser/types" 
                          xmlns:ns3="http://www.endeca.com/endeca-server/sconfig/3/0">
   <ns3:validatedSemanticEntity isValid="true" key="SalesTrans" displayName="Sales Transaction" isActive="true">
      <ns3:definition>DEFINE SalesTrans AS
      SELECT FactSales_SalesAmount AS SalesAmount,
      DimReseller_ProductLine AS ProductLine</ns3:definition>
      <ns3:description>Sales transaction information</ns3:description>
      <ns3:attributes>
         <ns3:semanticAttribute name="SalesAmount" displayName="Sales Amount" datatype="mdex:double" 
                 isDimension="false" isKeyColumn="true" description="Amounts">
            <ns3:property key="locale">EN</ns3:property>
         </ns3:semanticAttribute>
         <ns3:semanticAttribute name="ProductLine" displayName="Product Line" datatype="mdex:string" 
                 isDimension="true" isKeyColumn="false" description="prod"/>
         <ns3:semanticAttribute name="SaleOrderNumber" displayName="Sale Number" datatype="mdex:string" 
                 isDimension="false" isKeyColumn="false" description="Orders"/>
      </ns3:attributes>
      <ns3:metrics>
         <ns3:metric name="TotalSales" displayName="Total Sales" datatype="mdex:double" description="Totals">
            <ns3:definition>sum(SalesAmount)</ns3:definition>
            <ns3:property key="currency">$</ns3:property>
         </ns3:metric>
         <ns3:metric name="AvgSales" displayName="Average Sales" datatype="mdex:double" description="Averages">
            <ns3:definition>avg(SalesAmount)</ns3:definition>
         </ns3:metric>
      </ns3:metrics>
      <ns3:groups/>
      <ns3:property key="SalesArea">North America</ns3:property>
      <ns3:parsedDefinition>
         <ns2:statements returnTable="false" statementKey="SalesTrans">
            <ns2:selects attributeKey="SalesAmount">
               <ns2:expression xsi:type="ns2:AttributeRefExpression" attributeKey="FactSales_SalesAmount" 
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
            </ns2:selects>
            <ns2:selects attributeKey="ProductLine">
               <ns2:expression xsi:type="ns2:AttributeRefExpression" attributeKey="DimReseller_ProductLine" 
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
            </ns2:selects>
         </ns2:statements>
      </ns3:parsedDefinition>
   </ns3:validatedSemanticEntity>
</ns3:listEntitiesResponse>

In the validatedSemanticEntity element, the isValid attribute specifies whether the entity has been successfully validated.

If the entity has a dependency, the dependentEntities element will list that dependency.

Validating an entity

Before adding an entity, it is useful to validate the syntax of the EQL statements in the entity definition.

To validate an entity, issue a request either with validateEntity (which validates a single entity) or with validateEntities (which can validate multiple entities). With both operations, you specify the entities inside the semanticEntity elements. Note that the entity is validated regardless of whether it is active or inactive.

The following abbreviated example illustrates the validateEntity request:

<validateEntity>
   <semanticEntity key="Sales" displayName="Sales Data" isActive="true">
   ...
   </semanticEntity>
</validateEntity>

If the request validates successfully, validateEntityResponse does not contain errors. Note that if the entity validation fails, the isValid flag on the entity record is set to false (regardless of its previous setting).

Adding an entity

You can add one entity using a putEntity operation, or add multiple entities using putEntities.

In this abbreviated example, a putEntity operation is used in a request to add one entity, Sales, with two metrics, TotalSales and AvgSales:

<putEntity xmlns="http://www.endeca.com/endeca-server/sconfig/3/0">
<semanticEntity key="Sales" displayName="Sales Data" 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 territorial information</description>
<attributes>
	<semanticAttribute name="SalesAmount" displayName="Sales Amount" datatype="mdex:double" 
   isDimension="false" isKeyColumn="true"/>
	<semanticAttribute name="ProductLine" displayName="Product Line" datatype="mdex:string" 
 isDimension="true" isKeyColumn="true"/>
	<semanticAttribute name="SalesTerritoryCountry" displayName="Sales Territory Country" 
 datatype="mdex:string" isDimension="true" isKeyColumn="false"/>
	<semanticAttribute name="FiscalYear" displayName="Year" datatype="mdex:int" 
 isDimension="true" isKeyColumn="false"/>
	<semanticAttribute name="SaleOrderNumber" displayName="Sale Order Number" 
 datatype="mdex:string" isDimension="false" isKeyColumn="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>
<groups/
</semanticEntity>
</putEntity>

The abbreviated example response from the Entity and Collection Configuration Web Service informs you how many entities were created or replaced:

<putEntityResponse xmlns="http://www.endeca.com/endeca-server/sconfig/3/0">
  <entityAdditionInformation numEntitiesAdded="1" numEntitiesReplaced="0"/>
</putEntityResponse>

Deleting an entity

To delete individual entities (one or more), use the deleteEntities operation, specifying keys for the entities to be deleted, as in this example:

<deleteEntities xmlns="http://www.endeca.com/endeca-server/sconfig/3/0">
   <semanticEntityKey key="SalesInfo"/>
</deleteEntities>

The response indicates the number of entities deleted:

<deleteEntitiesResponse xmlns="http://www.endeca.com/endeca-server/sconfig/3/0">
   <numEntitiesDeleted>1</numEntitiesDeleted>
</deleteEntitiesResponse>