зеркало из https://github.com/mozilla/kitsune.git
add advanced search documentation (#4800)
This commit is contained in:
Leo McArdle
GitHub
Родитель
02eb0ed032
Коммит
245cb9dd3e
|
|
@ -0,0 +1,350 @@
|
|||
# Advanced Search
|
||||
|
||||
```eval_rst
|
||||
.. contents:: :local:
|
||||
```
|
||||
|
||||
Kitsune supports an advanced search syntax in all its search boxes.
|
||||
|
||||
A number of search operators and tokens,
|
||||
described below,
|
||||
take a `{field_name}` as an argument.
|
||||
The valid field names for each of our document types are explained in the [Document Fields](#document-fields) section.
|
||||
|
||||
The most basic search token is simply an individual word.
|
||||
For example,
|
||||
the query `firefox crashes` contains two tokens `firefox` and `crashes`.
|
||||
|
||||
By default all simple tokens specified must exist in the same field in a document for it to be matched.
|
||||
So our `firefox crashes` query will only match a document with both `firefox` _and_ `crashes` in the same field.
|
||||
This behaviour can be modified using the operators below.
|
||||
|
||||
## Quoted Phrase
|
||||
|
||||
`"x y z"`
|
||||
|
||||
Matches the phrase,
|
||||
disabling synonym matching.
|
||||
|
||||
e.g. `"firefox accounts"`
|
||||
will match "firefox accounts" but not "firefox can't find my account".
|
||||
|
||||
e.g. `add-ons NOT "themes"`
|
||||
will match add-ons and extensions, but not themes.
|
||||
|
||||
## Field Operator
|
||||
|
||||
`field:{field_name}:{query}`
|
||||
|
||||
Specifies that `{query}` should be run against `{field_name}`.
|
||||
If enclosed in brackets,
|
||||
`{query}` can have nested operators.
|
||||
|
||||
e.g. `field:keywords.en-US:(firefox NOT android)`
|
||||
will find KB documents with `firefox` and without `android` in their keywords field.
|
||||
|
||||
### Aliases
|
||||
|
||||
Each document type has a number of aliases,
|
||||
shown below,
|
||||
which allows easy searching across document types.
|
||||
|
||||
e.g. using `field:title:firefox` in instant search would find both articles and questions with firefox in the title.
|
||||
|
||||
#### Knowledge Base Articles
|
||||
|
||||
```eval_rst
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Alias
|
||||
- Maps To
|
||||
* - ``title``
|
||||
- ``title.{locale}``
|
||||
* - ``content``
|
||||
- ``content.{locale}``
|
||||
```
|
||||
|
||||
#### Questions
|
||||
|
||||
```eval_rst
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Alias
|
||||
- Maps To
|
||||
* - ``title``
|
||||
- ``question_title.{current_locale}``
|
||||
* - ``content``
|
||||
- ``question_content.{current_locale}`` or ``answer_content.{current_locale}``
|
||||
* - ``question``
|
||||
- ``question_content.{current_locale}``
|
||||
* - ``answer``
|
||||
- ``answer_content.{current_locale}``
|
||||
```
|
||||
|
||||
#### Forum Posts
|
||||
|
||||
```eval_rst
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Field
|
||||
- Maps To
|
||||
* - ``title``
|
||||
- ``thread_title``
|
||||
```
|
||||
|
||||
## Boolean Operators
|
||||
|
||||
### NOT
|
||||
|
||||
`NOT x`
|
||||
|
||||
Specifies that the token must not exist in the document.
|
||||
|
||||
### AND
|
||||
|
||||
`x AND y`
|
||||
|
||||
Specifies that both tokens must exist in the document.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
A quirk of our current implementation is that ``x AND y`` can return more results than ``x y``.
|
||||
This is because ``x y`` requires both tokens to exist in the same field,
|
||||
whereas ``x AND y`` will match across fields.
|
||||
|
||||
e.g. with a document like so:
|
||||
::
|
||||
{
|
||||
"title": "x",
|
||||
"content": "y"
|
||||
}
|
||||
|
||||
``x y`` wouldn't match, but ``x AND y`` would.
|
||||
```
|
||||
|
||||
### OR
|
||||
|
||||
`x OR y`
|
||||
|
||||
Specifies that either token must exist in the document.
|
||||
|
||||
## Exact Value Query
|
||||
|
||||
`exact:{field_name}:{value}`
|
||||
|
||||
Specifies that `{value}` should exactly match the value of (or token in) `{field_name}`.
|
||||
|
||||
e.g. `exact:question_has_solution:false` will only match questions without solutions.
|
||||
|
||||
### Convenience Values
|
||||
|
||||
These fields take a value which will be mapped to the appropriate ID internally.
|
||||
|
||||
#### Knowledge Base Articles
|
||||
|
||||
```eval_rst
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Field
|
||||
- Valid values
|
||||
* - ``category``
|
||||
- ``troubleshooting``,
|
||||
``how-to``,
|
||||
``how-to-contribute``,
|
||||
``navigation``
|
||||
```
|
||||
|
||||
## Range Query
|
||||
|
||||
`range:{field_name}:{operator}:{value}`
|
||||
|
||||
Specifies that `{value}` should fall within the range of the value of `{field_name}`.
|
||||
`{field_name}` must be a date or numeric field.
|
||||
|
||||
`{operator}` can take the following values:
|
||||
* `gt` - greater than
|
||||
* `gte` - greater than or equal
|
||||
* `lt` - less than
|
||||
* `lte` - less than or equal
|
||||
|
||||
`{value}` can take the following formats:
|
||||
* a basic number e.g. `1`
|
||||
* a date in the form `yyyy-MM-dd`
|
||||
* a date and time in the form `yyyy-MM-dd'T'HH:mm:ss`
|
||||
* a [date math](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#date-math) value e.g. `now`, or `now-1d`
|
||||
|
||||
e.g. `range:question_created:gte:2021-05-27 AND range:question_created:lt:2021-05-28`
|
||||
will match questions created on 27th May 2021.
|
||||
|
||||
e.g. `range:question_created:gte:now-2d`
|
||||
will match questions created in the last two days.
|
||||
|
||||
## Brackets and Operator Precedence
|
||||
|
||||
The operators above are documented in the order they're evaluated.
|
||||
To adjust the order of evaluation,
|
||||
you can make use of brackets.
|
||||
|
||||
e.g. `NOT firefox OR crashes` will match documents which either don't have firefox in them, or have crashes in them. (This can also be expressed like `(NOT firefox) OR crashes`).
|
||||
|
||||
e.g. `NOT (firefox OR crashes)` will match documents which have neither firefox nor crashes in them.
|
||||
|
||||
## Document Fields
|
||||
|
||||
Fields below with a _Yes_ in the _Locale?_ column require a locale code after their field name.
|
||||
|
||||
e.g. to match against question content in English, you'll need to use `question_content.en-US`.
|
||||
|
||||
e.g. to match against answer content in German, you'll use to use `answer_content.de`.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
Currently you can't search in a locale other than the one you're using SUMO in.
|
||||
For instance, attempting to search for ``field:question_content.en-US:firefox`` on http://support.mozilla.org/de will return zero results.
|
||||
```
|
||||
|
||||
### Knowledge Base Articles
|
||||
|
||||
```eval_rst
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Field
|
||||
- Locale?
|
||||
- Type
|
||||
* - ``updated``
|
||||
-
|
||||
- Date
|
||||
* - ``product_ids``
|
||||
-
|
||||
- Array of Keywords
|
||||
* - ``topic_ids``
|
||||
-
|
||||
- Array of Keywords
|
||||
* - ``category``
|
||||
-
|
||||
- Keyword
|
||||
* - ``title``
|
||||
- Yes
|
||||
- Text
|
||||
* - ``content``
|
||||
- Yes
|
||||
- Text
|
||||
* - ``summary``
|
||||
- Yes
|
||||
- Text
|
||||
* - ``keywords``
|
||||
- Yes
|
||||
- Text
|
||||
* - ``slug``
|
||||
- Yes
|
||||
- Keyword
|
||||
* - ``doc_id``
|
||||
- Yes
|
||||
- Keyword
|
||||
```
|
||||
|
||||
### Questions
|
||||
|
||||
```eval_rst
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Field
|
||||
- Locale?
|
||||
- Type
|
||||
* - ``question_id``
|
||||
-
|
||||
- Keyword
|
||||
* - ``question_title``
|
||||
- Yes
|
||||
- Text
|
||||
* - ``question_creator_id``
|
||||
-
|
||||
- Keyword
|
||||
* - ``question_content``
|
||||
- Yes
|
||||
- Text
|
||||
* - ``question_created``
|
||||
-
|
||||
- Date
|
||||
* - ``question_updated``
|
||||
-
|
||||
- Date
|
||||
* - ``question_updated_by_id``
|
||||
-
|
||||
- Keyword
|
||||
* - ``question_has_solution``
|
||||
-
|
||||
- Boolean
|
||||
* - ``question_is_locked``
|
||||
-
|
||||
- Boolean
|
||||
* - ``question_is_archived``
|
||||
-
|
||||
- Boolean
|
||||
* - ``question_product_id``
|
||||
-
|
||||
- Keyword
|
||||
* - ``question_topic_id``
|
||||
-
|
||||
- Keyword
|
||||
* - ``question_taken_by_id``
|
||||
-
|
||||
- Keyword
|
||||
* - ``question_taken_until``
|
||||
-
|
||||
- Date
|
||||
* - ``question_tag_ids``
|
||||
-
|
||||
- Array of Keywords
|
||||
* - ``question_num_votes``
|
||||
-
|
||||
- Integer
|
||||
* - ``answer_content``
|
||||
- Yes
|
||||
- Array of Text
|
||||
* - ``locale``
|
||||
-
|
||||
- Keyword
|
||||
```
|
||||
|
||||
### Forum Posts
|
||||
|
||||
```eval_rst
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Field
|
||||
- Type
|
||||
* - ``thread_title``
|
||||
- Text
|
||||
* - ``thread_forum_id``
|
||||
- Keyword
|
||||
* - ``forum_slug``
|
||||
- Keyword
|
||||
* - ``thread_id``
|
||||
- Keyword
|
||||
* - ``thread_created``
|
||||
- Date
|
||||
* - ``thread_creator_id``
|
||||
- Keyword
|
||||
* - ``thread_is_locked``
|
||||
- Boolean
|
||||
* - ``thread_is_sticky``
|
||||
- Boolean
|
||||
* - ``content``
|
||||
- Text
|
||||
* - ``author_id``
|
||||
- Keyword
|
||||
* - ``created``
|
||||
- Date
|
||||
* - ``updated``
|
||||
- Date
|
||||
* - ``updated_by_id``
|
||||
- Keyword
|
||||
```
|
||||
|
|
@ -44,8 +44,8 @@ Part 3: SUMO
|
|||
sla
|
||||
architectural-decisions
|
||||
|
||||
Part 4: Administration
|
||||
======================
|
||||
Part 4: User Guide
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
@ -53,3 +53,4 @@ Part 4: Administration
|
|||
users
|
||||
questions
|
||||
badges
|
||||
advanced-search
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче