JavaScript client

    The client contains a library of APIs that let you perform different operations on your cluster and return a standard response body. The example here demonstrates some basic operations like creating an index, adding documents, and searching your data.

    To add the client to your project, install it from :

    copy

    To install a specific major version of the client, run the following command:

    copy

    If you prefer to add the client manually or just want to examine the source code, see opensearch-js on GitHub.

    Then require the client:

    1. const { Client } = require("@opensearch-project/opensearch");

    copy

    Connecting to OpenSearch

    To connect to the default OpenSearch host, create a client object with the address https://localhost:9200 if you are using the Security plugin:

    1. var host = "localhost";
    2. var protocol = "https";
    3. var port = 9200;
    4. var auth = "admin:admin"; // For testing only. Don't store credentials in code.
    5. var ca_certs_path = "/full/path/to/root-ca.pem";
    7. // Optional client certificates if you don't want to use HTTP basic authentication.
    8. // var client_cert_path = '/full/path/to/client.pem'
    9. // var client_key_path = '/full/path/to/client-key.pem'
    11. // Create a client with SSL/TLS enabled.
    12. var { Client } = require("@opensearch-project/opensearch");
    13. var fs = require("fs");
    14. var client = new Client({
    15.   node: protocol + "://" + auth + "@" + host + ":" + port,
    16.   ssl: {
    17.     ca: fs.readFileSync(ca_certs_path),
    18.     // You can turn off certificate verification (rejectUnauthorized: false) if you're using 
    19.     // self-signed certificates with a hostname mismatch.
    20.     // cert: fs.readFileSync(client_cert_path),
    21.     // key: fs.readFileSync(client_key_path)
    22.   },
    23. });

    copy

    Authenticating with Amazon OpenSearch Service – AWS Sigv4

    Use the following code to authenticate with AWS V2 SDK:

    1. const AWS = require('aws-sdk'); // V2 SDK.
    2. const { Client } = require('@opensearch-project/opensearch');
    3. const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');
    5. const client = new Client({
    6.   ...AwsSigv4Signer({
    7.     region: 'us-west-2',
    8.     service: 'es',
    9.     // Must return a Promise that resolve to an AWS.Credentials object.
    10.     // This function is used to acquire the credentials when the client start and
    11.     // when the credentials are expired.
    12.     // The Client will refresh the Credentials only when they are expired.
    13.     // With AWS SDK V2, Credentials.refreshPromise is used when available to refresh the credentials.
    15.     // Example with AWS SDK V2:
    16.     getCredentials: () =>
    17.       new Promise((resolve, reject) => {
    18.         // Any other method to acquire a new Credentials object can be used.
    19.         AWS.config.getCredentials((err, credentials) => {
    20.           if (err) {
    21.             reject(err);
    22.           } else {
    23.             resolve(credentials);
    24.           }
    25.         });
    26.       }),
    27.   }),
    28.   node: 'https://search-xxx.region.es.amazonaws.com', // OpenSearch domain URL
    29. });

    AWS V2 SDK for Amazon OpenSearch Serverless

    copy

    Use the following code to authenticate with AWS V3 SDK:

    1. const { defaultProvider } = require('@aws-sdk/credential-provider-node'); // V3 SDK.
    2. const { Client } = require('@opensearch-project/opensearch');
    3. const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');
    5. const client = new Client({
    6.   ...AwsSigv4Signer({
    7.     region: 'us-east-1',
    8.     service: 'es',  // 'aoss' for OpenSearch Serverless
    9.     // Must return a Promise that resolve to an AWS.Credentials object.
    10.     // This function is used to acquire the credentials when the client start and
    11.     // when the credentials are expired.
    12.     // The Client will refresh the Credentials only when they are expired.
    13.     // With AWS SDK V2, Credentials.refreshPromise is used when available to refresh the credentials.
    15.     // Example with AWS SDK V3:
    16.     getCredentials: () => {
    17.       // Any other method to acquire a new Credentials object can be used.
    18.       const credentialsProvider = defaultProvider();
    19.       return credentialsProvider();
    20.     },
    21.   }),
    22.   node: 'https://search-xxx.region.es.amazonaws.com', // OpenSearch domain URL
    23. });

    copy

    AWS V3 SDK for Amazon OpenSearch Serverless

    1. const { defaultProvider } = require('@aws-sdk/credential-provider-node'); // V3 SDK.
    2. const { Client } = require('@opensearch-project/opensearch');
    3. const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');
    5. const client = new Client({
    6.   ...AwsSigv4Signer({
    7.     region: 'us-east-1',
    8.     service: 'aoss',
    10.     // This function is used to acquire the credentials when the client start and
    11.     // when the credentials are expired.
    12.     // The Client will refresh the Credentials only when they are expired.
    13.     // With AWS SDK V2, Credentials.refreshPromise is used when available to refresh the credentials.
    15.     // Example with AWS SDK V3:
    16.     getCredentials: () => {
    17.       // Any other method to acquire a new Credentials object can be used.
    18.       const credentialsProvider = defaultProvider();
    19.       return credentialsProvider();
    20.     },
    21.   }),
    22.   node: "https://xxx.region.aoss.amazonaws.com" // OpenSearch domain URL
    23. });

    copy

    To create an OpenSearch index, use the indices.create() method. You can use the following code to construct a JSON object with custom settings:

    1. var index_name = "books";
    3. var settings = {
    4.   settings: {
    5.     index: {
    6.       number_of_shards: 4,
    7.       number_of_replicas: 3,
    8.     },
    9.   },
    10. };
    12. var response = await client.indices.create({
    13.   index: index_name,
    14.   body: settings,
    15. });

    copy

    Indexing a document

    You can index a document into OpenSearch using the client’s index method:

    1. var document = {
    2.   title: "The Outsider",
    3.   author: "Stephen King",
    4.   year: "2018",
    5.   genre: "Crime fiction",
    6. };
    8. var id = "1";
    10. var response = await client.index({
    11.   id: id,
    12.   index: index_name,
    13.   body: document,
    14.   refresh: true,
    15. });

    copy

    Searching for documents

    The easiest way to search for documents is to construct a query string. The following code uses a match query to search for “The Outsider” in the title field:

    You can delete a document using the client’s delete method:

    1. var response = await client.delete({
    2.   index: index_name,
    3.   id: id,
    4. });

    copy

    Deleting an index

    You can delete an index using the indices.delete() method:

    1. var response = await client.indices.delete({
    2.   index: index_name,
    3. });

    copy

    Sample program

    The following sample program creates a client, adds an index with non-default settings, inserts a document, searches for the document, deletes the document, and then deletes the index:

    1. "use strict";
    3. var host = "localhost";
    4. var protocol = "https";
    5. var port = 9200;
    6. var auth = "admin:admin"; // For testing only. Don't store credentials in code.
    7. var ca_certs_path = "/full/path/to/root-ca.pem";
    9. // Optional client certificates if you don't want to use HTTP basic authentication.
    10. // var client_cert_path = '/full/path/to/client.pem'
    11. // var client_key_path = '/full/path/to/client-key.pem'
    13. // Create a client with SSL/TLS enabled.
    14. var { Client } = require("@opensearch-project/opensearch");
    15. var fs = require("fs");
    16. var client = new Client({
    17.   node: protocol + "://" + auth + "@" + host + ":" + port,
    18.   ssl: {
    19.     ca: fs.readFileSync(ca_certs_path),
    20.     // You can turn off certificate verification (rejectUnauthorized: false) if you're using 
    21.     // self-signed certificates with a hostname mismatch.
    22.     // cert: fs.readFileSync(client_cert_path),
    23.     // key: fs.readFileSync(client_key_path)
    24.   },
    25. });
    27.   // Create an index with non-default settings.
    28.   var index_name = "books";
    31.     settings: {
    32.       index: {
    33.         number_of_shards: 4,
    34.         number_of_replicas: 3,
    35.       },
    36.     },
    37.   };
    39.   var response = await client.indices.create({
    40.     index: index_name,
    41.     body: settings,
    42.   });
    44.   console.log("Creating index:");
    45.   console.log(response.body);
    47.   // Add a document to the index.
    48.   var document = {
    49.     title: "The Outsider",
    50.     author: "Stephen King",
    51.     year: "2018",
    52.     genre: "Crime fiction",
    53.   };
    55.   var id = "1";
    57.   var response = await client.index({
    58.     id: id,
    59.     index: index_name,
    60.     body: document,
    61.     refresh: true,
    62.   });
    64.   console.log("Adding document:");
    65.   console.log(response.body);
    67.   // Search for the document.
    68.   var query = {
    69.     query: {
    70.       match: {
    71.         title: {
    72.           query: "The Outsider",
    73.         },
    74.       },
    75.     },
    76.   };
    78.   var response = await client.search({
    79.     index: index_name,
    80.     body: query,
    81.   });
    83.   console.log("Search results:");
    84.   console.log(response.body.hits);
    86.   // Delete the document.
    87.   var response = await client.delete({
    88.     index: index_name,
    89.     id: id,
    90.   });
    92.   console.log("Deleting document:");
    93.   console.log(response.body);
    95.   // Delete the index.
    96.   var response = await client.indices.delete({
    97.     index: index_name,
    98.   });
    100.   console.log("Deleting index:");
    101.   console.log(response.body);
    102. }
    104. search().catch(console.log);

    copy

    The memoryCircuitBreaker option can be used to prevent errors caused by a response payload being too large to fit into the heap memory available to the client.

    The memoryCircuitBreaker object contains two fields:

    • enabled: A Boolean used to turn the circuit breaker on or off. Defaults to false.
    • maxPercentage: The threshold that determines whether the circuit breaker engages. Valid values are floats in the [0, 1] range that represent percentages in decimal form. Any value that exceeds that range will correct to 1.0.

    The following example instantiates a client with the circuit breaker enabled and its threshold set to 80% of the available heap size limit:

    1. var client = new Client({
    2.   memoryCircuitBreaker: {
    3.     enabled: true,
    4.     maxPercentage: 0.8,
    5.   },
    6. });

    copy