IBM Content Manager, Version 8.5 Supports: Oracle, DB2, C++, Java

Querying the IBM Content Manager server

You can build queries that perform three main types of searches: parametric, text, and combined parametric and text. To run a query, you can use one of the following methods: evaluate, execute, or executeWithCallback.

A parametric query uses conditions such as equality and comparison. A text query uses text search functions, which make the search more thorough. A combined query is composed of both text and parametric conditions.

When you query the IBM® Content Manager library server, you complete the following main steps:

Create a query string to represent your search conditions.
Call the evaluate, execute, or executeWithCallback method with your query string and query options to get the results. Or, call the executeCount method to get the count of the results.
Receive the results through a DKResults object, a dkResultSetCursor, or a dkCallback object.

The query APIs perform the query processing tasks, such as preparing and executing a query, monitoring the status of a query execution, and retrieving the results.

When you submit a query, you must submit a list of query options, each of which is documented in the Application Programming Reference (Javadoc) for the DKDatastoreICM class. One of the query options available includes an entry for retrieve options. Query calls multi-item retrieve (DKDatastoreICM::retrieveObjects(dkCollection,DKNVPair[]) method and passes the retrieve options you supplied (or the default options).

Important: It is recommended that you always specify the retrieve options instead of the default and use the DKRetrieveOptionsICM class. Submitting a DKRetrieveOptionsICM instance enables additional optimization and allows for better performance choices. For the C++ native API, it is especially important to always submit a DKRetrieveOptionsICM instance for better performance.

The evaluate method returns all results as a collection of DDOs. The default options work well for result sets that are relatively small, 200 items or less. When working with larger results sets, specify the IDONLY retrieve option to prevent attribute data from being stored in the DDOs that are returned. In this case, you must explicitly retrieve the attribute data for the DDOs because the data is needed by the application. You can limit the result set size by using the max results option.

The execute method returns a dkResultSetCursor object, which has the following characteristics:

The dkResultSetCursor object works like a content server cursor.
You can use the dkResultSetCursor object for large result sets because the DDOs it returns are retrieved in blocks as the user requests them.
You can use the dkResultSetCursor object to rerun a query by calling the close and open methods.
You can use the dkResultSetCursor to delete and update the current position of the result set cursor.
The dkResultSetCursor object holds a database cursor open to fetch rows as they are needed from the database.
To prevent locking and transaction problems, a new database connection is used to execute the query. This means that your application might use two connections while the cursor remains open. To avoid this additional connection, use the evaluate method to run the query.

Important: The IBM Content Manager does not support scrollable cursors.

The executeWithCallback method executes a query in an asynchronous manner and sends the results to the specified callback object in blocks. As such, the executeWithCallback method frees up the main thread of execution from the task of retrieving query results. See the Application Programming Reference for a description of the query options of the execute method.

Starting with IBM Content Manager Version 8 Release 3, there are two ways you can get the count of query results without retrieving the results themselves. One way is through the executeCount method in DKDatastoreICM, and the other way is through the cardinality method in dkResultSetCursor. The executeCount method in DKDatastoreICM takes in a query string and options and returns the estimated count of the results of the query. The cardinality method in dkResultSetCursor, implemented in the IBM Content Manager Version 8 connector, allows you to obtain the count when you already have a dkResultSetCursor. This call requires a separate trip to the server to evaluate the count.

The count of query results can be different from the number of results that you would get when running the query and getting the results. This result occurs because the count is accurate only at an instant in time. Items might be added or deleted between the time the count is retrieved and when the results are retrieved. There are also a few cases in which query might return the ID of an item, but the retrieve API cannot access that item. In these cases, the count is also inaccurate. To get an accurate count, a server call must be made to evaluate the query, which means that if you want the count and then the results, you must make two trips to the server.

For more information about query methods, see the SSearchICM sample. See the Application Programming Reference for the evaluate, execute, or executeWithCallback methods in DKDatastoreICM class.

Feedback