Complete client configuration options for establishing and managing connections to Elasticsearch clusters, including authentication, transport settings, and performance optimization.
Creates a new Elasticsearch client instance with comprehensive configuration options.
/**
* Creates a new Elasticsearch client instance
* @param opts - Complete client configuration options
*/
constructor(opts: ClientOptions);
interface ClientOptions {
// Connection Configuration
node?: string | string[] | NodeOptions | NodeOptions[];
nodes?: string | string[] | NodeOptions | NodeOptions[];
cloud?: { id: string };
// Transport Classes
Connection?: typeof BaseConnection;
ConnectionPool?: typeof BaseConnectionPool;
Transport?: typeof Transport;
Serializer?: typeof Serializer;
// Authentication
auth?: BasicAuth | ApiKeyAuth | BearerAuth;
// Performance & Reliability
maxRetries?: number;
requestTimeout?: number;
pingTimeout?: number;
compression?: boolean;
// Connection Pooling
sniffInterval?: number | boolean;
sniffOnStart?: boolean;
sniffOnConnectionFault?: boolean;
sniffEndpoint?: string;
resurrectStrategy?: 'ping' | 'optimistic' | 'none';
// Network & Security
tls?: TlsConnectionOptions;
agent?: HttpAgentOptions | UndiciAgentOptions | agentFn | false;
proxy?: string | URL;
caFingerprint?: string;
// Headers & Request Configuration
headers?: Record<string, any>;
opaqueIdPrefix?: string;
generateRequestId?: generateRequestIdFn;
enableMetaHeader?: boolean;
// Advanced Options
name?: string | symbol;
context?: Context;
maxResponseSize?: number;
maxCompressedResponseSize?: number;
disablePrototypePoisoningProtection?: boolean | 'proto' | 'constructor';
redaction?: RedactionOptions;
serverMode?: 'stack' | 'serverless';
// Custom Functions
nodeFilter?: nodeFilterFn;
nodeSelector?: nodeSelectorFn;
}Usage Examples:
import { Client } from "@elastic/elasticsearch";
// Basic configuration
const client = new Client({
node: "https://localhost:9200",
auth: {
username: "elastic",
password: "password"
}
});
// Advanced configuration
const client = new Client({
nodes: [
"https://node1.example.com:9200",
"https://node2.example.com:9200"
],
auth: {
apiKey: {
id: "my-api-key-id",
api_key: "my-api-key-secret"
}
},
maxRetries: 5,
requestTimeout: 60000,
sniffOnStart: true,
sniffInterval: 300000,
compression: true,
tls: {
rejectUnauthorized: false
}
});
// Cloud configuration
const client = new Client({
cloud: {
id: "deployment-name:base64encodedurl"
},
auth: {
username: "elastic",
password: "password"
}
});Individual node configuration options for multi-node clusters.
/**
* Configuration options for individual Elasticsearch nodes
*/
interface NodeOptions {
/** Elasticsearch node's location */
url: URL;
/** Optional node identifier */
id?: string;
/** Custom HTTP agent options for this node */
agent?: HttpAgentOptions | UndiciAgentOptions;
/** TLS connection settings override for this node */
ssl?: TlsConnectionOptions;
/** Custom HTTP headers for this node */
headers?: Record<string, any>;
/** Node roles for filtering and selection */
roles?: {
master: boolean;
data: boolean;
ingest: boolean;
ml: boolean;
};
}Authentication options for different security scenarios.
/**
* Basic username/password authentication
*/
interface BasicAuth {
username: string;
password: string;
}
/**
* API Key authentication
*/
interface ApiKeyAuth {
id: string;
api_key: string;
}
/**
* Bearer token authentication
*/
interface BearerAuth {
bearer: string;
}Usage Examples:
// Basic authentication
const client = new Client({
node: "https://localhost:9200",
auth: {
username: "elastic",
password: "changeme"
}
});
// API Key authentication
const client = new Client({
node: "https://localhost:9200",
auth: {
apiKey: {
id: "VuaCfGcBCdbkQm-e5aOx",
api_key: "ui2lp2axTNmsyakw9tvNnw"
}
}
});
// Bearer token authentication
const client = new Client({
node: "https://localhost:9200",
auth: {
bearer: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
});Configure HTTP transport behavior, connection pooling, and retry strategies.
/**
* TLS/SSL connection options
*/
interface TlsConnectionOptions {
ca?: string | Buffer | Array<string | Buffer>;
cert?: string | Buffer;
key?: string | Buffer;
passphrase?: string;
rejectUnauthorized?: boolean;
servername?: string;
secureProtocol?: string;
}
/**
* HTTP agent configuration
*/
interface HttpAgentOptions {
keepAlive?: boolean;
keepAliveMsecs?: number;
maxSockets?: number;
maxFreeSockets?: number;
timeout?: number;
}
/**
* Request redaction options for sensitive data
*/
interface RedactionOptions {
type: 'replace' | 'remove';
additionalKeys?: string[];
}Usage Examples:
// TLS configuration
const client = new Client({
node: "https://localhost:9200",
tls: {
ca: fs.readFileSync("./ca.crt"),
cert: fs.readFileSync("./client.crt"),
key: fs.readFileSync("./client.key"),
rejectUnauthorized: true
}
});
// Connection pool configuration
const client = new Client({
nodes: ["https://node1:9200", "https://node2:9200"],
ConnectionPool: WeightedConnectionPool,
pingTimeout: 3000,
resurrectStrategy: "ping",
sniffInterval: 300000,
maxRetries: 3
});
// Proxy configuration
const client = new Client({
node: "https://localhost:9200",
proxy: "http://proxy-server:8080"
});Create child client instances that share connection pools with the parent.
/**
* Creates a child client instance sharing connection pool with parent
* @param opts - Configuration options to merge with parent options
* @returns New client instance sharing connection resources
*/
child(opts: ClientOptions): Client;Usage Examples:
const parentClient = new Client({
node: "https://localhost:9200",
auth: { username: "elastic", password: "password" }
});
// Child client with additional headers
const childClient = parentClient.child({
headers: {
"x-custom-header": "value"
}
});
// Child client with different authentication
const adminClient = parentClient.child({
auth: {
username: "admin",
password: "admin-password"
}
});Manage client connections and resources.
/**
* Closes all connections in the connection pool
* Connections shared with parent or child instances will also be closed
*/
close(): Promise<void>;Usage Examples:
const client = new Client({ node: "https://localhost:9200" });
// Use client for operations...
await client.search({ index: "my-index" });
// Clean shutdown
await client.close();Configure client behavior for stack vs serverless deployments.
/**
* Server mode configuration affects default behaviors
* - 'stack': Traditional Elasticsearch cluster (default)
* - 'serverless': Elasticsearch serverless deployment
*/
serverMode?: 'stack' | 'serverless';Usage Examples:
// Serverless configuration
const client = new Client({
cloud: { id: "serverless-deployment-id" },
serverMode: "serverless",
auth: {
apiKey: {
id: "api-key-id",
api_key: "api-key-secret"
}
}
});
// Stack configuration (default)
const client = new Client({
nodes: ["https://node1:9200", "https://node2:9200"],
serverMode: "stack", // explicit, but this is default
sniffOnStart: true,
sniffInterval: 300000
});