NAME

Kernel::System::DocumentSearch::Base – Base class to handle connections and requests to Elasticsearch clusters.

PUBLIC INTERFACE

Provides methods to handle connections to Elasticsearch clusters, based on the OTRS configuration in Kernel::Config::Defaults or Kernel::Config.

To handle connections, requests and responses, this class makes use of the official Elasticsearch client implementation for perl. For more information, please see https://metacpan.org/pod/Search::Elasticsearch.

has Client

Attribute that holds the instantiated Elasticsearch client object.

has Drivers

Attribute that holds the instantiated index driver objects. The different index driver modules are located below Kernel::System::DocumentSearch::Driver::*, please refer to the single modules for more information about their usage.

has Version

Attribute that holds information about the current Elasticsearch version.

    {
        Major => 7,
        Minor => 9,
        Patch => 0,
    }

has ClientVersion

Attribute that holds information about the current Elasticsearch client version.

    {
        Major => 7,
        Minor => 3,
        Patch => 0,
    }

Connect()

Method that acts as a builder method for the 'Client' attribute. It will be called automatically to gather the Elasticsearch client specific configuration, instantiate the client object and initially connect to the related cluster.

This method returns the instantiated and connected client object, which will be then stored in the Client attribute for further usage.

Ping()

Method that sends a small request to check the availability of the cluster.

    my $Success = $DocumentSearchBaseObject->Ping();

Returns a true value, if the cluster is available and undef, if not.

ClusterInfo()

Method that gathers some basic cluster information.

    my $ClusterInfo = $DocumentSearchBaseObject->ClusterInfo();

Returns:

    {
        'name'         => 'my_node_name',
        'cluster_name' => 'my_cluster_name',
        'cluster_uuid' => 'Q15EUl-9Tr66c03kfeeHQw',
        'version' => {
            'build_snapshot'                      => bless( do{\(my $o = 0)}, 'JSON::PP::Boolean' ),
            'number'                              => '6.3.0',
            'minimum_wire_compatibility_version'  => '5.6.0',
            'build_flavor'                        => 'default',
            'lucene_version'                      => '7.3.1',
            'minimum_index_compatibility_version' => '5.0.0',
            'build_hash'                          => '424e937',
            'build_date'                          => '2018-06-11T23:38:03.357887Z',
            'build_type'                          => 'deb'
        },
        'tagline' => 'You Know, for Search'
    }

ClusterHealth()

Method that gathers information about the cluster internals (the cluster health).

    my $ClusterHealth = $DocumentSearchBaseObject->ClusterHealth(
        Level => 'string',          # optional, 'cluster' | 'indices' | 'shards'
    );

Returns:

    {
        'task_max_waiting_in_queue_millis' => 0,
        'unassigned_shards'                => 50,
        'timed_out'                        => bless( do{\(my $o = 0)}, 'JSON::PP::Boolean' ),
        'cluster_name'                     => 'my_cluster_name',
        'active_shards'                    => 51,
        'status'                           => 'yellow',
        'number_of_in_flight_fetch'        => 0,
        'number_of_data_nodes'             => 1,
        'relocating_shards'                => 0,
        'active_primary_shards'            => 51,
        'delayed_unassigned_shards'        => 0,
        'active_shards_percent_as_number'  => '50.4950495049505',
        'initializing_shards'              => 0,
        'number_of_pending_tasks'          => 0,
        'number_of_nodes'                  => 1
    }

Indices level returns additionally: { # … 'indices' => { 'otrs_ticket' => { 'status' => "yellow", 'number_of_shards' => 10, 'number_of_replicas' => 1, 'active_primary_shards' => 10, 'active_shards' => 10, 'relocating_shards' => 0, 'initializing_shards' => 0, 'unassigned_shards' => 10, }, # … }, }

Shards level returns additionally per index:

    {
        # ...
        'indices' => {
            'otrs_ticket' => {
                # ...
                'shards' => {
                    '0' =>  {
                        'status' => "yellow",
                        'primary_active' => true,
                        'active_shards' => 1,
                        'relocating_shards' => 0,
                        'initializing_shards' => 0,
                        'unassigned_shards' => 1
                    },
                },
            },
            # ...
        },
    }

ClusterState()

Method that gathers a very huge and detailed load of information about the cluster. Those information includes i.e. installed plugins, number of nodes, node details etc.

    my $ClusterState = $DocumentSearchBaseObject->ClusterState(
        Indices => ['string', 'string' ],   # optional
        Metrics => ['string', 'string' ],   # optional '_all' | 'blocks' | 'metadata' | 'nodes'
                                            #   | 'routing_table'
    );

The returned information are stored in a hash reference. For more detailed information about the cluster state, please refer to https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-state.html.

IndicesStats()

Method that gathers detail information about the existing indices in the connected cluster. Those information includes i.e. index names, sizes, memory usage, segment details etc.

    my $IndicesStats = $DocumentSearchBaseObject->IndicesStats(
        Indices => ['string', 'string' ],   # optional (requires Metrics)
        Metrics => ['string', 'string' ],   # optional '_all' | 'completion' | 'docs' | 'fielddata'
                                            #   | 'filter_cache' | 'flush' | 'get' | 'id_cache'
                                            #   | 'indexing' | 'merge' | 'percolate'
                                            #   | 'query_cache' | 'refresh' | 'request_cache'
                                            #   | 'search' | 'segments' | 'store'
    );

The returned information are stored in a hash reference. For more detailed information about the cluster state, please refer to https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-stats.html.

NodesInfo()

Method that gathers detail information about the existing nodes in the connected cluster. Those information includes i.e. node names, available plugins, versions etc.

    my $NodesInfo = $DocumentSearchBaseObject->NodesInfo(
        NodeIDS ['string', 'string'],   # optional,
        Metrics ['string', 'string'],   # optional,
    );

The returned information are stored in a hash reference.

For more detailed information about the cluster state, please refer to https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-nodes-info.html.

NodesVersionStatus()

Method that returns status information about the available nodes of the connected cluster:

    my $NodesVersionStatus = $DocumentSearchBaseObject->NodesVersionStatus();

Returns:

    [
        {
            'JVM' => {
                'Version' => '1.8.0_171',
                'Success' => 1,
                'Message' => undef
            },
            'RequiredPlugins' => {
                'Plugins' => {
                    'ingest-attachment' => {
                        'Success' => 1,
                        'Status' => 'Installed'
                    }
                },
                'Success' => 1
            },
            'NodeUUID'      => 'iOwC4EaqSWClbisTjmQJgQ',
            'Name'          => 'my_node_name',
            'Master'        => 'Yes',
            'Elasticsearch' => {
                'Message' => undef,
                'Success' => 1,
                'Version' => '6.3.0'
            },
        },
    ]

PerformRequest()

The official Elasticsearch client for perl supports nearly all API's provided by Elasticsearch. Nevertheless there might be situations and problems, that can't be handled using the normal API implementation of the client and thus needs to covered by manual REST structures processed by the cluster.

This method provides the possibility to send arbitrary REST bodies to the cluster, using the provided set of HTTP methods, paths and query strings, that are interpreted by the Elasticsearch.

    my $Result = $DocumentSearchBaseObject->PerformRequest(
        Method => 'GET',
        Path   => '/my_index/my_index_type/my_id',
        Body   => {
            UsefulKey => 'WithUsefulValues',
        },
    );

This method returns the result converted JSON reply to a perl structure.

For more information about the supported API's and it's usage, please refer to https://metacpan.org/pod/Search::Elasticsearch.

PipelineSet()

Creates a pipeline entry in the Elasticsearch cluster, to be used during the indexing process.

    my $Success = $DocumentSearchBaseObject->PipelineSet(
        ID   => 'some_unique_pipeline_name',
        Body => {
            description => 'Useful description what this pipeline does.',
            processors  => [
                # some processors, that handles data to be indexed.
            ],
        },
    );

Returns 1 if the pipeline creation was successful and 0, if not.

For more information about pipelines and it's usage, please refer to https://www.elastic.co/guide/en/elasticsearch/reference/current/pipeline.html.

PipelineGet()

Returns a pipeline entry by id (pipeline name).

    my $Pipeline = $DocumentSearchBaseObject->PipelineGet(
        ID => 'some_unique_pipeline_name',      # optional
    );

PipelineDelete()

Deletes a pipeline entry by id (pipeline name).

    my $Success = $DocumentSearchBaseObject->PipelineDelete(
        ID => 'some_unique_pipeline_name',
    );

Returns a true value, if the deletion was successful and undef, if not.

PipelineSimulate()

Simulates the execution of a pipeline and returns the result, which would be normally indexed directly.

    my $Result = $DocumentSearchBaseObject->PipelineSimulate(
        ID   => 'some_unique_pipeline_name',
        Body => {
            # some keys and values which would be indexed via the pipleline.
        },
    );

Returns the result, that would normally be indexed directly.

PipelineList()

Method that returns a list of all existing pipelines:

    my $PipelineList = $DocumentSearchBaseObject->PipelineList(
        Result => 'ARRAY' || 'HASH', # optional, Result type, default: ARRAY
    );

Returns:

    [
        Attachment,
        SomePipeline,
        # ...
    ]

or

    {
        Attachment   => 1,
        SomePipeline => 1,
        # ...
    }

IndexList()

Method that returns a list of all existing indices with related index driver names:

    my $List = $DocumentSearchBaseObject->IndexList();

Returns:

    [
        {
            'IndexName'   => 'otrs_article_chat'
            'IndexDriver' => 'ArticleChat',
        },
        {
            'IndexName'   => 'otrs_article_mime'
            'IndexDriver' => 'ArticleMIME',
        },
        {
            'IndexName'   => 'otrs_article_sms'
            'IndexDriver' => 'ArticleSMS',
        },
        {
            'IndexName'   => 'otrs_faq',
            'IndexDriver' => 'FAQ'
        },
        {
            'IndexName'   => 'otrs_ticket',
            'IndexDriver' => 'Ticket'
        }
    ]

IndexLookup()

Method that looks up the index name by DocumentType or document type by IndexName:

    my $IndexName = $DocumentSearchBaseObject->IndexLookup(
        DocumentType => 'Ticket',
    );

Returns the related index name or undef in case it was not found.

    my $DocumentType = $DocumentSearchBaseObject->IndexLookup(
        IndexName => 'otrs_ticket',
    );

Returns the related document type or undef in case it was not found.

IndexExists()

Method that verifies, if a particular index exists on the Elasticsearch server:

    my $Success = $DocumentSearchBaseObject->IndexExists(
        DocumentType => 'Ticket',       # Either DocumentType or IndexName must be given.
        IndexName    => 'otrs_ticket',
    );

Returns 1 if the related index exists and 0, if not.

DriverList()

Method that returns a list of all existing index drivers:

    my $DriverList = $DocumentSearchBaseObject->DriverList(
        Result  => 'ARRAY' || 'HASH', # optional, Result type, default: ARRAY
        Virtual => 0,                 # optional, include virtual drivers, default: 0
    );

Returns:

    [
        ArticleChat,
        ArticleMIME,
        ArticleSMS,
        FAQ,
        Ticket
    ]

or

    {
        ArticleChat => 1,
        ArticleMIME => 1,
        ArticleSMS  => 1,
        FAQ         => 1,
        Ticket      => 1
    }

_DriverGet()

Returns the instantiated index driver object, that can be used to gather information for a certain DocumentType.

    my $IndexDriver = $DocumentSearchBaseObject->_DriverGet('Ticket');

Returns the instantiated index driver object.

_VersionCheck()

Checks if the given version matches a required version.

    my $Result = $DocumentSearchBaseObject->_VersionCheck(
        CurrentVersion   => '5.3.0',
        RequiredVersion  => '6.3.0',
        LowerThanVersion => '7.0.0',
    );

Returns:

    {
        Success => 0,
        Version => '5.3.0',
        Message => "Version 5.3.0 installed but 6.3.0 or higher is required!",
    }

_VersionClean()

Converts a version string to a format, that can be compared.

    my $CleanedVersion = $DocumentSearchBaseObject->_VersionClean(
        Version  => '5.3.0',
    );

Returns:

    530

_BuildVersion()

Requests the Elasticsearch version from the cluster and splits it into major, minor and patch parts.

Returns:

    {
        Major => 7,
        Minor => 9,
        Patch => 0,
    }

_BuildClientVersion()

Detects the used client module version and splits it into major, minor and patch parts.

Returns:

    {
        Major => 7,
        Minor => 3,
        Patch => 0,
    }