⚠️ This repository is deprecated ⚠️

Please visit https://github.com/elastic/app-search-javascript for the up to date version. Thank you! - Elastic

A first-party JavaScript client for building excellent, relevant search experiences with Elastic App Search.

• Getting started
• Browser support
• Usage
• Running tests
• Development
• FAQ
• Contribute
• License

The easiest way to install this client is to simply include the built distribution from the jsDelivr CDN.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/swiftype_app_search.umd.js"></script>

This will make the client available globally at:

window.SwiftypeAppSearch;

This package can also be installed with npm or yarn.

npm install --save swiftype-app-search-javascript

The client could then be included into your project like follows:

// CommonJS
var SwiftypeAppSearch = require("swiftype-app-search-javascript");

// ES
import * as SwiftypeAppSearch from "swiftype-app-search-javascript";

The client is compatible with all modern browsers.

Note that this library depends on the Fetch API.

This is not supported by Internet Explorer. If you need backwards compatibility for Internet Explorer, you'll need to polyfill the Fetch API with something like https://github.com/github/fetch.

Using this client assumes that you have already created an App Search account, and subsequently created an Engine. You'll need to configure the client with the name of your Engine and your authentication credentials, which can be found here: https://app.swiftype.com/as/credentials.

var client = SwiftypeAppSearch.createClient({
  hostIdentifier: "host-c5s2mj",
  searchKey: "search-mu75psc5egt9ppzuycnc2mc3",
  engineName: "favorite-videos"
});

* Please note that you should only ever use a Public Search Key within Javascript code on the browser. By default, your account should have a Key prefixed with search- that is read-only. More information can be found in the documentation.

List of configuration options:

The client can be configured to use a managed deploy by using the endpointBase parameter. Since managed deploys do not rely on a hostIdentifier , it can be omitted.

var client = SwiftypeAppSearch.createClient({
  searchKey: "search-mu75psc5egt9ppzuycnc2mc3",
  endpointBase: "http://127.0.0.1:3002",
  engineName: "favorite-videos"
});

This client is a thin interface to the Swiftype App Search API. Additional details for requests and responses can be found in the documentation.

For the query term lion, a search call is constructed as follows:

var options = {
  search_fields: { title: {} },
  result_fields: { id: { raw: {} }, title: { raw: {} } }
};

client
  .search("lion", options)
  .then(resultList => {
    resultList.results.forEach(result => {
      console.log(`id: ${result.getRaw("id")} raw: ${result.getRaw("title")}`);
    });
  })
  .catch(error => {
    console.log(`error: ${error}`);
  });

Note that options supports all options listed here: https://swiftype.com/documentation/app-search/guides/search.

In addition to the supported options above, we also support the following fields:

Response

The search method returns the response wrapped in a ResultList type:

ResultList {
  rawResults: [], // List of raw `results` from JSON response
  rawInfo: { // Object wrapping the raw `meta` property from JSON response
    meta: {}
  },
  results: [ResultItem], // List of `results` wrapped in `ResultItem` type
  info: { // Currently the same as `rawInfo`
    meta: {}
  }
}

ResultItem {
  getRaw(fieldName), // Returns the HTML-unsafe raw value for a field, if it exists
  getSnippet(fieldName) // Returns the HTML-safe snippet value for a field, if it exists
}

var options = {
  size: 3,
  types: {
    documents: {
      fields: ["name"]
    }
  }
};

client
  .querySuggestion("cat", {
    size: 3,
    types: {
      documents: {
        fields: ["name"]
      }
    }
  })
  .then(response => {
    response.results.documents.forEach(document => {
      console.log(document.suggestion);
    });
  })
  .catch(error => {
    console.log(`error: ${error}`);
  });

It is possible to run multiple queries at once using the multiSearch method.

To search for the term lion and tiger, a search call is constructed as follows:

var options = {
  search_fields: { name: {} },
  result_fields: { id: { raw: {} }, title: { raw: {} } }
};

client
  .multiSearch([{ query: "node", options }, { query: "java", options }])
  .then(allResults => {
    allResults.forEach(resultList => {
      resultList.results.forEach(result => {
        console.log(
          `id: ${result.getRaw("id")} raw: ${result.getRaw("title")}`
        );
      });
    });
  })
  .catch(error => {
    console.log(`error: ${error}`);
  });

client
  .click({
    query: "lion",
    documentId: "1234567",
    requestId: "8b55561954484f13d872728f849ffd22",
    tags: ["Animal"]
  })
  .catch(error => {
    console.log(`error: ${error}`);
  });

Clickthroughs can be tracked by binding client.click calls to click events on individual search result links.

The following example shows how this can be implemented declaratively by annotating links with class and data attributes.

document.addEventListener("click", function(e) {
  const el = e.target;
  if (!el.classList.contains("track-click")) return;

  client.click({
    query: el.getAttribute("data-query"),
    documentId: el.getAttribute("data-document-id"),
    requestId: el.getAttribute("data-request-id"),
    tags: [el.getAttribute("data-tag")]
  });
});

<a href="/items/1234567"
    class="track-click"
    data-request-id="8b55561954484f13d872728f849ffd22"
    data-document-id="1234567"
    data-query="lion"
    data-tag="Animal">
  Item 1
</a>

The specs in this project use node-replay to capture responses.

The responses are then checked against Jest snapshots.

To capture new responses and update snapshots, run:

nvm use
REPLAY=record yarn test -u

To run tests:

nvm use
yarn test

You will probably want to install a node version manager, like nvm.

We depend upon the version of node defined in .nvmrc.

To install and use the correct node version with nvm:

nvm install

Install dependencies:

yarn

Run dev server:

yarn dev

nvm use
yarn build

nvm use
yarn publish

App Search has a first-party Node.js client which supports write operations like indexing.

If something is not working as expected, please open an issue.

Your best bet is to read the documentation.

You can checkout the Elastic App Search community discuss forums.

We welcome contributors to the project. Before you begin, a couple notes...

• Prior to opening a pull request, please create an issue to discuss the scope of your proposal.
• Please write simple code and concise documentation, when appropriate.

MIT © Elastic

Thank you to all the contributors!