diff --git a/CHANGELOG.md b/CHANGELOG.md index e769e4654..fcc9c6596 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - Added Amazon OpenSearch Serverless in user_guide ([#372](https://github.com/opensearch-project/opensearch-js/issues/372)) - Add guidelines on installing yarn, dependencies; instructions on running ESLint in developer_guide ([#439](https://github.com/opensearch-project/opensearch-js/issues/435)) - Added pull_request_template ([440](https://github.com/opensearch-project/opensearch-js/pull/440)) +- Added guide for Search ([#473](https://github.com/opensearch-project/opensearch-js/pull/489)) ### Dependencies diff --git a/guides/search.md b/guides/search.md index 879f81bf3..7421e9708 100644 --- a/guides/search.md +++ b/guides/search.md @@ -1,66 +1,78 @@ # Search OpenSearch provides a powerful search API that allows you to search for documents in an index. The search API supports a number of parameters that allow you to customize the search operation. In this guide, we will explore the search API and its parameters. - # Setup Let's start by creating an index and adding some documents to it: - ```javascript -const { Client } = require('@opensearch-project/opensearch'); - -const client = new Client({ - node: 'http://localhost:9200', +var host = "localhost"; +var protocol = "https"; +var port = 9200; +var auth = "admin:admin"; // For testing only. Don't store credentials in code. +var ca_certs_path = "/full/path/to/root-ca.pem"; + +// Optional client certificates if you don't want to use HTTP basic authentication. +// var client_cert_path = '/full/path/to/client.pem' +// var client_key_path = '/full/path/to/client-key.pem' + +// Create a client with SSL/TLS enabled. +var { Client } = require("@opensearch-project/opensearch"); +var fs = require("fs"); +var 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) + }, }); -client.indices.create({index: 'movies'}) +await client.indices.create({index: 'movies'}); -for (let i = 0; i < 10; i++) { - client.index({ - index: 'movies', - id: i, - body: { - title: `The Dark Knight ${i}`, - director: 'Christopher Nolan', - year: 2008 + i - } +for(let i = 0; i < 10; i++) { + await client.index({ + index: 'movies', + id: i, + body: { + title: `The Dark Knight ${i}`, + director: 'Christopher Nolan', + year: 2008 + i + } }); } -client.index({ +await client.index({ index: 'movies', body: { title: 'The Godfather', director: 'Francis Ford Coppola', year: 1972 } -}) -client.index({ +}); + +await client.index({ index: 'movies', body: { title: 'The Shawshank Redemption', director: 'Frank Darabont', year: 1994 } -}) +}); -client.indices.refresh({index: 'movies'}) // refresh the index to make the documents searchable +await client.index({index: 'movies', refresh: true}); ``` - -## Search API - +# Search API ### Basic Search - -The search API allows you to search for documents in an index. The following example searches for ALL documents in the `movies` index: +The search API allows you to search for documents in an index. The following example searches for ALL documents in the movies index: ```javascript -client.search({ index: 'movies'}).then(response => { - console.log(response.body.hits.total.value); -}) +const response = await client.search({ + index: 'movies' +}); ``` - You can also search for documents that match a specific query. The following example searches for documents that match the query `dark knight`: - ```javascript -client.search({ +const response = await client.search({ index: 'movies', body: { query: { @@ -69,17 +81,14 @@ client.search({ } } } -}).then(response => { - console.log(response.body.hits.hits); -}) +}); +console.log(response.body.hits.hits); ``` OpenSearch query DSL allows you to specify complex queries. Check out the [OpenSearch query DSL documentation](https://opensearch.org/docs/latest/query-dsl/) for more information. ### Basic Pagination - The search API allows you to paginate through the search results. The following example searches for documents that match the query `dark knight`, sorted by `year` in ascending order, and returns the first 2 results after skipping the first 5 results: - ```javascript search_body = { query: { @@ -96,121 +105,113 @@ search_body = { ] } -client.search({ +await client.search({ index: 'movies', size: 2, from: 5, body: search_body -}).then(response => { - console.log(response.body.hits.hits); -}) +}); ``` With sorting, you can also use the `search_after` parameter to paginate through the search results. Let's say you have already displayed the first page of results, and you want to display the next page. You can use the `search_after` parameter to paginate through the search results. The following example will demonstrate how to get the first 3 pages of results using the search query of the previous example: - ```javascript -page_1 = client.search({ +const page_1 = await client.search({ index: 'movies', size: 2, body: search_body -}).then(response => response.body.hits.hits) +}); -page2 = client.search({ +const page_2 = await client.search({ index: 'movies', size: 2, body: { ...search_body, - search_after: page1[page1.length - 1].sort + search_after: page_1[page_1.length - 1].sort } -}).then(response => response.body.hits.hits) +}); -page_3 = client.search({ +const page_3 = await client.search({ index: 'movies', size: 2, body: { ...search_body, - search_after: page_2[page2.length - 1].sort + search_after: page_2[page_2.length - 1].sort } -}).then(response => response.body.hits.hits) +}) ``` - ### Pagination with scroll - -When retrieving large amounts of non-real-time data, you can use the `scroll` parameter to paginate through the search results. - +When retrieving large amounts of non-real-time data, you can use the `scroll` parameter to paginate through the search results. ```javascript -page_1 = client.search({ +const page_1 = await client.search({ index: 'movies', scroll: '1m', size: 2, body: search_body -}) +}); -page_2 = client.scroll({ +const page_2 = await client.scroll({ scroll_id: page_1._scroll_id, scroll: '1m' -}) +}); -page_3 = client.scroll( +const page_3 = await client.scroll({ scroll_id: page_2._scroll_id, scroll: '1m' -) +}); ``` - -### Pagination with Point in Time - +### Pagination with point in time The scroll example above has one weakness: if the index is updated while you are scrolling through the results, they will be paginated inconsistently. To avoid this, you should use the "Point in Time" feature. The following example demonstrates how to use the `point_in_time` and `pit_id` parameters to paginate through the search results: - ```javascript -// create a point in time +/** Create a point in time */ const pit = client.create_pit({ index: 'movies', keep_alive: '1m' }); -// Include pit info in the search body +/** Include pit info in the search body */ const pit_search_body = { - ...search_body, + ..search_body, pit: { - id: pit['pit_id'], + id: pit.pit_id, keep_alive: '1m' } -}; +} -// Get the first 3 pages of results -const page_1 = client.search({ +/** Get the first 3 pages of results */ +const page_1 = await client.search({ size: 2, body: pit_search_body -}).then(response => response.body.hits.hits) +}); +console.log(page_1.body.hits.hits); -const page_2 = client.search({ +const page_2 = await client.search({ size: 2, body: { ...pit_search_body, - search_after: page_1[page_1.length - 1].sort + search_after: page_1[page_1.length - 1].sort } -}).then(response => response.body.hits.hits) +}); +console.log(page_2.body.hits.hits); -const page_3 = client.search({ +const page_3 = await client.search({ size: 2, body: { ...pit_search_body, - search_after: page_2[page_2.length - 1].sort + search_after: page2[page_2.length-1].sort } -}).then(response => response.body.hits.hits) +}); +console.log(page_3.body.hits.hits); -// Print out the titles of the first 3 pages of results +/** Print out the titles of the first 3 pages of results */ console.log(page_1.map(hit => hit._source.title)); console.log(page_2.map(hit => hit._source.title)); console.log(page_3.map(hit => hit._source.title)); -// delete the point in time -client.delete_pit({ body: { pit_id: pit.pit_id } }); +/** Delete the point in time */ +client.delete_pit({body: {pit_id: pit.pit_id}}); ``` Note that a point-in-time is associated with an index or a set of index. So, when performing a search with a point-in-time, you DO NOT specify the index in the search. - -## Cleanup - +# Cleanup ```javascript -client.indices.delete({index: 'movies'}) +await client.indices.delete({index: 'movies'}); ``` \ No newline at end of file