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',
            ],
        },
    );

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',
    );

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],
    }