1[[index_management]]
2=== Index management operations
3
4Index management operations allow you to manage the indices in your {es}
5cluster, such as creating, deleting and updating indices and their
6mappings/settings.
7
8[discrete]
9==== Create an index
10
11The index operations are all contained under a distinct namespace, separated
12from other methods that are on the root client object. As an example, let's
13create a new index:
14
15[source,php]
16----
17$client = ClientBuilder::create()->build();
18$params = [
19    'index' => 'my_index'
20];
21
22// Create the index
23$response = $client->indices()->create($params);
24----
25{zwsp} +
26
27You can specify any parameters that would normally be included in a new index
28creation API. All parameters that would normally go in the request body are
29located in the 'body' parameter:
30
31[source,php]
32----
33$client = ClientBuilder::create()->build();
34$params = [
35    'index' => 'my_index',
36    'body' => [
37        'settings' => [
38            'number_of_shards' => 3,
39            'number_of_replicas' => 2
40        ],
41        'mappings' => [
42            '_source' => [
43                'enabled' => true
44            ],
45            'properties' => [
46                'first_name' => [
47                    'type' => 'keyword'
48                ],
49                'age' => [
50                    'type' => 'integer'
51                ]
52            ]
53        ]
54    ]
55];
56
57
58// Create the index with mappings and settings now
59$response = $client->indices()->create($params);
60----
61{zwsp} +
62
63[discrete]
64==== Create an index (advanced example)
65
66This is a more complicated example of creating an index, showing how to define
67analyzers, tokenizers, filters and index settings. Although essentially the same
68as the previous example, the more complicated example can be helpful for "real
69world" usage of the client since this particular syntax is easy to mess up.
70
71[source,php]
72----
73$params = [
74    'index' => 'reuters',
75    'body' => [
76        'settings' => [ <1>
77            'number_of_shards' => 1,
78            'number_of_replicas' => 0,
79            'analysis' => [ <2>
80                'filter' => [
81                    'shingle' => [
82                        'type' => 'shingle'
83                    ]
84                ],
85                'char_filter' => [
86                    'pre_negs' => [
87                        'type' => 'pattern_replace',
88                        'pattern' => '(\\w+)\\s+((?i:never|no|nothing|nowhere|noone|none|not|havent|hasnt|hadnt|cant|couldnt|shouldnt|wont|wouldnt|dont|doesnt|didnt|isnt|arent|aint))\\b',
89                        'replacement' => '~$1 $2'
90                    ],
91                    'post_negs' => [
92                        'type' => 'pattern_replace',
93                        'pattern' => '\\b((?i:never|no|nothing|nowhere|noone|none|not|havent|hasnt|hadnt|cant|couldnt|shouldnt|wont|wouldnt|dont|doesnt|didnt|isnt|arent|aint))\\s+(\\w+)',
94                        'replacement' => '$1 ~$2'
95                    ]
96                ],
97                'analyzer' => [
98                    'reuters' => [
99                        'type' => 'custom',
100                        'tokenizer' => 'standard',
101                        'filter' => ['lowercase', 'stop', 'kstem']
102                    ]
103                ]
104            ]
105        ],
106        'mappings' => [ <3>
107            'properties' => [
108                'title' => [
109                    'type' => 'text',
110                    'analyzer' => 'reuters',
111                    'copy_to' => 'combined'
112                ],
113                'body' => [
114                    'type' => 'text',
115                    'analyzer' => 'reuters',
116                    'copy_to' => 'combined'
117                ],
118                'combined' => [
119                    'type' => 'text',
120                    'analyzer' => 'reuters'
121                ],
122                'topics' => [
123                    'type' => 'keyword'
124                ],
125                'places' => [
126                    'type' => 'keyword'
127                ]
128            ]
129        ]
130    ]
131];
132$client->indices()->create($params);
133----
134<1> The top level `settings` contains config about the index (# of shards, etc)
135as well as analyzers.
136<2> `analysis` is nested inside of `settings`, and contains tokenizers, filters,
137char filters and analyzers.
138<3> `mappings` is another element nested inside of `settings`, and contains the
139mappings for various types.
140
141[discrete]
142==== Delete an index
143
144Deleting an index is very simple:
145
146[source,php]
147----
148$params = ['index' => 'my_index'];
149$response = $client->indices()->delete($params);
150----
151{zwsp} +
152
153[discrete]
154=== PUT Settings API
155
156The PUT Settings API allows you to modify any index setting that is dynamic:
157
158[source,php]
159----
160$params = [
161    'index' => 'my_index',
162    'body' => [
163        'settings' => [
164            'number_of_replicas' => 0,
165            'refresh_interval' => -1
166        ]
167    ]
168];
169
170$response = $client->indices()->putSettings($params);
171----
172{zwsp} +
173
174[discrete]
175==== GET Settings API
176
177The GET Settings API shows you the currently configured settings for one or more
178indices:
179
180[source,php]
181----
182// Get settings for one index
183$params = ['index' => 'my_index'];
184$response = $client->indices()->getSettings($params);
185
186// Get settings for several indices
187$params = [
188    'index' => [ 'my_index', 'my_index2' ]
189];
190$response = $client->indices()->getSettings($params);
191----
192{zwsp} +
193
194[discrete]
195==== PUT Mappings API
196
197The PUT Mappings API allows you to modify or add to an existing index's mapping.
198
199[source,php]
200----
201// Set the index and type
202$params = [
203    'index' => 'my_index',
204    'body' => [
205        '_source' => [
206            'enabled' => true
207        ],
208        'properties' => [
209            'first_name' => [
210                'type' => 'text',
211                'analyzer' => 'standard'
212            ],
213            'age' => [
214                'type' => 'integer'
215            ]
216        ]
217    ]
218];
219
220// Update the index mapping
221$client->indices()->putMapping($params);
222----
223{zwsp} +
224
225[discrete]
226==== GET Mappings API
227
228The GET Mappings API returns the mapping details about your indices. Depending
229on the mappings that you wish to retrieve, you can specify one of more indices:
230
231[source,php]
232----
233// Get mappings for all indices
234$response = $client->indices()->getMapping();
235
236// Get mappings in 'my_index'
237$params = ['index' => 'my_index'];
238$response = $client->indices()->getMapping($params);
239
240// Get mappings for two indices
241$params = [
242    'index' => [ 'my_index', 'my_index2' ]
243];
244$response = $client->indices()->getMapping($params);
245----
246{zwsp} +
247
248[discrete]
249==== Other APIs in the indices namespace
250
251There are a number of other APIs in the indices namespace that allow you to
252manage your {es} indices (add/remove templates, flush segments, close indices,
253etc).
254
255If you use an IDE with autocompletion, you should be able to easily explore the
256indices namespace by typing:
257
258[source,php]
259----
260$client->indices()->
261----
262
263And perusing the list of available methods. Alternatively, browsing the
264`\Elasticsearch\Namespaces\Indices.php` file shows you the full list of
265available method calls (as well as parameter lists in the comments for each
266method).
267