Basic Search

Now that we've populated our database, let's start taking advantage of MarkLogic's real power: search/query. The first step to creating and executing queries is to get your hands on a QueryManager instance, which our DatabaseClient instance is happy to provide:

// create a manager for searching QueryManager queryMgr = client.newQueryManager();

All of the sample programs referred to in this section begin with the exact line of code above.

What's the difference between search and query? For MarkLogic, there's no difference except in how we use the terms. A query is a search specification, and a search is the execution of a query.

This usage is reflected in how you perform a search:

// run the search queryMgr.search(query, resultsHandle);

The search() method executes the query that you give it, sending the results to the resultsHandle you provide.

So how do we create a query? First we have to decide which of the three kinds of queries we want:

Kind of query	What it does
string	finds documents using a search string
query by example (QBE)	finds 'documents that look like this' using criteria that resemble the structure of documents in your database.
structured query	finds documents according to an explicit hierarchy of conditions

Each of these is modeled by the QueryDefinition interface and its sub-interfaces:

• QueryDefinition
  • StringQueryDefinition
  • RawQueryByExampleDefinition
  • StructuredQueryDefinition

To get one of these, you start by asking your query manager for a query instance. Let's start with a query-by-example search.

Find XML documents using a query by example

Open up Example_15_SearchQBE.java. Here we're going to look for documents with a person in them who is described as a brother. We can draw up a simple XML example of what this would look like, noting that inside the PERSONA element, we look for the word brother.

// Create a search definition StringHandle handle = new StringHandle( "<q:qbe xmlns:q=\"http://marklogic.com/appservices/querybyexample\">\n" + " <q:query>\n" + " <PLAY>\n" + " <PERSONAE>\n" + " <PERSONA><q:word>brother</q:word></PERSONA>\n" + " </PERSONAE>\n" + " </PLAY>\n" + " </q:query>\n" + "</q:qbe>" ); RawQueryByExampleDefinition query = queryMgr.newRawQueryByExampleDefinition(handle);

Query by example is a powerful and easy syntax to learn for expressing a wide variety of searches. This example is in XML, but there is JSON syntax as well as you will see next.

Find JSON documents using a query by example

Open up Example_15_SearchQBE_JSON.java. Here we are looking for plenary talks.

// create a search definition StringHandle handle = new StringHandle( "{ \"$query\": { \"plenary\": true } }" ).withFormat(Format.JSON); RawQueryByExampleDefinition query = queryMgr.newRawQueryByExampleDefinition(handle); // create a handle for the search results StringHandle resultsHandle = new StringHandle().withFormat(Format.JSON); // run the search queryMgr.search(query, resultsHandle);

Find documents using a search string

Open up Example_16_SearchString.java. This time we're using a StringQueryDefinition:

// create a search definition StringQueryDefinition query = queryMgr.newStringDefinition(); query.setCriteria("index OR Cassel NEAR Hare");

After grabbing an initial string query instance from our query manager, we specify the search text using its setCriteria() method. In a real-world search application, you'd often insert user-supplied text here (what the user types in the search box). In this case, our string query is "index OR Cassel NEAR Hare". This will find documents (regardless of format) that either contain the word "index" or have the word "Cassel" appearing near the word "Hare". What this illustrates is that even a "simple search" can be quite powerful using MarkLogic's default search configuration (which are called search options). Later on, we'll see a couple examples of how to customize search options.

Run the program to see the first 10 search results, each of which includes snippets of text that matched the query.

Get another page of search results

Open Example_17_SearchWithPageSize.java. This program is identical to the previous one, except in this case we want to return a different subset of the results. All the previous examples returned the first 10 most-relevant results. Here we're asking for the third 5 most relevant results. In other words, we're using a smaller page size (5 results per page) and asking for the third page of results. First we store our desired page size in a variable:

public static int PAGE_SIZE = 5;

Then we set the page size on our query manager:

// Set page size to 5 results queryMgr.setPageLength(PAGE_SIZE);

To specify which page of results we want, i.e. where we want the search results to begin, we use the search() method's third argument (start):

// get the 3rd page of search results int pageNum = 3; int start = PAGE_SIZE * (pageNum - 1) + 1; // get search results starting with the nth result queryMgr.search(query, resultsHandle, start);

Run the program to see the search results starting at the 11th result.

Find documents based on their properties

Open Example_18_SearchProperties.java. Here we see our first example of a StructuredQueryDefinition. Most structured queries are only useful in conjunction with modified search options (see "Custom search" below). But using one is also necessary for a basic search against document properties:

// get a structured query builder StructuredQueryBuilder qb = queryMgr.newStructuredQueryBuilder(); // Find all documents that have a property value containing the word "fish" StructuredQueryDefinition query = qb.properties(qb.term("fish"));

Run the program to get a list of all the matching documents (photos of fish).

Search within a directory

Regardless of what kind of query it is, every query implements the following three methods specified by QueryDefinition:

• setDirectory(),
• setCollections(), and
• setOptionsName()

(as well as their get* counterparts). The first two -— setDirectory() and setCollections() —- allow you to restrict a query to a particular directory or set of collections. The last one, setOptionsName(), lets you associate a query with a named set of custom search options stored on the server. (See "Custom search" below.)

Example_19_SearchDirectory.java shows an example of the first method:

// Restrict the search to a specific directory query.setDirectory("/images/2012/02/14/"); // empty search defaults to returning all results query.setCriteria("");

When you run the program, it will search only those documents in the "/images/2012/02/14/" directory.

Search within a collection

Similarly, the query in Example_20_SearchCollection.java restricts a search to a collection, thanks to the setCollections() method:

// Restrict the search to the "shakespeare" collection query.setCollections("shakespeare"); // Search for the term "flower" query.setCriteria("flower");

When you run the program, the query will return only the matches that it finds in the "shakespeare" collection.