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

[GUIDE] Add advanced_index_actions guide #288

Merged
merged 5 commits into from
Apr 14, 2023
Merged

[GUIDE] Add advanced_index_actions guide #288

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6e42962
Add advanced_index_actions guide
zethuman Apr 10, 2023
26ebf93
Updated CHANGELOG.md
zethuman Apr 10, 2023
6aefaa1
opensearchapi: Fix handling of errors without error response body (#286)
Jakob3xD Apr 10, 2023
4921720
Merge branch 'main' into feature/guides/advanced_index_actions
zethuman Apr 12, 2023
e0edaf7
Merge branch 'main' into feature/guides/advanced_index_actions
dblock Apr 14, 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 @@ -30,6 +30,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
- Adds `search` guide ([#291](https://github.com/opensearch-project/opensearch-go/pull/291))
- Adds `document_lifecycle` guide ([#290](https://github.com/opensearch-project/opensearch-go/pull/290))
- Adds `index_template` guide ([#289](https://github.com/opensearch-project/opensearch-go/pull/289))
- Adds `advanced_index_actions` guide ([#288](https://github.com/opensearch-project/opensearch-go/pull/288))

### Changed

Expand Down
206 changes: 206 additions & 0 deletions guides/advanced_index_actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,206 @@
# Advanced Index Actions

In this guide, we will look at some advanced index actions that are not covered in the [Index Lifecycle](index_lifecycle.md) guide.

## Setup

Let's create a client instance, and an index named `movies`:

```go
package main

import (
"github.com/opensearch-project/opensearch-go/v2"
"log"
)

func main() {
client, err := opensearch.NewDefaultClient()
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", client)
}

movies := "movies"

createMovieIndex, err := client.Indices.Create(movies)
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", createMovieIndex)
```

## API Actions

### Clear index cache

You can clear the cache of an index or indices by using the `indices.clear_cache` API action. The following example clears the cache of the `movies` index:

```go
res, err := client.Indices.ClearCache(client.Indices.ClearCache.WithIndex(movies))
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)
```

By default, the `indices.clear_cache` API action clears all types of cache. To clear specific types of cache pass the the `query`, `fielddata`, or `request` parameter to the API action:

```go
res, err := client.Indices.ClearCache(
client.Indices.ClearCache.WithIndex(movies),
client.Indices.ClearCache.WithFielddata(true),
client.Indices.ClearCache.WithRequest(true),
client.Indices.ClearCache.WithQuery(true),
)
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)
```

### Flush index

Sometimes you might want to flush an index or indices to make sure that all data in the transaction log is persisted to the index. To flush an index or indices use the `indices.flush` API action. The following example flushes the `movies` index:

```go
res, err := client.Indices.Flush(
client.Indices.Flush.WithIndex(movies),
)
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)
```

### Refresh index

You can refresh an index or indices to make sure that all changes are available for search. To refresh an index or indices use the `indices.refresh` API action:

```go
res, err := client.Indices.Refresh(
client.Indices.Refresh.WithIndex(movies),
)
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)
```

### Open/Close index

You can close an index to prevent read and write operations on the index. A closed index does not have to maintain certain data structures that an opened index require, reducing the memory and disk space required by the index. The following example closes and reopens the `movies` index:

```go
res, err := client.Indices.Close([]string{movies})
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)

res, err = client.Indices.Open([]string{movies})
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)
```

### Force merge index

You can force merge an index or indices to reduce the number of segments in the index. This can be useful if you have a large number of small segments in the index. Merging segments reduces the memory footprint of the index. Do note that this action is resource intensive and it is only recommended for read-only indices. The following example force merges the `movies` index:

```go
res, err := client.Indices.Forcemerge(
client.Indices.Forcemerge.WithIndex(movies),
)
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)
```

### Clone index

You can clone an index to create a new index with the same mappings, data, and MOST of the settings. The source index must be in read-only state for cloning. The following example blocks write operations from `movies` index, clones the said index to create a new index named `movies_clone`, then re-enables write:

```go
res, err := client.Indices.AddBlock([]string{movies}, "write")
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)

res, err = client.Indices.Clone(movies, "movies_clone")
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)

res, err = client.Indices.PutSettings(
strings.NewReader(`{"index":{"blocks":{"write":false}}}`),
client.Indices.PutSettings.WithIndex(movies),
)
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)
```

### Split index

You can split an index into another index with more primary shards. The source index must be in read-only state for splitting. The following example create the read-only `books` index with 30 routing shards and 5 shards (which is divisible by 30), splits index into `bigger_books` with 10 shards (which is also divisible by 30), then re-enables write:

```go
books := "books"

res, err := client.Indices.Create(books,
client.Indices.Create.WithBody(
strings.NewReader(`{
"settings": {
"index": {
"number_of_shards": 5,
"number_of_routing_shards": 30,
"blocks": {
"write": true
}
}
}
}`),
),
)
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)

res, err = client.Indices.Split(
books, "bigger_books",
client.Indices.Split.WithBody(strings.NewReader(`{"settings":{"index":{"number_of_shards": 10}}}`)))
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)

res, err = client.Indices.PutSettings(
strings.NewReader(`{"index":{"blocks":{"write":false}}}`),
client.Indices.PutSettings.WithIndex(books),
)
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", res)
```

## Cleanup

Let's delete all the indices we created in this guide:

```go
// movies and books are assigned to variables in the previous examples
deleteIndexes, err = client.Indices.Delete([]string{movies, books, "bigger_books", "movies_clone"})
if err != nil {
log.Printf("error occurred: [%s]", err.Error())
}
log.Printf("response: [%+v]", deleteIndexes)
```