7. Querying Working Memory

Jess's working memory is similar to a database; it's filled with indexed, structured data. Most of the time, you'll access working memory by pattern matching from a rule. But once in a while, you'll write some procedural code that needs to extract data from working memory directly. This chapter tells you how.

A time-honored way to search a collection of items is by using linear search and a filter, a Boolean function that indicates whether an item should be part of the search result or not. Jess supports this kind of brute-force search of Java objects in working memory using the jess.Filter interface. You can implement jess.Filter and then pass an instance of your filter to the jess.Rete.getObjects(jess.Filter) method, which will return an java.util.Iterator over the selected objects. Although this might not be practical for large working memory sizes, it's certainly convenient. In the following, we run a Jess program that deals in Payment objects, then query working memory for all the Payment objects and call process() on each one:

    
import jess.*;
import java.util.Iterator;
public class ExMyFilter {
    interface Payment { void process(); }
    public static void main(String[] argv) throws JessException {
        Rete engine = new Rete();
        engine.batch("cashier.clp");
        Iterator it = engine.getObjects(new Filter() {
            public boolean accept(Object o) {
                return o instanceof Payment;
            }
        });
        while (it.hasNext()) {
            ((Payment) it.next()).process();
        }
    }
}

While linear search is convenient, it's inefficient. The defquery construct lets you create a special kind of rule with no right-hand-side. While normal rules act spontaneously, queries are used to search the working memory under direct program control. Whereas a rule is activated once for each matching set of facts, a query gives you a jess.QueryResult object which gives you access to a list of all the matches.

Using a defquery involves three steps:

1. Writing the query
2. Invoking the query
3. Using the results

In the following section, we'll examine a specific example of how this is done.

Jess> (deftemplate person (slot firstName) (slot lastName) (slot age))

Imagine that we want to be able to query working memory to find people with a given last name. Once we've found a person, we'll want to know their first name as well, and their age. We can write a query which lets us specify the last name we're interested in, and also lets us easily recover the first name and age of each match.

Jess> (defquery search-by-name
  "Finds people with a given last name"
  (declare (variables ?ln))
  (person (lastName ?ln) (firstName ?fn) (age ?age)))

While we're at it, let's define some facts for the query to work with and load them into working memory:

Jess> (deffacts data
  (person (firstName Fred)   (lastName Smith)    (age 12))
  (person (firstName Fred)   (lastName Jones)    (age 9))
  (person (firstName Bob)    (lastName Thomas)   (age 32))
  (person (firstName Bob)    (lastName Smith)    (age 22))
  (person (firstName Pete)   (lastName Best)     (age 21))
  (person (firstName Pete)   (lastName Smith)    (age 44))
  (person (firstName George) (lastName Smithson) (age 1))
  )

Jess> (reset)

After we define a query, we can call it using the run-query* function in Jess, or the jess.Rete.runQueryStar(java.lang.String, jess.ValueVector) method in Java. In both cases, we need to pass the last name we're interested in as the query parameter. In Jess, this looks like

Jess> (reset)

Jess> (bind ?result (run-query* search-by-name Smith))

The arguments to run-query* are the name of the query and values for each parameter. The run-query* function returns a jess.QueryResult object, which we store in the variable ?result.

In Java, the equivalent code would look like:

    Rete engine = ...
    QueryResult result = engine.runQueryStar("search-by-name", new ValueVector().add("Smith"));

Now that we've created a jess.QueryResult, it's time to iterate over all the matches and process them however we'd like. For this example, let's just print a table of the people including their full names and ages.

The interface of the jess.QueryResult class is very similar to that of java.sql.ResultSet. We use jess.QueryResult.next() to advance to the next result, and we use the set of getXXX() methods to return the values bound to the variables defined in the query. Then the following Jess code will print the output shown:

Jess> (while (?result next)
    (printout t (?result getString fn) " " (?result getString ln)
                ", age " (?result getInt age) crlf))

Fred Smith, age 12
Bob Smith, age 22
Pete Smith, age 44
FALSE

because there are three people named Smith in working memory.

The same loop in Java would look like

while (result.next()) {
    System.out.println(result.getString("fn") + " " + result.getString("ln")
                       + ", age" + result.getInt("age"));
}

For the sake of completeness, here's the whole program in Java. The file "query.clp" is assumed to contain the deftemplate, defquery, and deffacts from above.

    
import jess.*;

public class ExQuery {
    public static void main(String[] argv) throws JessException {
        Rete engine = new Rete();
        engine.batch("query.clp");
        engine.reset();
        QueryResult result =
            engine.runQueryStar("search-by-name", new ValueVector().add("Smith"));
        while (result.next()) {
            System.out.println(result.getString("fn") + " " + result.getString("ln")
                               + ", age" + result.getInt("age"));
        }
    }
}
C:\> java ExQuery

(declare (variables ?X ?Y ...))

(declare (max-background-rules 10))