0
# Index Management
1
2
Complete index lifecycle management through the `indices` client. Provides functionality for index creation, deletion, mapping management, settings configuration, alias operations, and maintenance tasks.
3
4
## Capabilities
5
6
### Index Lifecycle
7
8
Create, delete, open, close, and manage index existence.
9
10
```python { .api }
11
# Accessed via es.indices
12
def create(index: str, body: dict = None, **params) -> dict:
13
"""
14
Create a new index with optional mappings and settings.
15
16
Parameters:
17
- index: Index name to create
18
- body: Index configuration with mappings and settings
19
- master_timeout: Timeout for master node
20
- timeout: Request timeout
21
- update_all_types: Update mapping for all types
22
- wait_for_active_shards: Wait for N shards to be active
23
24
Body structure:
25
{
26
"settings": {
27
"number_of_shards": 3,
28
"number_of_replicas": 1,
29
"analysis": {
30
"analyzer": {
31
"my_analyzer": {
32
"type": "custom",
33
"tokenizer": "standard",
34
"filter": ["lowercase", "stop"]
35
}
36
}
37
}
38
},
39
"mappings": {
40
"_doc": {
41
"properties": {
42
"title": {"type": "text", "analyzer": "my_analyzer"},
43
"created_at": {"type": "date"}
44
}
45
}
46
}
47
}
48
49
Returns:
50
dict: Creation confirmation with acknowledged status
51
52
Raises:
53
RequestError: If index already exists or invalid configuration
54
"""
55
56
def delete(index: str, **params) -> dict:
57
"""
58
Delete one or more indices.
59
60
Parameters:
61
- index: Index name(s) to delete (string or list)
62
- allow_no_indices: Ignore if no indices match
63
- expand_wildcards: Expand wildcard expressions
64
- ignore_unavailable: Ignore unavailable indices
65
- master_timeout: Master node timeout
66
- timeout: Request timeout
67
68
Returns:
69
dict: Deletion confirmation
70
71
Raises:
72
NotFoundError: If index doesn't exist and ignore_unavailable=False
73
"""
74
75
def exists(index: str, **params) -> bool:
76
"""
77
Check if an index exists.
78
79
Parameters:
80
- index: Index name(s) to check
81
- allow_no_indices: Handle no matches
82
- expand_wildcards: Wildcard expansion
83
- ignore_unavailable: Ignore unavailable indices
84
- local: Execute locally
85
86
Returns:
87
bool: True if index exists, False otherwise
88
"""
89
90
def open(index: str, **params) -> dict:
91
"""
92
Open a closed index to enable read/write operations.
93
94
Parameters:
95
- index: Index name(s) to open
96
- allow_no_indices: Handle no matches
97
- expand_wildcards: Wildcard expansion
98
- ignore_unavailable: Ignore unavailable indices
99
- master_timeout: Master node timeout
100
- timeout: Request timeout
101
- wait_for_active_shards: Wait for shards
102
103
Returns:
104
dict: Open operation confirmation
105
"""
106
107
def close(index: str, **params) -> dict:
108
"""
109
Close an index to disable read/write operations and reduce resource usage.
110
111
Parameters:
112
- index: Index name(s) to close
113
- allow_no_indices: Handle no matches
114
- expand_wildcards: Wildcard expansion
115
- ignore_unavailable: Ignore unavailable indices
116
- master_timeout: Master node timeout
117
- timeout: Request timeout
118
119
Returns:
120
dict: Close operation confirmation
121
"""
122
123
def get(index: str, feature: str = None, **params) -> dict:
124
"""
125
Get index information including settings, mappings, and aliases.
126
127
Parameters:
128
- index: Index name(s) to retrieve
129
- feature: Specific feature to retrieve ('_settings', '_mappings', '_aliases')
130
- allow_no_indices: Handle no matches
131
- expand_wildcards: Wildcard expansion
132
- ignore_unavailable: Ignore unavailable indices
133
- local: Execute locally
134
135
Returns:
136
dict: Index configuration and metadata
137
"""
138
```
139
140
### Index Maintenance
141
142
Refresh, flush, and optimize index operations for performance and consistency.
143
144
```python { .api }
145
def refresh(index: str = None, **params) -> dict:
146
"""
147
Refresh indices to make recent changes searchable.
148
149
Parameters:
150
- index: Index name(s) to refresh (all if None)
151
- allow_no_indices: Handle no matches
152
- expand_wildcards: Wildcard expansion
153
- ignore_unavailable: Ignore unavailable indices
154
155
Returns:
156
dict: Refresh operation results with shard information
157
"""
158
159
def flush(index: str = None, **params) -> dict:
160
"""
161
Flush indices to ensure data is written to disk.
162
163
Parameters:
164
- index: Index name(s) to flush
165
- allow_no_indices: Handle no matches
166
- expand_wildcards: Wildcard expansion
167
- force: Force flush even if not necessary
168
- ignore_unavailable: Ignore unavailable indices
169
- wait_if_ongoing: Wait if flush already in progress
170
171
Returns:
172
dict: Flush operation results
173
"""
174
175
def flush_synced(index: str = None, **params) -> dict:
176
"""
177
Perform synced flush for fast recovery.
178
179
Parameters:
180
- index: Index name(s) for synced flush
181
- allow_no_indices: Handle no matches
182
- expand_wildcards: Wildcard expansion
183
- ignore_unavailable: Ignore unavailable indices
184
185
Returns:
186
dict: Synced flush results
187
"""
188
189
def forcemerge(index: str = None, **params) -> dict:
190
"""
191
Force merge segments to reduce segment count and improve performance.
192
193
Parameters:
194
- index: Index name(s) to merge
195
- allow_no_indices: Handle no matches
196
- expand_wildcards: Wildcard expansion
197
- flush: Flush after merge
198
- ignore_unavailable: Ignore unavailable indices
199
- max_num_segments: Target number of segments
200
- only_expunge_deletes: Only merge segments with deleted documents
201
- wait_for_merge: Wait for merge completion
202
203
Returns:
204
dict: Force merge operation results
205
"""
206
207
def clear_cache(index: str = None, **params) -> dict:
208
"""
209
Clear various caches to free memory.
210
211
Parameters:
212
- index: Index name(s) to clear cache
213
- allow_no_indices: Handle no matches
214
- expand_wildcards: Wildcard expansion
215
- fielddata: Clear fielddata cache
216
- ignore_unavailable: Ignore unavailable indices
217
- query: Clear query cache
218
- request: Clear request cache
219
220
Returns:
221
dict: Cache clearing results
222
"""
223
```
224
225
### Mapping Management
226
227
Define and manage field mappings for document structure and indexing behavior.
228
229
```python { .api }
230
def put_mapping(doc_type: str, body: dict, index: str = None, **params) -> dict:
231
"""
232
Create or update field mappings for document types.
233
234
Parameters:
235
- doc_type: Document type name
236
- body: Mapping definition
237
- index: Index name(s) to update (all if None)
238
- allow_no_indices: Handle no matches
239
- expand_wildcards: Wildcard expansion
240
- ignore_unavailable: Ignore unavailable indices
241
- master_timeout: Master node timeout
242
- timeout: Request timeout
243
- update_all_types: Update all types with same name
244
245
Body structure:
246
{
247
"properties": {
248
"title": {
249
"type": "text",
250
"analyzer": "standard",
251
"fields": {
252
"keyword": {
253
"type": "keyword",
254
"ignore_above": 256
255
}
256
}
257
},
258
"created_at": {
259
"type": "date",
260
"format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
261
},
262
"tags": {
263
"type": "keyword"
264
},
265
"metadata": {
266
"type": "object",
267
"properties": {
268
"author": {"type": "keyword"},
269
"category": {"type": "keyword"}
270
}
271
}
272
}
273
}
274
275
Returns:
276
dict: Mapping update confirmation
277
"""
278
279
def get_mapping(index: str = None, doc_type: str = None, **params) -> dict:
280
"""
281
Retrieve field mappings for indices and document types.
282
283
Parameters:
284
- index: Index name(s) to get mappings
285
- doc_type: Document type(s) to get mappings
286
- allow_no_indices: Handle no matches
287
- expand_wildcards: Wildcard expansion
288
- ignore_unavailable: Ignore unavailable indices
289
- local: Execute locally
290
291
Returns:
292
dict: Mapping definitions organized by index and type
293
"""
294
295
def get_field_mapping(fields: str, index: str = None, doc_type: str = None, **params) -> dict:
296
"""
297
Get mapping for specific fields.
298
299
Parameters:
300
- fields: Field name(s) to retrieve mappings
301
- index: Index name(s)
302
- doc_type: Document type(s)
303
- allow_no_indices: Handle no matches
304
- expand_wildcards: Wildcard expansion
305
- ignore_unavailable: Ignore unavailable indices
306
- local: Execute locally
307
308
Returns:
309
dict: Field mapping definitions
310
"""
311
312
def exists_type(index: str, doc_type: str, **params) -> bool:
313
"""
314
Check if a document type exists in an index.
315
316
Parameters:
317
- index: Index name to check
318
- doc_type: Document type to check
319
- allow_no_indices: Handle no matches
320
- expand_wildcards: Wildcard expansion
321
- ignore_unavailable: Ignore unavailable indices
322
- local: Execute locally
323
324
Returns:
325
bool: True if type exists
326
"""
327
```
328
329
### Index Aliases
330
331
Create and manage index aliases for zero-downtime operations and flexible index management.
332
333
```python { .api }
334
def put_alias(index: str, name: str, body: dict = None, **params) -> dict:
335
"""
336
Create an alias for one or more indices.
337
338
Parameters:
339
- index: Index name(s) to alias
340
- name: Alias name
341
- body: Alias configuration with optional filter and routing
342
- master_timeout: Master node timeout
343
- timeout: Request timeout
344
345
Body structure (optional):
346
{
347
"filter": {
348
"term": {"user_id": 12}
349
},
350
"routing": "12",
351
"search_routing": "1,2",
352
"index_routing": "2"
353
}
354
355
Returns:
356
dict: Alias creation confirmation
357
"""
358
359
def get_alias(index: str = None, name: str = None, **params) -> dict:
360
"""
361
Retrieve alias information.
362
363
Parameters:
364
- index: Index name(s) to get aliases
365
- name: Alias name(s) to retrieve
366
- allow_no_indices: Handle no matches
367
- expand_wildcards: Wildcard expansion
368
- ignore_unavailable: Ignore unavailable indices
369
- local: Execute locally
370
371
Returns:
372
dict: Alias definitions organized by index
373
"""
374
375
def delete_alias(index: str, name: str, **params) -> dict:
376
"""
377
Delete an alias from one or more indices.
378
379
Parameters:
380
- index: Index name(s) to remove alias from
381
- name: Alias name to delete
382
- master_timeout: Master node timeout
383
- timeout: Request timeout
384
385
Returns:
386
dict: Alias deletion confirmation
387
"""
388
389
def exists_alias(index: str = None, name: str = None, **params) -> bool:
390
"""
391
Check if an alias exists.
392
393
Parameters:
394
- index: Index name(s) to check
395
- name: Alias name(s) to check
396
- allow_no_indices: Handle no matches
397
- expand_wildcards: Wildcard expansion
398
- ignore_unavailable: Ignore unavailable indices
399
- local: Execute locally
400
401
Returns:
402
bool: True if alias exists
403
"""
404
405
def update_aliases(body: dict, **params) -> dict:
406
"""
407
Atomically update multiple aliases in a single operation.
408
409
Parameters:
410
- body: List of alias actions to perform
411
- master_timeout: Master node timeout
412
- timeout: Request timeout
413
414
Body structure:
415
{
416
"actions": [
417
{"add": {"index": "logs-2023-01", "alias": "logs-current"}},
418
{"remove": {"index": "logs-2022-12", "alias": "logs-current"}},
419
{"add": {
420
"index": "logs-2023-01",
421
"alias": "logs-user-12",
422
"filter": {"term": {"user_id": 12}}
423
}}
424
]
425
}
426
427
Returns:
428
dict: Alias update confirmation
429
"""
430
```
431
432
### Index Templates
433
434
Define templates for automatic index configuration when creating new indices.
435
436
```python { .api }
437
def put_template(name: str, body: dict, **params) -> dict:
438
"""
439
Create or update an index template.
440
441
Parameters:
442
- name: Template name
443
- body: Template definition
444
- create: Create only (fail if exists)
445
- master_timeout: Master node timeout
446
- order: Template precedence order
447
- timeout: Request timeout
448
449
Body structure:
450
{
451
"index_patterns": ["logs-*", "metrics-*"],
452
"settings": {
453
"number_of_shards": 1,
454
"number_of_replicas": 1
455
},
456
"mappings": {
457
"_doc": {
458
"properties": {
459
"timestamp": {"type": "date"},
460
"message": {"type": "text"}
461
}
462
}
463
},
464
"aliases": {
465
"all_logs": {}
466
}
467
}
468
469
Returns:
470
dict: Template creation confirmation
471
"""
472
473
def get_template(name: str = None, **params) -> dict:
474
"""
475
Retrieve index template definitions.
476
477
Parameters:
478
- name: Template name(s) to retrieve (all if None)
479
- flat_settings: Return flattened settings
480
- local: Execute locally
481
- master_timeout: Master node timeout
482
483
Returns:
484
dict: Template definitions
485
"""
486
487
def delete_template(name: str, **params) -> dict:
488
"""
489
Delete an index template.
490
491
Parameters:
492
- name: Template name to delete
493
- master_timeout: Master node timeout
494
- timeout: Request timeout
495
496
Returns:
497
dict: Template deletion confirmation
498
"""
499
500
def exists_template(name: str, **params) -> bool:
501
"""
502
Check if an index template exists.
503
504
Parameters:
505
- name: Template name to check
506
- local: Execute locally
507
- master_timeout: Master node timeout
508
509
Returns:
510
bool: True if template exists
511
"""
512
```
513
514
### Settings Management
515
516
Configure and update index settings for performance, analysis, and behavior.
517
518
```python { .api }
519
def get_settings(index: str = None, name: str = None, **params) -> dict:
520
"""
521
Retrieve index settings.
522
523
Parameters:
524
- index: Index name(s) to get settings
525
- name: Setting name(s) to retrieve
526
- allow_no_indices: Handle no matches
527
- expand_wildcards: Wildcard expansion
528
- flat_settings: Return flattened settings
529
- ignore_unavailable: Ignore unavailable indices
530
- local: Execute locally
531
532
Returns:
533
dict: Index settings organized by index
534
"""
535
536
def put_settings(body: dict, index: str = None, **params) -> dict:
537
"""
538
Update index settings.
539
540
Parameters:
541
- body: Settings to update
542
- index: Index name(s) to update (all if None)
543
- allow_no_indices: Handle no matches
544
- expand_wildcards: Wildcard expansion
545
- flat_settings: Accept flattened settings
546
- ignore_unavailable: Ignore unavailable indices
547
- master_timeout: Master node timeout
548
- preserve_existing: Preserve existing settings
549
- timeout: Request timeout
550
551
Body structure:
552
{
553
"index": {
554
"number_of_replicas": 2,
555
"refresh_interval": "30s",
556
"analysis": {
557
"analyzer": {
558
"my_custom_analyzer": {
559
"type": "custom",
560
"tokenizer": "keyword",
561
"filter": ["lowercase"]
562
}
563
}
564
}
565
}
566
}
567
568
Returns:
569
dict: Settings update confirmation
570
"""
571
```
572
573
### Analysis and Monitoring
574
575
Analyze text and monitor index performance and health.
576
577
```python { .api }
578
def analyze(index: str = None, body: dict = None, **params) -> dict:
579
"""
580
Analyze text using index analyzers or ad-hoc analysis chains.
581
582
Parameters:
583
- index: Index name for context-specific analysis
584
- body: Analysis specification
585
- analyzer: Named analyzer to use
586
- attributes: Token attributes to return
587
- char_filter: Character filters to apply
588
- explain: Include detailed token information
589
- field: Field to use for analysis
590
- filter: Token filters to apply
591
- normalizer: Named normalizer to use
592
- text: Text to analyze
593
- tokenizer: Tokenizer to use
594
595
Body structure:
596
{
597
"analyzer": "standard",
598
"text": "The quick brown fox jumps over the lazy dog"
599
}
600
601
Or custom analysis chain:
602
{
603
"tokenizer": "standard",
604
"filter": ["lowercase", "stop"],
605
"text": "The Quick Brown Fox"
606
}
607
608
Returns:
609
dict: Analysis results with tokens and their attributes
610
"""
611
612
def stats(index: str = None, metric: str = None, **params) -> dict:
613
"""
614
Get comprehensive index statistics.
615
616
Parameters:
617
- index: Index name(s) to get stats
618
- metric: Specific metrics ('_all', 'completion', 'docs', 'fielddata', 'flush', etc.)
619
- completion_fields: Fields for completion stats
620
- expand_wildcards: Wildcard expansion
621
- fielddata_fields: Fields for fielddata stats
622
- fields: Fields for field stats
623
- groups: Stats groups to include
624
- ignore_unavailable: Ignore unavailable indices
625
- level: Stats level ('cluster', 'indices', 'shards')
626
627
Returns:
628
dict: Detailed index statistics
629
"""
630
631
def segments(index: str = None, **params) -> dict:
632
"""
633
Get segment information for indices.
634
635
Parameters:
636
- index: Index name(s) to get segments
637
- allow_no_indices: Handle no matches
638
- expand_wildcards: Wildcard expansion
639
- ignore_unavailable: Ignore unavailable indices
640
- verbose: Include detailed segment information
641
642
Returns:
643
dict: Segment information for each index
644
"""
645
646
def recovery(index: str = None, **params) -> dict:
647
"""
648
Get index recovery status and progress.
649
650
Parameters:
651
- index: Index name(s) to get recovery info
652
- active_only: Show only active recoveries
653
- detailed: Include detailed recovery information
654
655
Returns:
656
dict: Recovery status for indices
657
"""
658
```
659
660
## Usage Examples
661
662
### Index Creation and Configuration
663
664
```python
665
from elasticsearch5 import Elasticsearch
666
667
es = Elasticsearch(['localhost:9200'])
668
669
# Create index with custom settings and mappings
670
index_config = {
671
"settings": {
672
"number_of_shards": 3,
673
"number_of_replicas": 1,
674
"analysis": {
675
"analyzer": {
676
"content_analyzer": {
677
"type": "custom",
678
"tokenizer": "standard",
679
"filter": ["lowercase", "stop", "stemmer"]
680
}
681
},
682
"filter": {
683
"stemmer": {
684
"type": "stemmer",
685
"language": "english"
686
}
687
}
688
}
689
},
690
"mappings": {
691
"_doc": {
692
"properties": {
693
"title": {
694
"type": "text",
695
"analyzer": "content_analyzer",
696
"fields": {
697
"keyword": {"type": "keyword"}
698
}
699
},
700
"content": {
701
"type": "text",
702
"analyzer": "content_analyzer"
703
},
704
"created_at": {"type": "date"},
705
"tags": {"type": "keyword"},
706
"metadata": {
707
"type": "object",
708
"properties": {
709
"author": {"type": "keyword"},
710
"category": {"type": "keyword"}
711
}
712
}
713
}
714
}
715
}
716
}
717
718
es.indices.create(index='articles', body=index_config)
719
```
720
721
### Mapping Management
722
723
```python
724
# Add new field mapping
725
new_mapping = {
726
"properties": {
727
"view_count": {"type": "integer"},
728
"featured": {"type": "boolean"},
729
"summary": {
730
"type": "text",
731
"analyzer": "content_analyzer"
732
}
733
}
734
}
735
es.indices.put_mapping(doc_type='_doc', index='articles', body=new_mapping)
736
737
# Get current mappings
738
mappings = es.indices.get_mapping(index='articles')
739
print("Current mappings:", mappings)
740
```
741
742
### Alias Management
743
744
```python
745
# Create aliases for zero-downtime operations
746
es.indices.put_alias(index='articles-2023-01', name='articles-current')
747
748
# Atomic alias switching
749
alias_actions = {
750
"actions": [
751
{"remove": {"index": "articles-2022-12", "alias": "articles-current"}},
752
{"add": {"index": "articles-2023-01", "alias": "articles-current"}},
753
{"add": {
754
"index": "articles-2023-01",
755
"alias": "articles-published",
756
"filter": {"term": {"status": "published"}}
757
}}
758
]
759
}
760
es.indices.update_aliases(body=alias_actions)
761
762
# Check if alias exists
763
if es.indices.exists_alias(name='articles-current'):
764
aliases = es.indices.get_alias(name='articles-current')
765
print("Current alias points to:", list(aliases.keys()))
766
```
767
768
### Index Templates
769
770
```python
771
# Create template for log indices
772
log_template = {
773
"index_patterns": ["logs-*"],
774
"settings": {
775
"number_of_shards": 1,
776
"number_of_replicas": 0,
777
"index.lifecycle.name": "logs-policy",
778
"index.lifecycle.rollover_alias": "logs"
779
},
780
"mappings": {
781
"_doc": {
782
"properties": {
783
"@timestamp": {"type": "date"},
784
"level": {"type": "keyword"},
785
"message": {"type": "text"},
786
"service": {"type": "keyword"},
787
"host": {"type": "keyword"}
788
}
789
}
790
},
791
"aliases": {
792
"logs": {}
793
}
794
}
795
es.indices.put_template(name='logs-template', body=log_template)
796
797
# New indices matching pattern will automatically use this template
798
es.indices.create(index='logs-2023-01-01') # Will apply template
799
```
800
801
### Index Maintenance
802
803
```python
804
# Refresh index to make changes searchable
805
es.indices.refresh(index='articles')
806
807
# Force merge to optimize segments
808
es.indices.forcemerge(index='articles', max_num_segments=1, wait_for_merge=True)
809
810
# Clear caches to free memory
811
es.indices.clear_cache(index='articles', fielddata=True, query=True)
812
813
# Get detailed index statistics
814
stats = es.indices.stats(index='articles', metric='docs,store,indexing,search')
815
print(f"Document count: {stats['indices']['articles']['total']['docs']['count']}")
816
print(f"Store size: {stats['indices']['articles']['total']['store']['size_in_bytes']}")
817
```
818
819
### Text Analysis
820
821
```python
822
# Test analyzer
823
analysis_result = es.indices.analyze(
824
index='articles',
825
body={
826
"analyzer": "content_analyzer",
827
"text": "The quick brown foxes are jumping over lazy dogs"
828
}
829
)
830
831
for token in analysis_result['tokens']:
832
print(f"Token: {token['token']}, Position: {token['position']}")
833
834
# Test custom analysis chain
835
custom_analysis = es.indices.analyze(
836
body={
837
"tokenizer": "standard",
838
"filter": ["lowercase", "stop", "stemmer"],
839
"text": "Running quickly through the forest"
840
}
841
)
842
```