11.4. Compiling and Executing Queries
Prev | Chapter 11. Query | Next

## 11.4. Compiling and Executing Queries

    public FetchPlan getFetchPlan ();

Before compiling and/or executing your query, you may want to use the query's `FetchPlan` to optimize which fields and relations of your result objects will be loaded, and to configure result scrolling. See Chapter 12, FetchPlan for details on the `FetchPlan` interface.

When you create a query with `PersistenceManager.newQuery` or `PersistenceManager.newNamedQuery`, the query's `FetchPlan` is initialized to the same values as the plan of its owning `PersistenceManager`. Subsequent changes to the query's `FetchPlan`, however, will not affect the `PersistenceManager`'s plan.

    public void compile ();

Compiling is a hint to the implementation to optimize an execution plan for the query. During compilation, the query validates all of its elements and reports any inconsistencies by throwing a `JDOUserException`. Queries automatically compile themselves before they execute, so you probably won't use this method often.

    public Object execute ();
    public Object execute (Object param1);
    public Object execute (Object param1, Object param2);
    public Object execute (Object param1, Object param2, Object param3);
    public Object executeWithArray (Object[] params);
    public Object executeWithMap (Map params);

As evident from the examples throughout this chapter, queries are executed with one of the many `execute` methods defined in the `Query` interface. If your query uses between 0 and 3 parameters, you can use the `execute` version that takes the proper number of `Object` arguments. For queries with more than 3 parameters, you can use the generic `executeWithArray` and `executeWithMap` methods. In the latter method, the map is keyed on the parameter name.

All `execute` methods declare a return type of `Object` because the return type depends on how you've configured the query. So far we've only seen queries that return `List`s, but this will change in the next section.

    public void close (Object result);
    public void closeAll ();

Some query results may hold on to datastore resources. Therefore, you should close query results when you no longer need them. You can close an individual query result with the `close` method, or all open results at once with `closeAll`.

| Note
By default, Kodo greedily fills each result list and immediately releases all database resources, making `close` unnecessary. You can, however, configure Kodo to use lazy element instantiation where appropriate. Under lazy instantiation, list elements that are never accessed are never created, and elements may be released after being traversed. Combined with Kodo's memory-sensitive data structures and smart eager fetching policies, lazy element instantiation also allows you to efficiently iterate over huge data sets - even when the entire data set could not possibly fit into memory at once. These lazy results consume database resources, so if you enable them you are strongly encouraged to close all query results after processing. If they are not closed explicitly, they are closed automatically when the JVM garbage collects them. See Section 4.11, “Large Result Sets” in the Reference Guide for details on configuring Kodo for lazy result instantiation.

Prev | Up | Next
11.3. Advanced Object Filtering | Home | 11.5. Limits and Ordering