JavaScript client

The OpenSearch JavaScript client is a low-level client that provides a thin wrapper around the OpenSearch REST API. Since Lucenia supports the OpenSearch REST API, you can use the OpenSearch JavaScript client to interact with Lucenia. For more information, see the OpenSearch JavaScript client documentation.

You can use helper methods to simplify the use of complicated API tasks. For more information, see Helper methods. For more advanced index actions, see the lucenia-js guides in GitHub.

Setup

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

npm install @opensearch-project/opensearch

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

npm install @opensearch-project/opensearch@<major-version>

Then require the client:

const { Client } = require('@opensearch-project/opensearch');

Connecting to Lucenia

To connect to the default Lucenia host, create a client object with the address https://localhost:9200:

const host = "localhost";
const protocol = "https";
const port = 9200;
const auth = "admin:<custom-admin-password>"; // For testing only. Don't store credentials in code.
const ca_certs_path = "/full/path/to/root-ca.pem";

// Optional client certificates if you don't want to use HTTP basic authentication.
// const client_cert_path = '/full/path/to/client.pem'
// const client_key_path = '/full/path/to/client-key.pem'

// Create a client with SSL/TLS enabled.
import { Client } = require("@opensearch-project/opensearch");
const fs = require("fs");

const client = new Client({
  node: protocol + "://" + auth + "@" + host + ":" + port,
  ssl: {
    ca: fs.readFileSync(ca_certs_path),
    // You can turn off certificate verification (rejectUnauthorized: false) if you're using
    // self-signed certificates with a hostname mismatch.
    // cert: fs.readFileSync(client_cert_path),
    // key: fs.readFileSync(client_key_path)
  },
});

Creating an index

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

const index_name = 'books';

const settings = {
  settings: {
    index: {
      number_of_shards: 4,
      number_of_replicas: 3,
    },
  },
};

const response = await client.indices.create({
  index: index_name,
  body: settings,
});

Indexing a document

You can index a document into Lucenia using the client's index method:

const document = {
  title: 'The Outsider',
  author: 'Stephen King',
  year: '2018',
  genre: 'Crime fiction',
};

const id = '1';

const response = await client.index({
  id: id,
  index: index_name,
  body: document,
  refresh: true,
});

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:

const query = {
  query: {
    match: {
      title: {
        query: 'The Outsider',
      },
    },
  },
};

const response = await client.search({
  index: index_name,
  body: query,
});

Updating a document

You can update a document using the client's update method:

const response = await client.update({
  index: index_name,
  id: id,
  body: {
    doc: {
      // Specify the fields and their updated values here
      field1: 'new_value1',
      field2: 'new_value2',
      // Add more fields as needed
    },
  },
});

For example, the following code updates the genre field and adds a tv_adapted field to the document specified by id:

const response = await client.update({
  index: index_name,
  id: id,
  body: {
    doc: {
      genre: 'Detective fiction',
      tv_adapted: true,
    },
  },
  refresh: true,
});

Deleting a document

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

const response = await client.delete({
  index: index_name,
  id: id,
});

Deleting an index

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

const response = await client.indices.delete({
  index: index_name,
});

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:

'use strict';

const host = 'localhost';
const protocol = 'https';
const port = 9200;
const auth = 'admin:<custom-admin-password>'; // For testing only. Don't store credentials in code.
const ca_certs_path = '/full/path/to/root-ca.pem';

// Optional client certificates if you don't want to use HTTP basic authentication
// const client_cert_path = '/full/path/to/client.pem'
// const client_key_path = '/full/path/to/client-key.pem'

// Create a client with SSL/TLS enabled
const { Client } = require('@lucenia/lucenia');
const fs = require('fs');
const client = new Client({
  node: protocol + '://' + auth + '@' + host + ':' + port,
  ssl: {
    ca: fs.readFileSync(ca_certs_path),
    // You can turn off certificate verification (rejectUnauthorized: false) if you're using
    // self-signed certificates with a hostname mismatch.
    // cert: fs.readFileSync(client_cert_path),
    // key: fs.readFileSync(client_key_path)
  },
});

async function search() {
  // Create an index with non-default settings
  const index_name = 'books';

  const settings = {
    settings: {
      index: {
        number_of_shards: 4,
        number_of_replicas: 3,
      },
    },
  };

  const response = await client.indices.create({
    index: index_name,
    body: settings,
  });

  console.log('Creating index:');
  console.log(response.body);

  // Add a document to the index
  const document = {
    title: 'The Outsider',
    author: 'Stephen King',
    year: '2018',
    genre: 'Crime fiction',
  };

  const id = '1';

  const response = await client.index({
    id: id,
    index: index_name,
    body: document,
    refresh: true,
  });

  console.log('Adding document:');
  console.log(response.body);

  // Search for the document
  const query = {
    query: {
      match: {
        title: {
          query: 'The Outsider',
        },
      },
    },
  };

  const response = await client.search({
    index: index_name,
    body: query,
  });

  console.log('Search results:');
  console.log(JSON.stringify(response.body.hits, null, '  '));

  // Update a document
  const response = await client.update({
    index: index_name,
    id: id,
    body: {
      doc: {
        genre: 'Detective fiction',
        tv_adapted: true,
      },
    },
    refresh: true,
  });

  // Search for the updated document
  const query = {
    query: {
      match: {
        title: {
          query: 'The Outsider',
        },
      },
    },
  };

  const response = await client.search({
    index: index_name,
    body: query,
  });

  console.log('Search results:');
  console.log(JSON.stringify(response.body.hits, null, '  '));

  // Delete the document
  const response = await client.delete({
    index: index_name,
    id: id,
  });

  console.log('Deleting document:');
  console.log(response.body);

  // Delete the index
  const response = await client.indices.delete({
    index: index_name,
  });

  console.log('Deleting index:');
  console.log(response.body);
}

search().catch(console.log);