*** This package is subject to change. ***

Note:

Extension of the classes in this package is prohibited unless otherwise documented. Similarly, extension or implementation of the interfaces in this package is prohibited except as documented.

Package com.sas.iquery.metadata

Top-level package for SAS Query Services's three models, the business model, physical model, and expression model, which are all used in defining information maps and data selections.

See:
Description

Interface Summary

IntelligentQueryMetadataServiceInterface	Specifies an object that is more of a container or a configuration/context of knowledge that SAS Query Services has about supported databases and server information.
LocalizableNamedObjectInterface	Specifies basic getter methods for objects that have labels and descriptions that can be configured based on Locale.
NamedObjectInterface	Specifies basic getter methods for objects that have labels and descriptions.
PropertyChangeListenee	Specifies an object that can be listened to for changes to its definition.

Class Summary

IntelligentQueryMetadataServiceFactory	Specifies a factory for creating metadata service objects.
StructureOfData	Contains information about the structure of data that can be queried.

Exception Summary

InvalidIDException	Specifies an exception that is thrown when an object's ID is not set or when the business model that created the object has an ID that is not set.
IQueryException	IQueryException is a temporary superclass to MetadataException.
MetadataException	An exception that provides information on a metadata error or some other errors.
MetadataNotChangeableException	Models information about why a metadata object is not changeable.
MetadataUnresolvedException	Specifies an exception that is thrown when an unresolved BusinessModelResource object's method is called and that method is not supported because the object is unresolved.

Package com.sas.iquery.metadata Description

Top-level package for SAS Query Services's three models, the business model, physical model, and expression model, which are all used in defining information maps and data selections. Classes and interfaces within this package are used across the models.

Information maps enable you to model information about the data that a user wants to query and how that data should be accessed. Information Maps are a mapping between a raw, or "physical," form of the data (for example, as specified by tables, columns, cubes, or hierarchies) to a more composite form of the data that enables the specification of expressions and other operations. This composite form is called the "business" metadata form or business model. The business model enables you to model the data and filtering capabilities that you can use within queries, which enables you to model their business logic into modeled items and queries. The business model is concerned with the modeling of user-defined query-related items. Information maps and data selections are both business models in that they enable this type of modeling. Data selections, besides enabling the modeling, provide a query specification that is based on the modeling done in business models.

The main purpose of a data selection is to provide a "query specification." These queries are passed to QueryConnectorInterface objects to run and return result sets. The name "data selections" is used because they typically refer to selected modeled objects (such as "data items") in their query specification. The query specification portion of a data selection is usually referred to as a Business Query because it is based on objects that are modeled within a business model.

Types of modeling provided by SAS Query Services

SAS Query Services models information solely in order to provide metadata to define query specifications. There are several types of metadata that are modeled.

• Physical modeling: modeling of raw or physical forms of data, such as tables, columns, cubes and hierarchies.
• Business modeling: modeling of objects that are defined by IQ and that are referenced and persisted within a business model. This type of modeling can be further broken up into smaller pieces as follows:
  • Business item modeling: modeling of the higher-level objects (such as data items, filters, and prompts) that have an identity from a user's perspective. That is, if a user were "visually shown" the contents of a business model, then they would expect to see these types of higher-level objects.
  • Step modeling: modeling of incremental filtering of a data item or query using "steps."
  • Business Query modeling: specification of a query based on metadata that is defined in a business model.
• Expression modeling: modeling of expressions that are used within business items that help make up the "core" of a business item's definition

Modeling example

The following example shows a simple Information Map that is based on two relational tables and has a data selection that is built on the information map. The figure illistrates how an Information Map provides information about data sources that are the basis for defined objects such as data items and filters. Information maps also provide the relationships between multiple data sources. One of the core values of an information map, or of any business model, is the ability to model user-defined query-related objects that are to be used in the query specification (business query) portion of data selections. In the following example, data items and filters are modeled.

The arrows inf the figure show references from one model to another. The order of creation of the models though, is from left to right.

After you have a data selection, you can run the query and get the result set for the query by using a query connector (part of SAS Query Services' data services component).

Also notice in the previous figure that parent-child terminology is used to describe relationships between business models. The information map is the parent business model of the data selection, which is considered the child in this example.

It is also possible to base data selections on other data selections, not just information maps, resulting in a tree of business models with the root of the tree being an information map. The "basing" of models on one another can be used to build up metadata definitions in child data selections in such a way that the child data selections have access to more business item (for example, data item) definitions than their parent data selections. This can be useful to do when you want to use a set of business items that is already defined in a parent data selection and you want to add more business items either for a special purpose or for a secondary query, and you do not want to affect the query specification or the set of modeled objects in the parent data selection.

The SAS Query Services' Metadata Service

In this release, the SAS Query Services' metadata service does not support many functions that can be called by users. However, methods in other classes that take a metadata service object do require/enforce that a metadata service is passed into them.

The service contains a configuration of the supported types of servers and the capabilities of those servers. This configuration is read when the service is created and the configuration is used to provide context to business models based on that service. For example, if the following expression is modeled and used in a data item: SQRT(DataItemA + DataItemB), then the SQRT function and the + operator are objects that are part of the service's configuration for a specific server type and might not be available for all the types of servers that are supported. The functions and operators that are available for use within expressions are dependent on the server type that will access the data at query time. The server type is determined by the server that is specified to access the data; the server specification is made in the definition of each data source in an information map.

SAS Workspace Servers and SAS OLAP Servers are the server types that are supported by SAS Query Services. Oracle servers and other types of third party database servers can be used with SAS Query Services through SAS Workspace Servers and other SAS software like SAS/ACCESS.

How the Metadata Service is integrated with SAS Foundation Services

• SAS Query Services metadata service methods require a session context for supplying the user session. Users must have already been authenticated and have a session in order to use the metadata service.
• BriefInformationMap objects are Information Service ?smart objects? (MetadataInterface objects). Users can navigate a repository's root folders and get BriefInformationMap objects back when asking folders for the items they contain. BriefInformationMap objects provide only the basic smart object capabilities. Their main purpose is to enable interaction with a representation of an information map in order to get its most basic information, such as its name and description. Using brief information maps means that a full information map does not have to be built every time a representation of an information map is encountered, which means that memory and CPU costs are much lower. The actual usage of an information map by queries requires that BriefInformationMap objects be turned into full information map objects that contains its business metadata modeling information. A BriefInformationMap object is ?very thin? in memory footprint compared to its corresponding Information Map object.
• The SAS Query Services metadata service utilizes the Logging Service for its logging needs
• The SAS Query Services metadata service utilizes the Discovery Service for finding other SAS Foundation Services
• The SAS Query Services metadata service utilizes the Information Service for searching, navigating, and saving objects to/from repositories.

A single instance of the SAS Query Services metadata service, that has no changeable state and that requires sessions as input to its methods, is considered safe to use concurrently between multiple users in mid-tier usage scenarios.

Example ? Creating a SAS Query Services Metadata Service

// Create a SAS Query Services metadata service from the factory
// This creates a service containing configuration information on the servers
// and their properties that are supported by the SAS Query Services.

IntelligentQueryMetadataServiceInterface iqService = IntelligentQueryMetadataServiceFactory.newService();

The mechanics of using information maps

Reading an information map from a repository

There are two starting points for reading in an information map from a repository. In one case, you start with a brief representation of a map. The other is by starting with a path that describes the location of the information map.

Reading via a BriefInformationMap

A BriefInformationMap object is an Information Service ?smart object? (MetadataInterface object) that, in this case, represents basic information about an information map. This object is typically found by navigating through a repository root folder and obtaining a brief information map by asking folders within the tree for the items that they contain. If you are interested in getting a full information map object that corresponds to a BriefInformationMap object, then you can call one of the InformationMapFactory.newInformationMap() methods by inputting the brief information map as shown in the following example. The method returns a full information map object that corresponds to the brief information map given.

Example ? Reading an information map from a repository that corresponds to a BriefInformationMap

// This example assumes that the API user has a BriefInformationMap: this can be obtained by navigating

// through a repository root folder in a repository defined by the Information Services component of the SAS Foundation Services.

// Get the full information map from the repository, given the user?s session, the SAS Query Services' metadata service, and the brief information map representing

// the information map.

InformationMap map = InformationMapFactory.newInformationMap(userSessionContext, iqService, briefMap);

Reading via a PathUrl

A PathUrl object is a repository path to a smart object in a repository root folder. This path is similar to a filepath in a file system. The PathUrl is an object-modeled form of the URL string that represents where and what the object is. If you have a String object representing the URL to a BriefInformationMap, then you can read in the information map in two steps.

You must first turn the URL string into a PathUrl by using the constructorfor the PathUrl depending on what you want it to mean. The second step is to use one of the InformationMapFactory methods and use the PathUrl to construct an information map. The method returns a full information map object for the PathUrl that is given.

Applications such as those that create reports can keep paths to information maps as part of the persistence of their managed objects. Those paths can later on be brought back into memory through the reading of the map via the PathUrl.

Example ? Reading an information map from a repository that corresponds to a PathUrl

// This example assumes that the API user has a String object that represents a path to an Information

// Map in a repository that is configured in the Information Service component of SAS Foundation Services.

String pathToMap = "SBIP://MyRepository/BIP Tree/Users/InformationMaps/Inventory(BriefInformationMap)"

com.sas.services.information.metadata.PathUrl pathUrl = new com.sas.services.information.metadata.PathUrl(pathToMap);

// Get the full information map from the repository, given the user?s session, the SAS Query Services' metadata service, and the PathUrl object describing where and what type of object to retrieve.

InformationMap map = InformationMapFactory.newInformationMap(userSessionContext, iqService, pathUrl);

In-memory Lifetime Management of Information Map objects

No lifetime management of information map objects is provided by SAS Query Services. Also, no lifetime management is provided for BriefInformationMap objects (Information Service ?smart objects"). Therefore, you can have duplicate and different versions of the same map (a map corresponding to the same persistent location) in memory at the same time. You must use caution in such situations.

The Business Model

A business model is a persistable container of business items where the items are defined on a context of physical metadata and are meant to be used in specifying queries. Each business item enable you to specify a portion of a query, which is meant to be in terms that are more user-centric rather than be descriptive of how the data is stored.

Business models can be chained together in trees with parent-child relationships in order to enable one model to build upon another. Child business models provide at least as much business metadata to base queries on as parent business models provide.

There are several kinds of business items; the two most frequently used are the data item and filter (or filter item). Data items provide support for the mapping of physical pieces of data (for example, a column in a relational table or a measure in an OLAP cube) to a single unit of business data. Data items also:

• enable you to add things like formatting and ordering information to the mapped business data
• can contain expressions for defining calculated items
• are used in queries for returning results
• represent the smallest unit returned by a query

Filters are used to model how data is to be subsetted in the query. Query-language clauses like WHERE and HAVING are typically where this subsetting occurs.

Business items can model business metadata based on both OLAP and relational physical metadata. This means both forms of metadata are model by the DataItem class. The Step class is used to define navigation filtering, sorting, member filtering, and data-based filtering for OLAP metadata as well as rank filter for both forms of metadata. The FilterItem class is used to model filters for both relational and OLAP filters.

This diagram depicts the major containment relationship for a data item.

Modeling the contents of an information map

An information map is a business model. Not only does it enable you to model business metadata, but it also provides a few other things that a business model does not. An information map:

• provides support for organizing the business items that are contained within subfolders in the information map. Subfolders within information maps are called information map folders.
• provides support for being stored in a folder within a SAS Metadata Repository's root folder. Folders within a repository root folder extend the FolderInterface class, which is managed by the Information Service component of SAS Foundation Services.

It is typical, although not required, for some business metadata to be specified at the information map time only and not by child business models (child data selections). Some examples of this are the join information about how to join tables together that are used by data items, and which stored processes to run when a query is run that is based on the information map.

One can create new business items in business models by calling the newXXX methods on the business models, where XXX is the type of business item to be created by the business model. For example, there are newDataItem() and newFilterItem() methods for instantiating new data item and filter objects. These methods only instantiate the objects they do not ?add the object to the model? (that is, contain the new object).

Persistence of Business Models

If you want to use the instantiated business items later (that is, have them persisted when the model is persisted), then they must be contained in the business model. This is done by using the addBusinessItem() method after the items are instantiated. If you do try to persist (write) out an information map or data selection to persistent storage and one business item references another item (for example, if a filter references a data item) that is not contained in the business model, then the whole model will fail to persist because parts of its definition are not accessible in a persisted state.

Data selections -- a type of business query

Data selections are modeled relational or OLAP queries that are based on business metadata. The business metadata?s definition and location is an information map but additional business metadata can be modeled and used in queries by Data Selections themselves.

Therefore, a data selection is a ?business model? itself. It also models business metadata that is used in the data selections. In a general sense, a data selection can be thought of as having the capabilities of an information map (because it extends the business model) but a data selection also provides support for the specification of a query based on business metadata (because it extends the business query).

Data selections provide for specifying a number of things as part of their BusinessQuery interface, such as:

• What data items are to be used to define specific columns, and tuples that are to be returned in the result set from the query.
• What filters are to be applied when running the query.
• What data items are to be sorted on in the query results.
• What query options are to be applied when running the query (for example, return formatted data vs. return unformatted data).

The following diagram depicts the relationship between the data selection and the modeled objects that help make up its query specification.

*** This package is subject to change. ***

Note:

Extension of the classes in this package is prohibited unless otherwise documented. Similarly, extension or implementation of the interfaces in this package is prohibited except as documented.