github.com/opensearch-project/opensearch-go/v2@v2.3.0/guides/index_lifecycle.md (about) 1 # Index Lifecycle 2 3 This guide covers OpenSearch Golang Client API actions for Index Lifecycle. You'll learn how to create, read, update, and delete indices in your OpenSearch cluster. We will also leverage index templates to create default settings and mappings for indices of certain patterns. 4 5 ## Setup 6 7 In this guide, we will need an OpenSearch cluster with more than one node. Let's use the sample [docker-compose.yml](https://opensearch.org/samples/docker-compose.yml) to start a cluster with two nodes. The cluster's API will be available at `localhost:9200` with basic authentication enabled with default username and password of `admin:admin`. 8 9 To start the cluster, run the following command: 10 11 ```bash 12 cd /path/to/docker-compose.yml 13 docker-compose up -d 14 ``` 15 16 Let's create a client instance to access this cluster: 17 18 ```go 19 package main 20 21 import ( 22 "github.com/opensearch-project/opensearch-go/v2" 23 "log" 24 ) 25 26 func main() { 27 client, err := opensearch.NewDefaultClient() 28 if err != nil { 29 log.Printf("error occurred: [%s]", err.Error()) 30 } 31 log.Printf("response: [%+v]", client) 32 } 33 ``` 34 35 ## Index API Actions 36 37 ### Create a new index 38 39 You can quickly create an index with default settings and mappings by using the `indices.create` API action. The following example creates an index named `paintings` with default settings and mappings: 40 41 ```go 42 paintingsIndex, err := client.Indices.Create("paintings") 43 if err != nil { 44 log.Printf("error occurred: [%s]", err.Error()) 45 } 46 log.Printf("response: [%+v]", paintingsIndex) 47 ``` 48 49 To specify settings and mappings, you can pass them as the `body` of the request. The following example creates an index named `movies` with custom settings and mappings: 50 51 ```go 52 movies := "movies" 53 54 createMovieIndex, err := client.Indices.Create(movies, 55 client.Indices.Create.WithBody(strings.NewReader(`{ 56 "settings": { 57 "index": { 58 "number_of_shards": 2, 59 "number_of_replicas": 1 60 } 61 }, 62 "mappings": { 63 "properties": { 64 "title": { 65 "type": "text" 66 }, 67 "year": { 68 "type": "integer" 69 } 70 } 71 } 72 }`), 73 ), 74 ) 75 if err != nil { 76 log.Printf("error occurred: [%s]", err.Error()) 77 } 78 log.Printf("response: [%+v]", createMovieIndex) 79 ``` 80 81 When you create a new document for an index, OpenSearch will automatically create the index if it doesn't exist: 82 83 ```go 84 // return status code 404 Not Found 85 res, err := client.Indices.Exists([]string{"burner"}) 86 if err != nil { 87 log.Printf("error occurred: [%s]", err.Error()) 88 } 89 log.Printf("response: [%+v]", res) 90 91 res, err = client.Indices.Create( 92 "burner", 93 client.Indices.Create.WithBody(strings.NewReader(`{ "settings": {} }`)), 94 ) 95 if err != nil { 96 log.Printf("error occurred: [%s]", err.Error()) 97 } 98 log.Printf("response: [%+v]", res) 99 100 // return status code 200 OK 101 res, err = client.Indices.Exists([]string{"burner"}) 102 if err != nil { 103 log.Printf("error occurred: [%s]", err.Error()) 104 } 105 log.Printf("response: [%+v]", res) 106 ``` 107 108 ### Update an Index 109 110 You can update an index's settings and mappings by using the `indices.put_settings` and `indices.put_mapping` API actions. 111 112 The following example updates the `movies` index's number of replicas to `0`: 113 114 ```go 115 res, err := client.Indices.PutSettings( 116 strings.NewReader(`{ "index": { "number_of_replicas": 0} }`), 117 client.Indices.PutSettings.WithIndex(movies), 118 ) 119 if err != nil { 120 log.Printf("error occurred: [%s]", err.Error()) 121 } 122 log.Printf("response: [%+v]", res) 123 ``` 124 125 The following example updates the `movies` index's mappings to add a new field named `director`: 126 127 ```go 128 res, err := client.Indices.PutMapping( 129 strings.NewReader(`{ "properties": { "director": { "type": "text" } } }`), 130 client.Indices.PutMapping.WithIndex(movies), 131 ) 132 if err != nil { 133 log.Printf("error occurred: [%s]", err.Error()) 134 } 135 log.Printf("response: [%+v]", res) 136 ``` 137 138 ### Get Metadata for an Index 139 140 Let's check if the index's settings and mappings have been updated by using the `indices.get` API action: 141 142 ```go 143 res, err := client.Indices.Get([]string{movies}) 144 if err != nil { 145 log.Printf("error occurred: [%s]", err.Error()) 146 } 147 log.Printf("response: [%+v]", res) 148 ``` 149 150 The response body contains the index's settings and mappings: 151 152 ```json 153 { 154 "movies": { 155 "aliases": {}, 156 "mappings": { 157 "properties": { 158 "director": { 159 "type": "text" 160 }, 161 "title": { 162 "type": "text" 163 }, 164 "year": { 165 "type": "integer" 166 } 167 } 168 }, 169 "settings": { 170 "index": { 171 "creation_date": "1681033762803", 172 "number_of_shards": "2", 173 "number_of_replicas": "1", 174 "uuid": "n9suHX2wTPG3Mq2y-3Lvdw", 175 "version": { 176 "created": "136277827" 177 }, 178 "provided_name": "movies" 179 } 180 } 181 } 182 } 183 ``` 184 185 ### Delete an Index 186 187 Let's delete the `movies` index by using the `indices.delete` API action: 188 189 ```go 190 deleteIndexes, err := client.Indices.Delete([]string{movies}) 191 if err != nil { 192 log.Printf("error occurred: [%s]", err.Error()) 193 } 194 log.Printf("response: [%+v]", deleteIndexes) 195 ``` 196 197 We can also delete multiple indices at once: 198 199 ```go 200 deleteIndexes, err := client.Indices.Delete( 201 []string{movies, "burner", "paintings"}, 202 client.Indices.Delete.WithIgnoreUnavailable(true), 203 ) 204 if err != nil { 205 log.Printf("error occurred: [%s]", err.Error()) 206 } 207 log.Printf("response: [%+v]", deleteIndexes) 208 ``` 209 210 Notice that we are passing `ignore unavailable` to the request. This tells the client to ignore the `404` error if the index doesn't exist for deletion. Without it, the above `delete` request will throw an error because the `movies` index has already been deleted in the previous example. 211 212 ## Cleanup 213 214 All resources created in this guide are automatically deleted when the cluster is stopped. You can stop the cluster by running the following command: 215 216 ```bash 217 docker-compose down -v 218 ```