IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
Installation »
Elastic Docs ›enterprise-search-js [8.8]

Overview

edit

Overview

edit

enterprise-search-js is the official Node.js client for Elastic Enterprise Search, App Search, and Workplace Search.

The Enterprise Search Node.js client is generally available as of Enterprise Search version 8.6.0.

Learn how to get started here, with some basic examples.

To use Enterprise Search you must first have an Elastic subscription, deployment, and user (or token). Refer to the prerequisites documentation for details.

See the App Search APIs and Workplace Search APIs sections for more detailed information about those APIs.

Compatibility

edit

This client is versioned and released in parallel with Enterprise Search. Current development happens in the main branch.

Please use the latest version of the library that corresponds with your major version of Enterprise Search. For example, if running Enterprise Search 8.6.1, and the latest 8.6 version of the Node library is 8.6.0, use version 8.6.0 of the Node library.

The Enterprise Search Node.js client is generally available starting with Enterprise Search version 8.6.0.

To include @elastic/enterprise-search in your package.json file, you need to add it to the dependencies section of the file.

The syntax should look like this:

{
  "dependencies": {
    "@elastic/enterprise-search": "^8.6.0"
  }
}

Note that you may need to specify a specific version or version range for @elastic/enterprise-search. In the example above, the caret (^) symbol is used to specify that any version of @elastic/enterprise-search that is compatible with version 8.6.0 of the package should be installed.

Authentication

edit

The client supports basic authentication and bearer authentication.

Elastic Cloud users can manage their API keys in the Kibana UI. Go to Stack Management > API keys to manage API keys.

App Search and Workplace Search also have their own application-specific tokens:

  • To manage App Search API keys, go to Enterprise Search >App Search > Credentials.
  • To manage Workplace Search API keys, go to Enterprise Search > Workplace Search > API keys.

Quickstart

edit

Import and instantiate the client

edit

First, import the Client class from the @elastic/enterprise-search package:

const { Client } = require('@elastic/enterprise-search')

Then, create a new Client instance, passing an options object with the following properties:

  • url (required): The Enterprise Search base URL for the instance you want to connect to.

  • auth (required): An object containing either:

    • username and password properties for basic authentication
    • a token property for bearer authentication.

Example of a connection using basic authentication:

const client = new Client({
  url: 'https://d84b2890a1d7f30699b04c7b1d6930f8.ent-search.europe-west1.gcp.cloud.es.io',
  auth: {
    username: 'elastic',
    password: 'changeme'
  }
})

Example of a connection using bearer authentication:

const client = new Client({
  url: 'https://d84b2890a1d7f30699b04c7b1d6930f8.ent-search.europe-west1.gcp.cloud.es.io',
  auth: {
    token: 'my-token'
  }
})

Once instantiated you can use the client object to make API requests to Enterprise Search.

Enterprise Search API

edit

To make a request to the Enterprise Search Management APIs, use the enterprise property of the client object, followed by the desired method.

For example, to get the health of the Enterprise Search instance, use the getHealth method:

async function run() {
  const health = await client.enterprise.getHealth()
  if (health.errors) {
    console.log(health)
    return
  }
  console.log(health)
}

run().catch(console.error)
Expand to see an example response 
{
  name: '95c8e93f2cfe',
  version: {
    number: '8.6.0',
    build_hash: 'd5faad259c946d259f84a1aaebcf6fcec1464454',
    build_date: '2022-12-05T18:37:28+00:00'
  },
  jvm: {
    gc: {
      collection_count: 15,
      collection_time: 678,
      garbage_collectors: [Object]
    },
    pid: 20,
    uptime: 1268871,
    memory_usage: {
      heap_init: 6442450944,
      heap_used: 723603408,
      heap_committed: 6442450944,
      heap_max: 6442450944,
      object_pending_finalization_count: 0,
      non_heap_init: 7667712,
      non_heap_committed: 286724096
    },
    memory_pools: [
      "CodeHeap 'non-nmethods'",
      'Metaspace',
      "CodeHeap 'profiled nmethods'",
      'Compressed Class Space',
      'G1 Eden Space',
      'G1 Old Gen',
      'G1 Survivor Space',
      "CodeHeap 'non-profiled nmethods'"
    ],
    threads: {
      thread_count: 42,
      peak_thread_count: 44,
      total_started_thread_count: 77,
      daemon_thread_count: 20
    },
    vm_version: '11.0.17+8',
    vm_vendor: 'Eclipse Adoptium',
    vm_name: 'OpenJDK 64-Bit Server VM'
  },
  filebeat: {
    pid: 215,
    alive: true,
    restart_count: 0,
    seconds_since_last_restart: -1
  },
  metricbeat: { alive: false },
  esqueues_me: {},
  crawler: {
    running: true,
    workers: { pool_size: 64, active: 0, available: 64 }
  },
  system: {
    java_version: '11.0.17',
    jruby_version: '9.3.3.0',
    os_name: 'Linux',
    os_version: '5.4.0-1049-gcp'
  },
  cluster_uuid: 'cChsNC2cTkyO149k-TJR7g'
}

App Search API

edit

To make a request to the App Search API, use the app property of the client object, followed by the desired method.

For example, to list all App Search engines on your Enterprise Search deployment, use the listEngines method:

async function run() {
  const enginesList = await client
  .app
  .listEngines()
  if (enginesList.error){
    console.log(enginesList.error)
  }
console.log(enginesList)
}

run().catch(console.error)
Expand to see an example response 
{
  meta: { page: { current: 1, total_pages: 1, total_results: 3, size: 25 } },
  results: [
    {
      name: 'my-latest-engine',
      type: 'default',
      language: null,
      index_create_settings_override: {},
      document_count: 121
    },
    {
      name: 'new-engine',
      type: 'default',
      language: null,
      index_create_settings_override: {},
      document_count: 10
    },
    {
      name: 'python3-docs',
      type: 'elasticsearch',
      language: null,
      index_create_settings_override: {},
      document_count: 18
    }
  ]
}

To list the documents in an App Search engine, use the listDocuments method:

async function run() {
  const documentsList = await client
  .app
  .listDocuments({
    engine_name: 'python3-docs'
  })
  console.log(documentsList)
}

run().catch(console.error)
Expand to see an example response (trimmed) 
{
  meta: {
    page: { current: 1, total_pages: 1, total_results: 18, size: 100 }
  },
  results: [
    {
      last_crawled_at: '2023-01-04T10:54:47+00:00',
      url_path_dir3: 'classes.html',
      additional_urls: [Array],
      body_content: 'Table of Contents 9. Classes 9.1. A Word About Names and Objects 9.2. Python Scopes and Namespaces 9.2.1. Scopes and Namespaces Example 9.3. A First Look at Classes 9.3.1. Class Definition Syntax 9.3.2. Class Objects 9.3.3. Instance Objects 9.3.4. Method Objects 9.3.5. Class and Instance Variables 9.4. Random Remarks 9.5. Inheritance 9.5.1. Multiple Inheritance 9.6. Private Variables 9.7. Odds and Ends 9.8. Iterators 9.9. Generators 9.10. Generator Expressions Previous topic 8. Errors and Exceptions Next topic 10. Brief Tour of the Standard Library This Page Report a Bug Show Source Navigation index modules | next | previous | Python » 3.11.1 Documentation » The Python Tutorial » 9. Classes | 9. Classes ¶ Classes provide a means of bundling data and functionality together. Creating a new class creates a new type of object, allowing new instances of that type to be made. Each class instance can have attributes attached to it for maintaining its state.[trimmed]'
      domains: [Array],
      title: '9. Classes — Python 3.11.1 documentation',
      url: 'https://docs.python.org/3/tutorial/classes.html',
      url_scheme: 'https',
      meta_description: 'Classes provide a means of bundling data and functionality together. Creating a new class creates a new type of object, allowing new instances of that type to be made. Each class instance can have ...',
      headings: [Array],
      links: [Array],
      id: '63b55af7a336dfbc59e08931',
      url_port: '443',
      url_host: 'docs.python.org',
      url_path_dir2: 'tutorial',
      url_path: '/3/tutorial/classes.html',
      url_path_dir1: '3'
    },]
}

Workplace Search API

edit

To make a request to the Workplace Search API, use the workplace property of the client object, followed by the desired method. For example, to list all Workplace Search content sources, use the listContentSources method:

async function run () {
  const listSources = await client
  .workplace
  .listContentSources()
  if (listSources.errors) {
      console.log(listSources)
      process.exit(1)
    }
  console.log(listSources)}

run().catch(console.log)
Expand to see an example response 
{
  meta: { page: { current: 1, total_pages: 1, total_results: 1, size: 25 } },
  results: [
    {
      id: '63b6a3cb93f321b0d789fbcb',
      service_type: 'dropbox',
      created_at: '2023-01-05T10:17:47+00:00',
      last_updated_at: '2023-01-05T10:17:47+00:00',
      is_remote: false,
      details: [],
      groups: [Array],
      name: 'Dropbox',
      context: 'organization',
      is_searchable: true,
      indexing: [Object],
      facets: [Object],
      automatic_query_refinement: [Object],
      schema: [Object],
      display: [Object],
      document_count: 3367,
      last_indexed_at: null
    }
    ]
}
Installation »