|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|
|QueryConnectorInterface||Specifies methods that are used to execute queries.|
|ConnectionConfiguration||Contains settings that are used to configure connection behaviour.|
|OfflineResultSetConfiguration||Contains settings that are used to configure offline result sets.|
|QueryConnector||Retrieves result sets by executing business queries.|
|QueryConnector.CloseOptions||Contains bit values that are used to close specific resources that are managed by the
|RetrievalPolicy||Contains query policy settings.|
|SimpleQueryConnector||A basic query connector without result or connection management.|
|DataRetrievalException||Specifies an exception that is thrown on errors in SAS Query Services data retrieval.|
Provides entry points that are used to retrieve result data by executing queries (data selections).
This page describes the use of queries based on information maps. See
for a description of the underlying models such as business models, data selections and how to build
QueryConnector object serves as a facade
for executing queries and managing the resources that are obtained and the results that are returned.
Queries are represented by
objects and cab be executed in order to retrieve result sets, which enable applications to
pull data from the server.
Based on the abstract definitions of data sources, sorting, formatting and other properties of the result data items of a data selection, the query connector will build a query in the server?s native language, for example using SAS, SQL or MDX.
The result of executing this native query will be a result
data set object specific to the type of server, such as a
tabular result set or a multi-dimensional
OLAP data set. These result sets
are interactive objects, which enable applications to control how they work through
the returned data.
To accommodate abstract applications, which do not need to know about the specific types
of servers or query results, the server-type-specific result data sets are always
wrapped in an abstract
can be manipulated independently of the underlying type of result data.
The general sequence of interactions that are used to execute a query is outlined in the diagram
See executing a relational query for an example of query execution.
Currently, the query connector supports three types of queries:
InformationMap(a relational query) returns a tabular result set if it contains only
data itemswhose roles are neither
Both plain relational and relational cross tabular queries are performed against tabular data (information maps referencing tables). They are only distinguished from one another by the roles of the data items that they contain.
com.sas.iquery.metadata.business for examples of how to build
different types of queries.
The query connector?s mode of operation depends on a collection of settings
that are passed to it queries are executed. These settings
are collected into an object known as a
See an example of how to use the retrieval policy.
The retrieval policy contains settings for three areas:
The behavior policy uses the following settings to determine the general strategy to use for retrieving data:
Currently, the only difference between these two settings is in relation to embedded data, support for which might be removed or changed in future releases of SAS Data Services.
RetrievalPolicy for more information about behavior policies.
The connection configuration contains two settings:
The connection lifetime determines how connections are managed for subsequent queries that are made by the same user.
ConnectionConfiguration.USER_SESSION re-uses a single connection per user for all queries against
a server, until the connection is explicitly released.
ConnectionConfiguration.ACQUIRE_RELEASE creates a new connection to a server each time a query
is executed. This is usually slower than re-using a single connection.
See also the section below on managing resources.
The connection wait time determines how long to wait for an available connection to the server if no connections are immediately available.
ConnectionConfiguration for more
information about connection configurations.
For the system to scale to larger numbers of users, currently these users must be able to share a limited number of server connections. In order to release server connections early, it is possible to make tabular query result sets pre-load some of their data and then immediately return the connection for use by others. A tabular result set that contains such pre-loaded data and that is disconnected from the server, is called an offline result set.
Offline result sets make it possible for the user to interact (scroll) within the pre-loaded data without needing to make a new connection to the server. If the user scrolls beyond the pre-loaded data, then the same query is transparently executed against the server again in order to load more data.
OLAP result sets cannot currently be made off-line and therefore won't work after their connection has been closed.
For offline result sets, it is possible to configure the number of rows to pre-load and how many of these to keep in memory and on disk. Adjusting these values to match real-world usage is critical to good and scalable performance.
Note that enabling offline result sets might incur significant overhead because of disk writes and re-queries, so only enable them if you need to release connections immediately and still need to interact with tabular result sets after this point.
information about offline result set configuration.
The management of resources that are obtained and returned by the query connector depends on the connection lifetime settings.
When you exclusively use the ACQUIRE_RELEASE connection lifetime, the query
connector does not manage any resources. Connections are acquired for each query,
and are attached to the particular result set (
ResultSetInterface) that is returned. When the result set
is closed, so is its associated connection.
A useful pattern for ensuring clean-up of connections and result sets is to wrap the retrieval and use of result sets in a
try...finally block which
ensures that result sets are closed. If a result set is not closed
explicitly, then its associated connection will remain until the result object is garbage collected.
When you use USER_SESSION connection lifetime, the query connector
will manage both server connections and the result sets that are returned. Because multiple
result sets can depend on a server connection, these should be disposed of in
conjunction with the connection. (Offline or relational cross tabular result sets
do not depend on retaining their original connection. They will re-use a user's
connection if one is present or acquire a new one as necessary.)
int) for more information about managing resources.
Some relational information maps might have associated stored processes. The first time a query based on such a map is executed, the stored process is run, and the query is performed against the output of the stored process. Subsequent queries against the map using the same connection will not re-execute the stored process.
ConnectionConfiguration.ACQUIRE_RELEASE, each query creates a new connection, and so the stored process is re-executed every time a query is run.
ConnectionConfiguration.USER_SESSIONconnection lifetime, the connection is re-used and so the stored process is not re-executed except after an explicit closing of the tabular workspace server connection using
ConnectionConfiguration.USER_SESSIONis to close the current connection.
|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|