Filtering the Associated Objects That Are Returned by a GetMetadata Request

Introduction to the Search Attribute

The GetMetadata method supports a Search attribute on association names to filter the associated objects that it returns. The Search attribute can be specified in both the property string in the <METADATA> element and in a template in the <TEMPLATES> element. The Search attribute enables you to retrieve only associated objects that are of a specified metadata type, or are of a specified metadata type and meet specified criteria:

The Search attribute is specified in the association name element of a metadata property string in one of the following forms:

<AssociationName search="Object"/>

<AssociationName search="Object[Criteria]"/>

Object can be an * (asterisk) or a SAS Metadata Model metadata type that is valid for the specified association name.

Specifying an * instructs the SAS Metadata Server to get objects of all metadata types that are valid for AssociationName.

Specifying a metadata type instructs the SAS Metadata Server to get only associated objects of the specified metadata type.
[Criteria] is a search specification that conforms to the syntax documented for the <XMLSELECT> option. For information about the syntax, see <XMLSELECT search="criteria"/> Syntax. When search criteria are specified, GetMetadata retrieves only associated objects indicated by Object that also meet the specified criteria.

Example of Specifying Search Criteria in the <METADATA> Element

When specified in the <METADATA> element, the search criteria string looks like one of the following:

<Metadata>
  <MetadataType>
    <AssociationName search="Object"/>
  </MetadataType>
</Metadata>

<Metadata>
  <MetadataType>
    <AssociationName search="Object[AttributeCriteria]"/>
  </MetadataType>
</Metadata>

To understand the filtering that occurs, consider the following requests. In the first request, the <METADATA> element specifies to get the Document metadata object that has Id="A52WE4LI.AT0000RZ" and all objects that are associated with it through the Objects association name (all metadata types):

<GetMetadata>
   <Metadata>
     <Document Id="A52WE4LI.AT0000RZ">
      <Objects search="*"/>
     </Document>
   </Metadata>
   <NS>SAS</NS>
   <Flags>0</Flags>
   <Options/>
</GetMetadata>

The request is the same as specifying the association name without search criteria:

<GetMetadata>
   <Metadata>
     <Document Id="A52WE4LI.AT0000RZ">
      <Objects/>
     </Document>
   </Metadata>
   <NS>SAS</NS>
   <Flags>0</Flags>
   <Options/>
</GetMetadata>

In both requests, the GetMetadata method specifies to get requested attributes for the specified Document object (Id only in this case) and all objects that are associated with it through the Objects association name. Here is an example of the output from the requests:

<!-- Using the GETMETADATA method. -->

<Document Id="A52WE4LI.AT0000RZ">
  <Objects>
   <PhysicalTable Id="A52WE4LI.B60000RT" Name="Table1" Desc="Sales table"/>
   <PhysicalTable Id="A52WE4LI.B60000RU" Name="Table2" Desc="Human Resources table"/>
   <ExternalTable Id="A52WE4LI.BA000001" Name="Oracle Sales" Desc="Sales information 
from  Oracle database"/>
   <ExternalTable Id="A52WE4LI.BA000002" Name="Oracle HR" Desc="Human Resources
 information from Oracle database"/>
  </Objects>
</Document>

The specified Document object has four objects associated with it through the Objects association name: two PhysicalTable objects and two ExternalTable objects. By default, the GetMetadata method returns the Id, Name and Desc values of the associated objects.

In this second request, a search string is used in the Objects association name of the <METADATA> element to filter the request to get only PhysicalTable objects that are associated with the specified Document object through the Objects association:

<GetMetadata>
   <Metadata>
     <Document Id="A52WE4LI.AT0000RZ">
      <Objects search="PhysicalTable"/>
     </Document>
   </Metadata>
   <NS>SAS</NS>
   <Flags>0</Flags>
   <Options/>
</GetMetadata>

Here is an example of the output from the request:

<!-- Using the GETMETADATA method. -->

<Document Id="A52WE4LI.AT0000RZ">
 <Objects>
   <PhysicalTable Id="A52WE4LI.B60000RT" Name="Table1" Desc="Sales table"/>
   <PhysicalTable Id="A52WE4LI.B60000RU" Name="Table2" Desc="Human Resources table"/>
 </Objects>
</Document>

The ExternalTable objects that were returned in the first example are excluded from the output of this example.

In this third request, attribute criteria are added to the search criteria string in the <METADATA> element to further filter the request. The request specifies to get PhysicalTable objects that are associated with the specified Document object through the Objects association whose Desc attribute value has the word Sales in it:

<GetMetadata>
   <Metadata>
    <Document Id="A52WE4LI.AT0000RZ">
      <Objects search="PhysicalTable[@Desc ? 'Sales']"/>       
    </Document>    
   </Metadata>   
   <NS>SAS</NS>
   <Flags>0</Flags>
   <Options/>
</GetMetadata>

Here is an example of the output from the request:

<!-- Using the GETMETADATA method. -->

<Document Id="A52WE4LI.AT0000RZ">
 <Objects>
   <PhysicalTable Id="A52WE4LI.B60000RT" Name="Table1" Desc="Sales table"/>
 </Objects>
</Document>

Example of Specifying Search Criteria in the <TEMPLATES> Element

Templates are submitted to the GetMetadata method in the OPTIONS parameter in a <TEMPLATES> element. To submit a template, you must set the OMI_TEMPLATE (4) flag.

To understand how search criteria are processed in a template, consider the following request.

<GetMetadata>
   <Metadata>
     <Document Id="A52WE4LI.AT0000RZ"/>
   </Metadata>
   <NS>SAS</NS>
   <!-- OMI_TEMPLATE -->
   <Flags>4</Flags>
   <Options>
     <Templates>
       <Document MetadataCreated="" MetadataUpdated="">  
         <Objects search="ExternalTable[@Desc= ?  'Human Resources']"/> 
       </Document>
    </Templates>
 </Options>  
</GetMetadata>

In the method call, note the following:

The <METADATA> element specifies to get the Document metadata object that has Id="A52WE4LI.AT0000RZ".
The OMI_TEMPLATE flag (4) instructs the SAS Metadata Server to check for a template in the <OPTIONS> element.
The <TEMPLATES> element includes a template for the Document metadata type that specifies to get the Name, Desc, MetadataCreated and MetadataUpdated attributes of the Document object, and any ExternalTable objects that are associated to the specified Document through the Objects association and whose Desc attribute has the words Human Resources in it.

Here is an example of the output from the request:

<!-- Using the GETMETADATA method. -->

<Document Id="A52WE4LI.AT0000RZ" MetadataCreated="22Aug2008:14:52:24"  
MetadataUpdated="22Aug2008: 16:08:45">
  <Objects>
      <ExternalTable Id="A52WE4LI.BA000002"/>
   </Objects>
</Document>

Note: When the OMI_TEMPLATE flag is set, GetMetadata gets only the Id attribute for associated objects. If you want to get additional attributes, you need to specify them in another template, or set a flag such as OMI_ALL_SIMPLE (8), which gets all attributes for the specified object and all associated objects.

Example of Specifying Search Criteria in Both Elements

When search criteria are specified in both the <METADATA> and <TEMPLATES> elements, the following rules apply:

If the search criteria strings specify different association names, both are applied.
If the search criteria strings specify the same association name, the search criteria string in the <TEMPLATES> element is ignored.

For example, consider this request:

<GetMetadata>
   <Metadata>
     <Document Id="A52WE4LI.AT0000RZ">
      <Objects search="ExternalTable[@Desc ? 'Sales']"/>
     </Document>
   </Metadata>
   <NS>SAS</NS>
   <!-- OMI_TEMPLATE flag -->
   <Flags>12</Flags>
   <Options>
    <Templates>
     <Document>
      <Objects search="PhysicalTable[@Desc ? 'Sales']"/>
     </Document>
   </Templates>
 </Options>
</GetMetadata>

Before any metadata is retrieved, the properties in the <METADATA> and <TEMPLATES> elements are merged into one list that is used to get the metadata objects. The properties in the <METADATA> element take priority over properties in the <TEMPLATES> element. As a result, additional properties that are specified in the template are added to the list. However, any properties that are duplicated in the template are ignored.

In this example, although the search criteria in the <METADATA> element and in the <TEMPLATES> element specify different metadata types, they specify the same association name (Objects), so the search criteria in the <TEMPLATES> element is ignored. Because the OMI_TEMPLATE flag is set, the SAS Metadata Server returns only the Id value of the specified object and its associated objects.

Now, consider the following request:

<GetMetadata>
   <Metadata>
     <Document Id="A52WE4LI.AT0000RZ">
         <ResponsibleParties  search="ResponsibleParty[@Name  ? 'Writer']"/>
     </Document>
   </Metadata>
   <NS>SAS</NS>
   <!-- OMI_TEMPLATE + OMI_ALL_SIMPLE + OMI_SUCCINCT flags -->
   <Flags>2060</Flags>
   <Options>
     <Templates>
      <ResponsibleParty>
          <Persons search="*"/>
      </ResponsibleParty>
   </Templates>
 </Options>
</GetMetadata>

In this request, note the following:

The <METADATA> element specifies to get Document A52WE4LI.AT0000RZ and a search criteria string on the ResponsibleParties association. The search criteria string specifies to get ResponsibleParty objects that are associated to the specified Document object. The search criteria further specify to get only ResponsibleParty objects that have the word Writer in their Name attribute.
The sum of the OMI_TEMPLATE (4) + OMI_ALL_SIMPLE (8) + OMI_SUCCINCT (2048) flags instructs the SAS Metadata Server to check for a <TEMPLATES> element in the <OPTIONS> element, get all attributes for the specified object and associated objects, and to omit attributes that do not contain a value or that contain a null value from the results.
The <OPTIONS> element includes a template in the <TEMPLATES> element that specifies to get objects associated with the returned ResponsibleParty objects through the Persons association.

Here is an example of the output returned by the SAS Metadata Server:

 <!-- Using the GETMETADATA method. -->

<Document Id="A52WE4LI.AT0000RZ" Name="AugustPerformance" Desc="Summary report of 
NW Region production activity, HR expense, and sales" MetadataCreated=
"22Aug2008:14:52:24" MetadataUpdated="22Aug2008: 16:08:45" PublicType="Document" 
URI="Text" UsageVersion="1000000">
  <ResponsibleParties search="ResponsibleParty[@Name  ? 'Writer']">
   <ResponsibleParty Id="A52WE4LI.BN000003"  Name="Technical Writer" MetadataCreated=
"22Aug2008:14:52:24" MetadataUpdated="22Aug2008: 16:08:45" UsageVersion="1000000" >
     <Persons SEARCH="*">
      <Person Id="A52WE4LI.AR0002BE" Desc="Primary Writer" MetadataCreated=
"22Aug2008:14:52:24"  MetadataUpdated="22Aug2008: 16:08:45" Name="Melissa Mark" 
PublicType="User" UsageVersion="1000000" />
     </Persons>
  </ResponsibleParty>
 </ResponsibleParties>
</Document>

The results show that one ResponsibleParty object is associated with Document A52WE4LI.AT0000RZ through the ResponsibleParties association that has the word Writer in its Name attribute. In turn, this ResponsibleParty object has one object associated with it through the Persons association that describes a person named Melissa Mark.