202 lines
4.4 KiB
Markdown
202 lines
4.4 KiB
Markdown
# Query String Syntax
|
|
|
|
## Basics
|
|
|
|
Single words are treated as simple terms. The results will include
|
|
documents containing those terms, eg:
|
|
|
|
embiggen
|
|
cromulent
|
|
|
|
Terms are separated by spaces, so:
|
|
|
|
navel orange
|
|
|
|
Will match both documents containing "navel" and documents containing "orange",
|
|
which is probably not what was intended. The user was probably looking for
|
|
documents about "navel oranges" rather than those about "orange navels".
|
|
|
|
To search for phrases - multiple words, matched in order - enclose them in double quotes.
|
|
|
|
For example:
|
|
|
|
"navel orange"
|
|
|
|
## Boolean Operators
|
|
|
|
### `OR`
|
|
|
|
The `OR` operator returns documents matched by terms on either side of it.
|
|
It is the default operator, meaning that the following two queries are
|
|
considered to be equivalent:
|
|
|
|
orange OR "navel orange"
|
|
orange "navel orange"
|
|
|
|
Note that the query parser can be set up to use `AND` as the default operator instead of `OR`.
|
|
|
|
### `AND`
|
|
|
|
'`AND`' returns documents which match the terms on *both* sides.
|
|
|
|
orange AND citrus
|
|
|
|
### `+`
|
|
|
|
'`+`' is the 'required' operator. A term prefixed with '`+`' must exist in matching
|
|
documents.
|
|
|
|
For example, to return documents definitely containing "orange" and maybe also
|
|
containing "fruit":
|
|
|
|
fruit +orange
|
|
|
|
|
|
### `NOT`
|
|
|
|
`NOT` excludes documents that match the following term.
|
|
|
|
For example, to match documents containing "orange" but not "paint":
|
|
|
|
orange NOT paint
|
|
|
|
|
|
### `-`
|
|
|
|
Prefixing a term with '`-`' will "prohibit" it.
|
|
|
|
For example, to match documents containing "orange" but not "paint":
|
|
|
|
orange -paint
|
|
|
|
|
|
### Precedence
|
|
|
|
`-`, `+` and `NOT` take precedence over `AND`, which takes precedence over `OR`.
|
|
|
|
For example,
|
|
|
|
lemon OR orange AND citrus
|
|
|
|
is treated as:
|
|
|
|
lemon OR (orange AND citrus)
|
|
|
|
|
|
|
|
## Field Scoping
|
|
|
|
You can control which fields are matched by prefixing the name of a field separated by a colon.
|
|
|
|
Examples:
|
|
|
|
genus:citrus
|
|
headline:"How to Make the Perfect Negroni"
|
|
tags:(fruit OR paint)
|
|
|
|
If no field is specified, the default `_all` is used, unless overridden in the index mapping.
|
|
|
|
|
|
## Grouping
|
|
|
|
Parentheses can be used to group sub queries.
|
|
For example:
|
|
|
|
(shaddock OR pomelo OR pamplemousse) AND (family:rutaceae AND NOT genus:fortunella) AND colour:(greenish OR yellowish)
|
|
|
|
## Wildcards
|
|
|
|
Within an individual term, partial matches can be described using wildcard characters:
|
|
|
|
`?` to match any single character
|
|
|
|
`*` To match and sequence of zero or more characters
|
|
|
|
For example:
|
|
|
|
qu?ck bro*
|
|
|
|
|
|
## Fuzziness
|
|
|
|
A fuzzy query is a term query that matches terms within a given [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance).
|
|
The edit distance is the number of single-character edits (insertions, deletions or substitutions) allowed.
|
|
|
|
To specify a fuzzy query, use the tilde sign (`~`), optionally followed by the edit distance you'll accept.
|
|
|
|
|
|
For example,
|
|
|
|
colour~1
|
|
|
|
to match "`colour`" or "`color`" (or "`zolour`" or "`colours`"... but not "`colors`", as the `~1` allows only a single character change).
|
|
|
|
If no number is specified, the default value is 1, so the following are equivalent:
|
|
|
|
wibble~
|
|
wibble~1
|
|
|
|
|
|
|
|
## Boosting
|
|
|
|
Boosting a term doesn't affect the set of matching documents, but it does
|
|
indicate that that term should be assigned greater importance when the
|
|
results are being scored by relevance.
|
|
|
|
To boost a term, you use the boost operator '`^`' followed by a number
|
|
indicating the relative importance of the term.
|
|
|
|
For example, in the following query, "grapefruit" should be considered twice
|
|
as important as "lime":
|
|
|
|
grapefruit^2 lime
|
|
|
|
You can boost more complex sub queries:
|
|
|
|
(grapefruit OR orange)^2 "navel orange"^4 genus:citrus
|
|
|
|
|
|
|
|
## Ranges
|
|
|
|
Inclusive ranges can be described with square braces and `TO`, eg:
|
|
|
|
num:[1 TO 5]
|
|
date:[2010-01-01 TO 2010-01-31]
|
|
|
|
Dates must be in `YYYY-MM-DD` form.
|
|
|
|
Exclusive ranges are supported using curly braces. So, these are equivalent:
|
|
|
|
score:{0 TO 10}
|
|
score:[1 TO 9]
|
|
|
|
|
|
|
|
You can mix inclusive and exclusive endpoints, eg:
|
|
|
|
pubdate:[2010-01-01 TO 2011-01-01}
|
|
shoesize:{0 TO 16]
|
|
byte:[0 TO 256}
|
|
|
|
You can have open ranges by leaving off either endpoint:
|
|
|
|
pubdate:[2000-01-01 TO ]
|
|
temp:[TO 100}
|
|
|
|
|
|
NOTE: ranges currently work only on numeric and date fields.
|
|
|
|
|
|
## Relational Operators
|
|
|
|
You can perform numeric comparisons using the `>`, `>=`, `<`, and `<=` operators.
|
|
These are equivalent to using the above range syntax with unbounded ranges.
|
|
|
|
For example:
|
|
|
|
score:>=100
|
|
score:[ TO 100]
|
|
|
|
|