Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add Search guide #489

Merged
merged 3 commits into from
Apr 13, 2023
Merged

Add Search guide #489

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
267dac2
Add Search guide
sayuree Apr 12, 2023
ca6ff86
Update changelog
sayuree Apr 12, 2023
345703d
Merge branch 'main' into fix-473
nhtruong Apr 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
171 changes: 86 additions & 85 deletions guides/search.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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: {
Expand All @@ -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: {
Expand All @@ -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'});
```