NAME
Kernel::System::DocumentSearch::IndexSearch – Backend to search Elasticsearch indices.
PUBLIC INTERFACE
Search()
Method that performs a search, in Elasticsearch indexes:
my $SearchResult = $IndexSearchObject->Search(
# Required, the document type to be used for search
# (all types are used without a special type).
DocumentType => [ 'Ticket', 'FAQ', ], # or 'ALL'
# Optional, 'OR' or 'AND', defaults to 'OR'.
DefaultOperator => 'OR',
# Optional, sort by field (default, sort by score).
Sort => [
{
Field => 'TicketID', # a sortable field
Order => 'Desc' # optional 'Desc' or 'Asc', defaults to 'Desc'
},
# ...
],
# Optional, used to define an offset from the first result what will be fetched, together
# with Size can be used for pagination, defaults to 0.
From => 123,
# Optional, number of results to be fetched, defaults to 10.
Size => '100',
# Optional, used for an alternative way to scroll forward pagination, must be set as
# it was returned from previous search.
SearchAfter => \@SearchAfterArrayRef,
# Optional, specifies fields that must be highlighted in the related search results.
# If undef, nothing will be highlighted.
# If 'ALL' is send, all matching fields will be highlighted.
# If field names specified, just those fields are highlighted.
HighlightResults => ['SomeField', 'SomeOther'], # or 'ALL'
# Optional, specifies the fields per DocumentType to be used for search execution.
# If not specified, the related fields capable for fulltext searches, are automatically
# detected and will be used during the search execution.
SearchFields => {
ArticleMIME => [ 'Subject', 'Body' ],
},
# Optional, specifies the fields, that will be included in the search results.
# If not set, the related DocumentID will be used for results.
ResultFields => {
ArticleMIME => [ 'ArticleID', 'MessageID' ],
},
# Optional, specifies extra search filters.
CustomFilters => {
must => [
{
term => { GroupID => 1 }
}
],
should => [
{
term => { User => 2 }
},
{
term => { User => 3 }
},
],
},
# Optional, prevents error logging, if set to 1 (default, 0).
# Errors will still be returned in failing search requests.
Silent => 1,
# Required, search query to be executed. By default, spaces in the string will be converted to the
# DefaultOperator unless an operator is specified between words. For further information, see
# L<https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html>.
Query => 'Some Search String',
# Agent search (UserID is required)
UserID => 123,
Permission => 'ro' || 'rw',
# Customer search (CustomerUserID is required)
CustomerUserID => 123,
Permission => 'ro' || 'rw',
# Public search - Query indices without being an agent or customer.
# This will just work on indices, that grant access to be queried by the public.
# Those indices may add custom filters if public users executes queries.
PublicUser => 1,
# Optional, add filters aggregation of possible pre-defined filters and return
# the document count of every pre-defined filter as well as the filter structure,
# including the identifiers per filter, that can be used in frontends.
# Default: 0
FilterAggregations => 1,
# Optional, includes the related pre-defined filters to the search query.
# The structure must contain the filter identifiers to be used per document type.
PredefinedFilters => {
Ticket => [
'StateTypeAgent',
'PriorityMedium',
],
},
# Optional, adds filter on the document type ( e.g. Article ).
# CollapseBy, will return unique result based on provided indexed field.
DocumentFilter => {
Article => [
{
CollapseBy => Ticket,
},
{
term => {
QueueID => 3,
},
},
],
}
);Returns:
$SearchResult = {
Ticket => {
Label => 'Tickets' # human readable document type label
Hits => 2, # number of elements returned (limited by Size parameter)
TotalHits => 123, # number of elements found
SearchAfter => [ # to be use for scroll forward pagination
'1.4239533',
undef,
],
Documents => [
{
DocumentID => 23, # DocumentID of the related DocumentType (default)
Score => '1.6594417', # Score (relevance) of the result hit.
Highlight => 'Some <em>text</em> part', # Hit highlighting (if requested).
},
{
DocumentID => 2,
Score => '1.4239533',
Highlight => 'Another <em>text</em> part',
}
],
},
FAQ => {
# ...
},
# ...
}ValidateQuery()
Method that performs a query validation in Elasticsearch:
my $Success = $IndexSearchObject->ValidateQuery(
# Optional, 'OR' or 'AND', defaults to 'OR'.
DefaultOperator => 'OR',
# Required, search query to be analyzed. By default, spaces in the string will be converted to the
# DefaultOperator unless an operator is specified between words. For further information, see
# L<https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html>.
Query => 'Some Search String',
# optional, otherwise the default body structure is used.
Body => { },
);
Defult body structure is:
{
query => {
query_string => {
fields => [ 'Field1', 'Field2', ... ], # Searchable fields for each DocumentType.
default_operator => $Param{DefaultOperator,
query => $Param{Query},
},
},
}Count
Performs a multi-query aggregation search across one or more document types using Elasticsearch, returning the document count for each query string provided.
my $Result = $Object->Count(
DocumentType => 'ArticleMIME', # or 'ALL'
QueryList => [ 'SearchStrA', 'SearchStrB' ],
SearchFields => {
ArticleMIME => [ 'Subject', 'Body' ],
# ...
},
Silent => 1, # Optional
);Optional attributes: SearchField is a list of fields to restrict the query matching for each document type. If omitted, all searchable fields will be used by default.
Silent, if true, suppresses error messages.
Returns:
@QueueList = ( 'QueueA', 'QueueB', 'QueueC' );Returns a hashref containing the document count for each query string per document type:
$Result = { 'SearchStrA' => { Ticket => 1, FAQ => 1, ArticleChat => 0, ITSMConfigItem => 1, ITSMService => 1, Appointment => 1, ArticleMIME => 0, ArticleSMS => 0 }, 'SearchStrB' => { ArticleSMS => 0, ArticleMIME => 1, ITSMConfigItem => 1, ITSMService => 0, ArticleChat => 0, FAQ => 0, Ticket => 1, Appointment => 1 }, };
If an error occurs during processing or the index is not available for a document type, an error message may be returned in the result structure for that document type.
PRIVATE INTERFACE
_GetMatchedDocuments()
Get all document IDs that match a given criteria:
my $SearchResult = $IndexSearchObject->_GetMatchedDocuments(
# Filter is a mandatory parameter it contains the given criteria.
# Each filter element must provide at least a 'term' or 'terms' key,
# 'term' provides a single match value,
# 'terms' provides multiple match values using an 'OR' condition among them.
# Each filter element uses an 'AND' condition among other filter elements.
Filter => [
{
term => {
'Some.Property' => 'some value',
}
}
{
terms => {
'Some.Property' => ['some value', 'some other',],
}
}
# ...
],
);Returns:
$SearchResult = {
Ticket => [ 1, 2, 3 ],
FAQ => [ 4, 5, 6],
}