Per-request configuration
editPer-request configuration
editThere are several configurations that can be set on a per-request basis, rather than at a connection- or client-level. These are specified as part of the request associative array.
Request Identification
editYou can enrich your requests against Elasticsearch with an identifier string, that allows you to discover this identifier in deprecation logs, to support you with identifying search slow log origin or to help with identifying running tasks.
Ignoring exceptions
editThe library attempts to throw exceptions for common problems. These exceptions
match the HTTP response code provided by Elasticsearch. For example, attempting to GET a
nonexistent document will throw a Missing404Exception
.
Exceptions are a useful and consistent way to deal with problems like missing documents, syntax errors, version conflicts, and so on. But sometimes you want to deal with the response body rather than catch exceptions (often useful in test suites).
If you need that behavior, you can configure an ignore
parameter. You can
configure it in the client
parameter of the request array. For instance, the
example below ignores the Missing404Exception
exception and returns
the JSON provided by Elasticsearch instead.
$client = ClientBuilder::create()->build(); $params = [ 'index' => 'test_missing', 'id' => 1, 'client' => [ 'ignore' => 404 ] ]; echo $client->get($params); > {"_index":"test_missing","_type":"_doc","_id":"1","found":false}
You can specify multiple HTTP status codes to ignore by providing an array of values:
$client = ClientBuilder::create()->build(); $params = [ 'index' => 'test_missing', 'client' => [ 'ignore' => [400, 404] ] ]; echo $client->get($params); > No handler found for uri [/test_missing/test/] and method [GET]
|
It should be noted that the response is a string which may or may not be encoded as JSON. In the first example, the response body is a complete JSON object which could be decoded. In the second example, it was simply a string.
Since the client has no way of knowing what the exception response will contain, no attempts to decode it are taken.
Providing custom query parameters
editSometimes you need to provide custom query parameters, such as authentication tokens for a third-party plugin or proxy. All query parameters are allow listed in Elasticsearch-php, which is to protect you from specifying a parameter which is not accepted by Elasticsearch.
If you need custom parameters, you need to bypass this allow listing mechanism.
To do so, add them to the custom
parameter as an array of values:
$client = ClientBuilder::create()->build(); $params = [ 'index' => 'test', 'id' => 1, 'parent' => 'abc', // allowlisted Elasticsearch parameter 'client' => [ 'custom' => [ 'customToken' => 'abc', // user-defined, not allow listed, not checked 'otherToken' => 123 ] ] ]; $exists = $client->exists($params);
Increasing the verbosity of responses
editBy default, the client only returns the response body. If you require more
information (for example, stats about the transfer, headers, status codes, and
so on), you can tell the client to return a more verbose response. This is
enabled via the verbose
parameter in the client options.
Without verbosity, all you see is the response body:
$client = ClientBuilder::create()->build(); $params = [ 'index' => 'test', 'id' => 1 ]; $response = $client->get($params); print_r($response); Array ( [_index] => test [_type] => _doc [_id] => 1 [_version] => 1 [found] => 1 [_source] => Array ( [field] => value ) )
With verbosity turned on, you will see all of the transfer stats:
$client = ClientBuilder::create()->build(); $params = [ 'index' => 'test', 'id' => 1, 'client' => [ 'verbose' => true ] ]; $response = $client->get($params); print_r($response); Array ( [transfer_stats] => Array ( [url] => http://127.0.0.1:9200/test/test/1 [content_type] => application/json; charset=UTF-8 [http_code] => 200 [header_size] => 86 [request_size] => 51 [filetime] => -1 [ssl_verify_result] => 0 [redirect_count] => 0 [total_time] => 0.00289 [namelookup_time] => 9.7E-5 [connect_time] => 0.000265 [pretransfer_time] => 0.000322 [size_upload] => 0 [size_download] => 96 [speed_download] => 33217 [speed_upload] => 0 [download_content_length] => 96 [upload_content_length] => -1 [starttransfer_time] => 0.002796 [redirect_time] => 0 [redirect_url] => [primary_ip] => 127.0.0.1 [certinfo] => Array ( ) [primary_port] => 9200 [local_ip] => 127.0.0.1 [local_port] => 62971 ) [curl] => Array ( [error] => [errno] => 0 ) [effective_url] => http://127.0.0.1:9200/test/test/1 [headers] => Array ( [Content-Type] => Array ( [0] => application/json; charset=UTF-8 ) [Content-Length] => Array ( [0] => 96 ) ) [status] => 200 [reason] => OK [body] => Array ( [_index] => test [_type] => _doc [_id] => 1 [_version] => 1 [found] => 1 [_source] => Array ( [field] => value ) ) )
Curl Timeouts
editIt is possible to configure per-request curl timeouts via the timeout
and
connect_timeout
parameters. These control the client-side, curl timeouts. The
connect_timeout
parameter controls how long curl should wait for the "connect"
phase to finish, while the timeout
parameter controls how long curl should
wait for the entire request to finish.
If either timeout expires, curl closes the connection and returns an error. Both parameters should be specified in seconds.
Note: client-side timeouts do not mean that Elasticsearch aborts the request. Elasticsearch will
continue executing the request until it completes. In the case of a slow query
or bulk request, the operation continues executing "in the background", unknown
to your client. If your client kills connections rapidly with a timeout, only to
immediately execute another request, it is possible to swamp the server with
many connections because there is no "back-pressure" on the client. In these
situations, you will see the appropriate threadpool queue growing in size, and
may start receiving EsRejectedExecutionException
exceptions from Elasticsearch when the
queue finally reaches capacity.
$client = ClientBuilder::create()->build(); $params = [ 'index' => 'test', 'id' => 1, 'client' => [ 'timeout' => 10, // ten second timeout 'connect_timeout' => 10 ] ]; $response = $client->get($params);
Enabling Future Mode
editThe client supports asynchronous, batch processing of requests. This is enabled
(if your HTTP handler supports it) on a per-request basis via the future
parameter in the client options:
$client = ClientBuilder::create()->build(); $params = [ 'index' => 'test', 'id' => 1, 'client' => [ 'future' => 'lazy' ] ]; $future = $client->get($params); $results = $future->wait(); // resolve the future
Future mode supports two options: true
or 'lazy'
. For more details about how
asynchronous execution functions, and how to work with the results, see the
dedicated page on Future Mode.
SSL Encryption
editNormally, you specify SSL configurations when you create the client (see
Authentication for more details), since encryption typically applies to all
requests. However, it is possible to configure on a per-request basis, too, if
you need that functionality. For example, if you need to use a self-signed cert
on a specific request, you can specify it via the verify
parameter in the
client options:
$client = ClientBuilder::create()->build(); $params = [ 'index' => 'test', 'id' => 1, 'client' => [ 'verify' => 'path/to/cacert.pem' //Use a self-signed certificate ] ]; $result = $client->get($params);