Working with Lucene queries

With this new feature you will be able to create complex Lucene queries, so you won’t be limited by the current search form fields. But keep in mind this can be difficult unless you know how to write these queries. Let’s define a couple of items:

Terms: A query is broken up into terms and operators. A term is a single word like “cat” or “dog”. Multiple terms can be combined with boolean operators for a more specific query. For example:
Terminal window
```
cat AND dog
```
Fields: When you perform a Lucene search, you can specify a field or use the default field. In OpenKM, the default field contains the extracted document text. You can search a field by writing the field name, followed by a colon “:” and a term. For example, this query will search for all nodes in taxonomy whose name is “animals”:
Terminal window
```
context:okm_root AND name:animals
```

Term modifiers

Lucene supports different term modifiers to create complex searches.

Wildcard searches

You can use single and multiple character wildcard searches within terms.

Single: To perform a single-character wildcard search, use the “?” symbol. For example, to search for “text” or “test”:
Terminal window
```
te?t
```
Multiple: To perform a multiple-character wildcard search, use the “*” symbol. For example, to search for “test”, “tests” or “tester”:
Terminal window
```
test*
```

Proximity searches

Lucene also supports finding words that are within a specific distance. To perform a proximity search use the tilde “~” symbol at the end of the phrase.

For example, to search for a “cat” and “dog” within 10 words of each other in a document:

"cat dog"~

Range searches

Range queries allow you to match documents whose field values are between a specified lower and upper bound. Sorting is done lexicographically.

For example, to look for documents whose field “name” is between “cat” and “horse” but will not include these terms:

name:{cat TO horse}

If you want these two terms to be included, use this query:

name:[cat TO horse]

Boolean operators

You can combine several terms using boolean operators. Lucene supports “AND”, “+”, “OR”, “NOT” and “-”.

The “OR” operator is the default conjunction operator: this means that if there is no boolean operator between two terms, the “OR” operator is used. These two queries are equivalent:

cat animal

And this one:

cat OR animal

AND

The AND operator matches documents where both terms exist. The symbol “&&” can also be used to replace the word “AND”.

Let’s look for documents with both “cat” and “animal” words in the content:

cat AND animal

+

This is called the required operator and forces the term placed after the “+” to be included in the results.

For example, to search for documents that must contain “animal” and may contain “cat”:

+animal cat

NOT

The NOT operator excludes documents that contain the term after the “NOT”. The symbol “!” can be used to replace the word “NOT”.

For example, to search for documents that contain “animal” but not “cat”:

animal NOT cat

-

This operator excludes documents that contain the term given after the “-” character:

For example, to search for documents that contain “animal” but not “cat”:

animal -cat

Grouping

Lucene supports using parentheses to group clauses to form sub queries. This can be very useful if you want to control the boolean logic for a query.

For example, to search for “cat” or “dog” and “animal” use this query:

(cat OR dog) AND animal

Escaping special characters

Lucene supports escaping some special characters that are part of the query syntax using the slash “\” before the character to be escaped. This is the current list of special characters:

+ - && || ! ( ) { } [ ] ^ " ~ * ? : \

Working with metadata fields

Because OpenKM uses Lucene-restricted characters like “:”, the field name must be sanitized. For example, a field named in OpenKM as “okp:consulting.text” should be sanitized as “okp_consulting_text”, replacing the characters “:” and “.” with “_”.

okp_consulting_text:value