Filtering a GetMetadataObjects Request

Understanding an Association Path

To understand how an association path is evaluated, we must consider each association path level that is specified. The AssociationPathLevel specifies an association and an associated object that is evaluated, as well as optional attribute criteria that the associated objects must meet to be selected.

The first AssociationPathLevel in AssociationPath sets the context for the request. It specifies the association that an object must have defined to be evaluated. When considered in the context of Object, the syntax of the first AssociationPathLevel looks like the following:

Object[AssociationName/AssociatedObject[AttributeCriteria]]

Object can be the same metadata type name that is specified in the GetMetadataObjects TYPE parameter, a subtype of the metadata type in TYPE, or an asterisk, which defaults to the value in the TYPE parameter. The value that you specify in Object indicates what association names are valid. In the first AssociationPathLevel, the following is true:

If Object is a metadata type, then AssociationName must be an association name that is valid for that metadata type as defined in the SAS Metadata Model. For example, if Object is Report, then AssociationName must be an association name that is defined for the Report metadata type in the SAS Metadata Model.
If Object is an *, then AssociationName must be an association name that is valid for the metadata type specified in the TYPE parameter.

The AssociatedObject in AssociationPathLevel specification can also be a metadata type name or an asterisk. However, in this position, the specified value stipulates whether associated objects of one metadata type should be evaluated, or, that associated objects of all of the potential associated metadata types defined for the association name should be evaluated. For example:

When AssociatedObject is a metadata type, this says, "Give me only object instances of this metadata type that are related under the specified association name."
When AssociatedObject is an asterisk, this says "Give me object instances of all potential metadata types that are defined for the specified association name."

Consider the following AssociationPathLevel specifications to understand how the asterisk and metadata type names are evaluated in the Object and AssociatedObject positions. For these examples, assume that Report is the metadata type specified in the TYPE parameter.

*[ReportLocation/*]

Report[ReportLocation/Email]

The first specification selects objects of the metadata type specified in the TYPE parameter (Report) that have a ReportLocation association and associated objects of any of the metadata types that are valid for the ReportLocation association name. The ReportLocation association name supports associations to objects of 19 metadata types.

The second specification selects Report objects that have a ReportLocation association to an Email object. (Email is one of the 19 supported metadata types.)

If a subtype were specified in either the Object or AssociatedObject positions, then the SAS Metadata Server would select only objects and associated objects of the specified subtypes. Report is a subtype of the Classifier metadata type. If Classifier were the metadata type specified in the TYPE parameter, the first specification above would apply to the Classifier metadata type. The second specification would still only apply to Report objects.

The AttributeCriteria component in AssociationPathLevel further limits the Objects that are selected to objects whose associated objects meet the specified attribute criteria. For example, consider the following request:

Report[ReportLocation/Document[@TextType='XML']]

The attribute criteria limit the Report objects that are selected to objects that have associated Document objects that have the attribute TextType="XML". When attribute criteria are specified in a query that has an * in the AssociatedObject component, the attribute criteria are applied to all associated objects.

Subsequent AssociationPathLevel components in an AssociationPath get their context from the AssociatedObject in the preceding level.

When the preceding associated object is a metadata type, then AssociationName must be an association name that is valid for that metadata type.
When the preceding associated object is an *, then AssociationName can be any association name defined for one of the metadata types supported by the preceding association name.

Consider the following AssociationPathLevel:

Report[ReportLocation/Document[@TextType='XML']]

AssociationName in a second AssociationPathLevel specification must be an association that is valid for the Document metadata type. The AssociatedObject in the second AssociationPathLevel must be a metadata type that is supported by the second AssociationName or an *.

Consider the following AssociationPathLevel:

Report[ReportLocation/*]

AssociationName in a second AssociationPathLevel specification can be an association name that is valid for any of the 19 metadata types supported by the ReportLocation association. The AssociatedObject in the second AssociationPathLevel must be a metadata type that is supported by the second AssociationName or an *.

The following is an example of an AssociationPath that specifies multiple AssociationPathLevel components and specifies metadata types in the AssociatedObject positions:

Report[ResponsibleParties/ResponsibleParty/Persons/Person/Locations/Location[Area='New York']]

The request selects Report objects that have a ResponsibleParties association to a ResponsibleParty object that has a Persons association to a Person who has a Locations association to a Location object that has the attribute value Area="New York". It has three AssociationPathLevel components:

ResponsibleParties/ResponsibleParty
Persons/Person
Locations/Location

The following is an example of an AssociationPath that specifies multiple AssociationPathLevel components and specifies asterisks in the AssociatedObject positions:

Report[ResponsibleParties/*[@Role='OWNER']/Persons/*[@Name='John Doe']]

The request selects Report objects that have a ResponsibleParties association to any object that has a Role= attribute value of Owner and a Persons association to any object that has a Name= attribute value of John Doe. It has two AssociationPathLevel components:

ResponsibleParties/*
Persons/*

Effect of OMI_INCLUDE_SUBTYPES Flag on an Association Path

Setting the OMI_INCLUDE_SUBTYPES (16) flag with OMI_XMLSELECT in the GetMetadataObjects method can drastically alter the results. When OMI_INCLUDE_SUBTYPES is set, the SAS Metadata Server applies the specified selection criteria to objects of the metadata types specified in Object and AssociatedObject, and to all of their subtypes.

If the metadata types have no subtypes defined for them in the SAS Metadata Model (neither Report nor Person have subtypes defined), the flag has no effect. However, some metadata types, such as Classifier, have many subtypes. The ability to get subtypes is useful when you want to get objects of similar metadata types that have common properties. Consider the following request:

Classifier[ResponsibleParties/*[@Role='OWNER']/Persons/*[@Name='John Doe']]

When OMI_INCLUDE_SUBTYPES is set, this request returns all Classifier objects, and objects of its subtypes Cube, Dimension, ExternalTable, PhysicalTable, QueryTable, Report, SharedDimension, TableCollection, and WorkTable objects that are owned by John Doe.

To determine what metadata types have subtypes, see the SAS Metadata Model documentation.

Top of Page