/ 
OpenSearch-Client-3.007004
/ OpenSearch::Client::Manual::Basics

OpenSearch::Client::Manual::Basics

Basic use of OpenSearch::Client

Creating a new instance

The 'new' method returns a new client which can be used to run requests against the OpenSearch cluster.

use OpenSearch::Client;
my $os = OpenSearch::Client->new( %params );

The most important arguments to 'new' are the following:

nodes

The nodes parameter tells the client which OpenSearch nodes it should talk to. It can be a single node, multiples nodes or, if not specified, will default to localhost:9200:

# default: localhost:9200
$os = OpenSearch::Client->new();

# single
$os = OpenSearch::Client->new( nodes => 'search_1:9200');

# multiple
$os = OpenSearch::Client->new(
    nodes => [
        'search_1:9200',
        'search_2:9200'
    ]
);

Each node can be a URL including a scheme, host, port, and path. For instance, this would be a valid node:

https://search.domain.com:443/prefix/path

See "node" in OpenSearch::Client::Role::Cxn for more on node specification.

cxn_pool

The CxnPool modules manage connections to nodes in the OpenSearch cluster. They handle the load balancing between nodes and failover when nodes fail. Which CxnPool you should use depends on where your cluster is. There are three choices:

  • Static

    $os = OpenSearch::Client->new(
    cxn_pool => 'Static'     # default
    nodes    => [
        'search1.domain.com:9200',
        'search2.domain.com:9200'
    ],
);

    The Static connection pool, which is the default, should be used when you don't have direct access to the OpenSearch cluster, eg when you are accessing the cluster through a proxy. See OpenSearch::Client::CxnPool::Static for more.

  • Sniff

    $os = OpenSearch::Client->new(
    cxn_pool => 'Sniff',
    nodes    => [
        'search1:9200',
        'search2:9200'
    ],
);

    The Sniff connection pool should be used when you do have direct access to the OpenSearch cluster, eg when your web servers and OpenSearch servers are on the same network. The nodes that you specify are used to discover the cluster, which is then sniffed to find the current list of live nodes that the cluster knows about. See OpenSearch::Client::CxnPool::Sniff.

  • Static::NoPing

    $os = OpenSearch::Client->new(
    cxn_pool => 'Static::NoPing'
    nodes    => [
        'proxy1.domain.com:80',
        'proxy2.domain.com:80'
    ],
);

    The Static::NoPing connection pool should be used when your access to a remote cluster is so limited that you cannot ping individual nodes with a HEAD / request.

    See OpenSearch::Client::CxnPool::Static::NoPing for more.

trace_to

For debugging purposes, it is useful to be able to dump the actual HTTP requests which are sent to the cluster, and the response that is received. This can be enabled with the trace_to parameter, as follows:

# To STDERR
$os = OpenSearch::Client->new(
    trace_to => 'Stderr'
);

# To a file
$os = OpenSearch::Client->new(
    trace_to => ['File','/path/to/filename']
);

Logging is handled by Log::Any. See OpenSearch::Client::Logger::LogAny for more information.

other

Other arguments are explained in the respective module docs.

Running Requests

When you create a new instance of OpenSearch::Client, it returns a client object, which can be used for running requests.

use OpenSearch::Client;
my $os = OpenSearch::Client->new( %params );

# create an index
$os->indices->create( index => 'my_index' );

# index a document
$os->index(
    index   => 'my_index',
    type    => 'blog_post',
    id      => 1,
    body    => {
        title   => 'OpenSearch clients',
        content => 'Interesting content...',
        date    => '2013-09-24'
    }
);

See OpenSearch::Client::Core::3_0::Direct for more details about the requests that can be run.

Modules

Each chunk of functionality is handled by a different module, which can be specified in the call to 'new' as shown in cxn_pool above. For instance, the following will use the OpenSearch::Client::CxnPool::Sniff module for the connection pool.

$os = OpenSearch::Client->new(
    cxn_pool => 'Sniff'
);

Custom modules can be named with the appropriate prefix, eg OpenSearch::Client::CxnPool::, or by prefixing the full class name with +:

$os = OpenSearch::Client->new(
    cxn_pool => '+My::Custom::CxnClass'
);

The modules that you can override are specified with the following arguments to 'new':

client

The class to use for the client functionality, which provides methods that can be called to execute requests, such as search(), index() or delete(). The client parses the user's requests and passes them to the "transport" class to be executed.

The default version of the client is 3_0::Direct, which can be explicitly specified as follows:

$os = OpenSearch::Client->new(
    client => '3_0::Direct'
);

transport

The Transport class accepts a parsed request from the "client" class, fetches a "cxn" from its "cxn_pool" and tries to execute the request, retrying after failure where appropriate. See:

cxn

The class which handles raw requests to OpenSearch nodes. See:

cxn_factory

The class which the "cxn_pool" uses to create new "cxn" objects. See:

cxn_pool

The class to use for the connection pool functionality. It calls the "cxn_factory" class to create new "cxn" objects when appropriate. See:

logger

The class to use for logging events and tracing HTTP requests/responses. See:

serializer

The class to use for serializing request bodies and deserializing response bodies. See:

MANUAL

Documentation index OpenSearch::Client::Manual

HISTORY

This distribution is derived from Search::Elasticsearch version 7.714. All subsequent changes are unique to this distribution.

AUTHOR

Mark Dootson <mdootson@cpan.org> ( current maintainer )

CREDITS

OpenSearch::Client is based on Search::Elasticsearch version 7.714 by Enrico Zimuel <enrico.zimuel@elastic.co>.

COPYRIGHT AND LICENSE

Copyright (C) 2026 by Mark Dootson ( this distribution )

Copyright (C) 2021 by Elasticsearch BV ( original distribution )

This is free software, licensed under:

The Apache License, Version 2.0, January 2004