CirrusSearch
Elasticsearch-powered search for MediaWiki
Loading...
Searching...
No Matches
CirrusSearch\Query\KeywordFeature Interface Reference

Definition of a search keyword. More...

+ Inheritance diagram for CirrusSearch\Query\KeywordFeature:

Public Member Functions

 getKeywordPrefixes ()
 List of keyword strings this implementation consumes.
 
 allowEmptyValue ()
 Whether this keyword allows empty value.
 
 hasValue ()
 Whether this keyword can have a value.
 
 greedy ()
 Whether this keyword is greedy consuming the rest of the string.
 
 queryHeader ()
 Whether this keyword can appear only at the beginning of the query (excluding spaces)
 
 getFeatureName ( $key, $valueDelimiter)
 Determine the name of the feature being set in SearchContext::addSyntaxUsed Defaults to $key.
 
 getValueDelimiters ()
 List of value delimiters supported (must be an array of single byte char)
 
 parseValue ( $key, $value, $quotedValue, $valueDelimiter, $suffix, WarningCollector $warningCollector)
 Parse the value of the keyword.
 
 getCrossSearchStrategy (KeywordFeatureNode $node)
 Get support strategy for cross searching.
 
 expand (KeywordFeatureNode $node, SearchConfig $config, WarningCollector $warningCollector)
 Expand the keyword potentially accessing external resources.
 
 apply (SearchContext $context, $term)
 Checks $term for usage of the feature, and applies necessary filters, rescores, etc.
 

Detailed Description

Definition of a search keyword.

This interface is being actively refactored, the initial behavior is to do all the work in the function apply( SearchContext $context, $term ).

The aim is to clearly separate the parsing logic from the query building logic.

  • AST generation and parsing: must be idempotent and depend as little as possible on configuration variables. Output of the parsing will be KeywordFeatureNode.
  • CrossSearchStrategy evaluation
  • Expansion: for keyword needing to fetch external resources.
  • Query building

The parsing behavior can be defined using the following methods:

  • getKeywordPrefixes()
  • allowEmptyValue()
  • hasValue()
  • greedy()
  • queryHeader()
  • getValueDelimiters()
  • parseValue()

The keyword can define its CrossSearchStrategy to decide whether or not a query using this keyword can be applied to external wikis indices.

For keywords that need to fetch data from external resource the method expand( KeywordFeatureNode $node, SearchConfig $config, WarningCollector $warningCollector ) can be used. Its return value will be made in a context available during query building.

A keyword must not directly implement this interface but extends SimpleKeywordFeature.

NOTE: since this interface is being refactored it's highly recommended to use and implement the dedicated method in the old all-in-one apply strategy (This "apply" strategy will be removed).

See also
SimpleKeywordFeature
CrossSearchStrategy
KeywordFeatureNode

Member Function Documentation

◆ allowEmptyValue()

CirrusSearch\Query\KeywordFeature::allowEmptyValue ( )

Whether this keyword allows empty value.

Returns
bool true to allow the keyword to appear in an empty form

Implemented in CirrusSearch\Query\PreferRecentFeature, and CirrusSearch\Query\SimpleKeywordFeature.

◆ apply()

CirrusSearch\Query\KeywordFeature::apply ( SearchContext $context,
$term )

Checks $term for usage of the feature, and applies necessary filters, rescores, etc.

to the provided $context. The returned $term will be passed on to other keyword features, and eventually to an elasticsearch QueryString query.

Parameters
SearchContext$context
string$termThe input search query
Returns
string The remaining search query after processing

Implemented in CirrusSearch\Query\SimpleKeywordFeature.

◆ expand()

CirrusSearch\Query\KeywordFeature::expand ( KeywordFeatureNode $node,
SearchConfig $config,
WarningCollector $warningCollector )

Expand the keyword potentially accessing external resources.

Keywords that need to access the DB or any other external resources should implement this method. NOTE: this method will be called on every external wikis the search request will be made to.

Parameters
KeywordFeatureNode$node
SearchConfig$config
WarningCollector$warningCollector
Returns
array a state containing the data the keyword fetched from an external resource The format of this array is only known by the keyword implementation and is stored in the query building context.

Implemented in CirrusSearch\Query\DeepcatFeature, CirrusSearch\Query\InCategoryFeature, CirrusSearch\Query\MoreLikeFeature, and CirrusSearch\Query\SimpleKeywordFeature.

◆ getCrossSearchStrategy()

◆ getFeatureName()

CirrusSearch\Query\KeywordFeature::getFeatureName ( $key,
$valueDelimiter )

Determine the name of the feature being set in SearchContext::addSyntaxUsed Defaults to $key.

Parameters
string$key
string$valueDelimiterthe delimiter used to wrap the value
Returns
string '"' when parsing keyword:"test" '' when parsing keyword:test

Implemented in CirrusSearch\Query\BaseRegexFeature, CirrusSearch\Query\DeepcatFeature, CirrusSearch\Query\MoreLikeFeature, CirrusSearch\Query\MoreLikeThisFeature, and CirrusSearch\Query\SimpleKeywordFeature.

◆ getKeywordPrefixes()

CirrusSearch\Query\KeywordFeature::getKeywordPrefixes ( )

List of keyword strings this implementation consumes.

Returns
string[]

Implemented in CirrusSearch\Query\SimpleKeywordFeature.

◆ getValueDelimiters()

CirrusSearch\Query\KeywordFeature::getValueDelimiters ( )

List of value delimiters supported (must be an array of single byte char)

Returns
string[][] list of delimiters options

Implemented in CirrusSearch\Query\BaseRegexFeature, and CirrusSearch\Query\SimpleKeywordFeature.

◆ greedy()

CirrusSearch\Query\KeywordFeature::greedy ( )

Whether this keyword is greedy consuming the rest of the string.

NOTE: do not use, greedy keywords will eventually be removed in the future

Returns
bool

Implemented in CirrusSearch\Query\MoreLikeFeature, CirrusSearch\Query\PrefixFeature, and CirrusSearch\Query\SimpleKeywordFeature.

◆ hasValue()

CirrusSearch\Query\KeywordFeature::hasValue ( )

Whether this keyword can have a value.

Returns
bool

Implemented in CirrusSearch\Query\LocalFeature, and CirrusSearch\Query\SimpleKeywordFeature.

◆ parseValue()

CirrusSearch\Query\KeywordFeature::parseValue ( $key,
$value,
$quotedValue,
$valueDelimiter,
$suffix,
WarningCollector $warningCollector )

Parse the value of the keyword.

NOTE: this function called prior to creating the node in the AST. It is not allowed to call external resources here (db, elastic, others). The data known by this method should only be the value contained in the user query string and maybe few config vars for sanity check purposes.

Parameters
string$keyThe keyword
string$valueThe value attached to the keyword with quotes stripped and escaped quotes un-escaped.
string$quotedValueThe original value in the search string, including quotes if used
string$valueDelimiterthe delimiter char used to wrap the keyword value ('"' in intitle:"test")
string$suffixthe optional suffix used after the value ('i' in insource:/regex/i)
WarningCollector$warningCollector
Returns
array|null|false an array kept containing the information parsed, null when nothing is to be kept false when the value is refused (only allowed for keywords that allows empty value)
See also
self::allowEmptyValue

Implemented in CirrusSearch\Query\ArticleTopicFeature, CirrusSearch\Query\BaseRegexFeature, CirrusSearch\Query\BoostTemplatesFeature, CirrusSearch\Query\FileTypeFeature, CirrusSearch\Query\HasRecommendationFeature, CirrusSearch\Query\HasTemplateFeature, CirrusSearch\Query\InCategoryFeature, CirrusSearch\Query\IndexedNumericFieldFeature, CirrusSearch\Query\LanguageFeature, CirrusSearch\Query\PageIdFeature, CirrusSearch\Query\PreferRecentFeature, CirrusSearch\Query\PrefixFeature, CirrusSearch\Query\SimpleKeywordFeature, and CirrusSearch\Query\SubPageOfFeature.

◆ queryHeader()

CirrusSearch\Query\KeywordFeature::queryHeader ( )

Whether this keyword can appear only at the beginning of the query (excluding spaces)

Returns
bool

Implemented in CirrusSearch\Query\LocalFeature, CirrusSearch\Query\MoreLikeFeature, and CirrusSearch\Query\SimpleKeywordFeature.


The documentation for this interface was generated from the following file: