Basic Search

Now that we've populated our database, let's start taking advantage of MarkLogic's real power: search/query. 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.

String and structured queries are executed using the /search endpoint. We can also look for content using an example of what we want to find, using the /qbe endpoint (Query By Example).

Find JSON documents by example

Start by finding all the conference talks by speakers who work for MarkLogic-—in other words, all the JSON documents that have this key/value pair: {"affilliation": "MarkLogic"}. To do that, you use the /qbe endpoint:

http://localhost:8011/v1/qbe?query={affiliation:%22MarkLogic%22}&format=json

You can also get the results back in XML format:

http://localhost:8011/v1/qbe?query={affiliation:"MarkLogic"}&format=xml

Regardless of which format you choose, the results include references to, and snippets of, the first 10 matching JSON documents.

Find XML documents by example

You can also search by element value using the /qbe endpoint. Here you're searching for all Shakespeare plays that feature the King of France:

If your XML documents use namespaces (unlike our sample Shakespeare docs), then you'll first need to use the /config/namespaces endpoint to configure a namespace prefix binding.

Find documents using a search string

Now let's use the /search endpoint to perform a string search using the q parameter:

In either format, the search returns the first 10 results, each of which includes snippets of text that matched the query.

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, the 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.

Get another page of search results

All the previous examples returned the first 10 most-relevant results. Now let's get the third 5 most relevant results. In other words, let's use a smaller page size (5 results per page) and ask for the third page of results. Use the pageLength parameter to override the default size (10), and the start parameter to indicate the index of the first result to return:

Now the search results yield a maximum page size of 5, starting at the 11th result (effectively the third page).

Find documents based on their properties

You've now seen string-based queries and QBE queries. One example of a structured query (the third kind of query) is what you need for searching properties (at least without defining a constraint option, which we'll be doing in the next section). To use a structured query, you POST it using either JSON or XML format. Copy, paste, and execute the following command:

curl -v -X POST \
--digest --user rest-writer:x \
-d'{"query":{"properties-query":{"term-query":{"text":"fish"}}}}' \
-H "Content-type: application/json" \
'http://localhost:8011/v1/search?format=json'

The above command uses a JSON-based structured query to find all photos of fish (searching the extracted image metadata for "fish"). Here's the same query using the XML format:

curl -v -X POST \
  --digest --user rest-writer:x \
  -d'<query xmlns="http://marklogic.com/appservices/search"><properties-query><term-query><text>fish</text></term-query></properties-query></query>' \
  -H "Content-type: application/xml" \
  'http://localhost:8011/v1/search'

You can also do this with a GET request, using the structuredQuery parameter with the (URL-encoded) structured query in either XML or JSON:

http://localhost:8011/v1/search?structuredQuery=%7b%22query%22:%7b%22properties-query%22:%7b%22term-query%22:%7b%22text%22:%22fish%22%7d%7d%7d%7d&format=json

This example hints at the richness of the query language as well as the complexity that string queries hide for you, using the default search grammar. For more details, see Using Structured Search in the Search Developer's Guide.

Search within a directory

To search within a directory, use the directory parameter. Since the q parameter is absent, the following search will find all documents in the given directory:

Search within a collection

Similarly, the collection parameter restricts a search to a particular collection. This query finds all mentions of "flower" in the "shakespeare" collection:

We've now seen how to perform some basic searches. Now let's look more closely at the results format.

CRUD

Understanding search results

Contents