0
# Index Management
1
2
Index creation, configuration, and management operations for Elasticsearch indices. Provides comprehensive control over index settings, mappings, aliases, and lifecycle with support for both synchronous and asynchronous operations.
3
4
## Capabilities
5
6
### Index Management Class
7
8
Main class for managing Elasticsearch indices with settings and mapping configuration.
9
10
```python { .api }
11
class Index:
12
"""
13
Index management class for creating and managing Elasticsearch indices.
14
"""
15
16
def __init__(self, name, using=None):
17
"""
18
Initialize index management.
19
20
Args:
21
name (str): Index name
22
using (str, optional): Connection alias to use
23
"""
24
25
def settings(self, **kwargs):
26
"""
27
Configure index settings.
28
29
Args:
30
**kwargs: Index settings
31
32
Parameters:
33
number_of_shards (int): Number of primary shards
34
number_of_replicas (int): Number of replica shards
35
refresh_interval (str): Refresh interval
36
max_result_window (int): Maximum result window size
37
max_rescore_window (int): Maximum rescore window size
38
analysis (dict): Analysis configuration (analyzers, tokenizers, etc.)
39
mapping (dict): Mapping configuration
40
41
Returns:
42
Index: Current Index instance with settings applied
43
"""
44
45
def mapping(self, mapping=None, **kwargs):
46
"""
47
Configure index mapping.
48
49
Args:
50
mapping (dict, optional): Complete mapping configuration
51
**kwargs: Mapping properties
52
53
Returns:
54
Index: Current Index instance with mapping applied
55
"""
56
57
def aliases(self, **kwargs):
58
"""
59
Configure index aliases.
60
61
Args:
62
**kwargs: Alias configurations
63
64
Returns:
65
Index: Current Index instance with aliases applied
66
"""
67
68
def create(self, ignore=400, **kwargs):
69
"""
70
Create the index.
71
72
Args:
73
ignore (int or list): HTTP status codes to ignore
74
**kwargs: Additional create parameters
75
76
Returns:
77
dict: Create index response
78
79
Raises:
80
RequestError: If index already exists and ignore=400 not set
81
"""
82
83
def delete(self, ignore=404, **kwargs):
84
"""
85
Delete the index.
86
87
Args:
88
ignore (int or list): HTTP status codes to ignore
89
**kwargs: Additional delete parameters
90
91
Returns:
92
dict: Delete index response
93
"""
94
95
def exists(self, **kwargs):
96
"""
97
Check if index exists.
98
99
Args:
100
**kwargs: Additional parameters
101
102
Returns:
103
bool: True if index exists, False otherwise
104
"""
105
106
def close(self, **kwargs):
107
"""
108
Close the index.
109
110
Args:
111
**kwargs: Additional close parameters
112
113
Returns:
114
dict: Close index response
115
"""
116
117
def open(self, **kwargs):
118
"""
119
Open the index.
120
121
Args:
122
**kwargs: Additional open parameters
123
124
Returns:
125
dict: Open index response
126
"""
127
128
def refresh(self, **kwargs):
129
"""
130
Refresh the index.
131
132
Args:
133
**kwargs: Additional refresh parameters
134
135
Returns:
136
dict: Refresh response
137
"""
138
139
def flush(self, **kwargs):
140
"""
141
Flush the index.
142
143
Args:
144
**kwargs: Additional flush parameters
145
146
Returns:
147
dict: Flush response
148
"""
149
150
def get_settings(self, **kwargs):
151
"""
152
Get index settings.
153
154
Args:
155
**kwargs: Additional parameters
156
157
Returns:
158
dict: Index settings
159
"""
160
161
def get_mapping(self, **kwargs):
162
"""
163
Get index mapping.
164
165
Args:
166
**kwargs: Additional parameters
167
168
Returns:
169
dict: Index mapping
170
"""
171
172
def put_settings(self, body, **kwargs):
173
"""
174
Update index settings.
175
176
Args:
177
body (dict): Settings to update
178
**kwargs: Additional parameters
179
180
Returns:
181
dict: Update settings response
182
"""
183
184
def put_mapping(self, body, **kwargs):
185
"""
186
Update index mapping.
187
188
Args:
189
body (dict): Mapping to update
190
**kwargs: Additional parameters
191
192
Returns:
193
dict: Update mapping response
194
"""
195
196
class AsyncIndex:
197
"""
198
Async version of Index class for async/await operations.
199
"""
200
201
def __init__(self, name, using=None):
202
"""Initialize async index management."""
203
204
def settings(self, **kwargs):
205
"""Configure index settings (same as Index)."""
206
207
def mapping(self, mapping=None, **kwargs):
208
"""Configure index mapping (same as Index)."""
209
210
def aliases(self, **kwargs):
211
"""Configure index aliases (same as Index)."""
212
213
async def create(self, ignore=400, **kwargs):
214
"""Async create the index."""
215
216
async def delete(self, ignore=404, **kwargs):
217
"""Async delete the index."""
218
219
async def exists(self, **kwargs):
220
"""Async check if index exists."""
221
222
async def close(self, **kwargs):
223
"""Async close the index."""
224
225
async def open(self, **kwargs):
226
"""Async open the index."""
227
228
async def refresh(self, **kwargs):
229
"""Async refresh the index."""
230
231
async def flush(self, **kwargs):
232
"""Async flush the index."""
233
234
async def get_settings(self, **kwargs):
235
"""Async get index settings."""
236
237
async def get_mapping(self, **kwargs):
238
"""Async get index mapping."""
239
240
async def put_settings(self, body, **kwargs):
241
"""Async update index settings."""
242
243
async def put_mapping(self, body, **kwargs):
244
"""Async update index mapping."""
245
```
246
247
### Index Template Management
248
249
Manage index templates for automatic index configuration.
250
251
```python { .api }
252
class IndexTemplate:
253
"""
254
Index template management class.
255
"""
256
257
def __init__(self, name, using=None):
258
"""
259
Initialize index template management.
260
261
Args:
262
name (str): Template name
263
using (str, optional): Connection alias to use
264
"""
265
266
def body(self, **kwargs):
267
"""
268
Configure template body.
269
270
Args:
271
**kwargs: Template configuration
272
273
Parameters:
274
index_patterns (list): Index patterns to match
275
template (dict): Template configuration with settings and mappings
276
priority (int): Template priority
277
version (int): Template version
278
composed_of (list): Component templates to compose from
279
data_stream (dict): Data stream configuration
280
_meta (dict): Template metadata
281
282
Returns:
283
IndexTemplate: Current instance with body configured
284
"""
285
286
def create(self, **kwargs):
287
"""
288
Create the index template.
289
290
Args:
291
**kwargs: Additional create parameters
292
293
Returns:
294
dict: Create template response
295
"""
296
297
def delete(self, **kwargs):
298
"""
299
Delete the index template.
300
301
Args:
302
**kwargs: Additional delete parameters
303
304
Returns:
305
dict: Delete template response
306
"""
307
308
def exists(self, **kwargs):
309
"""
310
Check if template exists.
311
312
Args:
313
**kwargs: Additional parameters
314
315
Returns:
316
bool: True if template exists, False otherwise
317
"""
318
319
def get(self, **kwargs):
320
"""
321
Get the index template.
322
323
Args:
324
**kwargs: Additional parameters
325
326
Returns:
327
dict: Template configuration
328
"""
329
330
class AsyncIndexTemplate:
331
"""
332
Async version of IndexTemplate class.
333
"""
334
335
def __init__(self, name, using=None):
336
"""Initialize async index template management."""
337
338
def body(self, **kwargs):
339
"""Configure template body (same as IndexTemplate)."""
340
341
async def create(self, **kwargs):
342
"""Async create the index template."""
343
344
async def delete(self, **kwargs):
345
"""Async delete the index template."""
346
347
async def exists(self, **kwargs):
348
"""Async check if template exists."""
349
350
async def get(self, **kwargs):
351
"""Async get the index template."""
352
```
353
354
### Index Alias Management
355
356
Manage index aliases for flexible index operations.
357
358
```python { .api }
359
def get_alias(name=None, index=None, using=None, **kwargs):
360
"""
361
Get index aliases.
362
363
Args:
364
name (str, optional): Alias name to get
365
index (str or list, optional): Index name(s) to get aliases for
366
using (str, optional): Connection alias to use
367
**kwargs: Additional parameters
368
369
Returns:
370
dict: Alias information
371
"""
372
373
def put_alias(index, name, body=None, using=None, **kwargs):
374
"""
375
Create or update index alias.
376
377
Args:
378
index (str or list): Index name(s) to alias
379
name (str): Alias name
380
body (dict, optional): Alias configuration (filter, routing, etc.)
381
using (str, optional): Connection alias to use
382
**kwargs: Additional parameters
383
384
Returns:
385
dict: Put alias response
386
"""
387
388
def delete_alias(index, name, using=None, **kwargs):
389
"""
390
Delete index alias.
391
392
Args:
393
index (str or list): Index name(s) to remove alias from
394
name (str): Alias name to delete
395
using (str, optional): Connection alias to use
396
**kwargs: Additional parameters
397
398
Returns:
399
dict: Delete alias response
400
"""
401
402
def update_aliases(body, using=None, **kwargs):
403
"""
404
Perform multiple alias operations atomically.
405
406
Args:
407
body (dict): Alias operations to perform
408
using (str, optional): Connection alias to use
409
**kwargs: Additional parameters
410
411
Returns:
412
dict: Update aliases response
413
414
Body format:
415
{
416
"actions": [
417
{"add": {"index": "index1", "alias": "alias1"}},
418
{"remove": {"index": "index2", "alias": "alias2"}},
419
{"remove_index": {"index": "old_index"}}
420
]
421
}
422
"""
423
```
424
425
### Utility Functions
426
427
Additional utility functions for index operations.
428
429
```python { .api }
430
def get_mapping(index=None, using=None, **kwargs):
431
"""
432
Get mapping for index(es).
433
434
Args:
435
index (str or list, optional): Index name(s)
436
using (str, optional): Connection alias to use
437
**kwargs: Additional parameters
438
439
Returns:
440
dict: Index mappings
441
"""
442
443
def put_mapping(index, body, using=None, **kwargs):
444
"""
445
Update mapping for index(es).
446
447
Args:
448
index (str or list): Index name(s) to update
449
body (dict): Mapping configuration
450
using (str, optional): Connection alias to use
451
**kwargs: Additional parameters
452
453
Returns:
454
dict: Put mapping response
455
"""
456
457
def get_settings(index=None, using=None, **kwargs):
458
"""
459
Get settings for index(es).
460
461
Args:
462
index (str or list, optional): Index name(s)
463
using (str, optional): Connection alias to use
464
**kwargs: Additional parameters
465
466
Returns:
467
dict: Index settings
468
"""
469
470
def put_settings(index, body, using=None, **kwargs):
471
"""
472
Update settings for index(es).
473
474
Args:
475
index (str or list): Index name(s) to update
476
body (dict): Settings configuration
477
using (str, optional): Connection alias to use
478
**kwargs: Additional parameters
479
480
Returns:
481
dict: Put settings response
482
"""
483
```
484
485
## Usage Examples
486
487
### Basic Index Creation and Management
488
489
```python
490
from elasticsearch_dsl import Index, connections
491
492
# Configure connection
493
connections.create_connection(hosts=['localhost:9200'])
494
495
# Create index with settings and mapping
496
index = Index('blog')
497
index.settings(
498
number_of_shards=2,
499
number_of_replicas=1,
500
refresh_interval='30s',
501
analysis={
502
'analyzer': {
503
'blog_analyzer': {
504
'type': 'custom',
505
'tokenizer': 'standard',
506
'filter': ['lowercase', 'stop']
507
}
508
}
509
}
510
)
511
512
# Create the index
513
response = index.create()
514
print(f"Index created: {response}")
515
516
# Check if index exists
517
if index.exists():
518
print("Index exists")
519
520
# Get index settings and mapping
521
settings = index.get_settings()
522
mapping = index.get_mapping()
523
print(f"Settings: {settings}")
524
print(f"Mapping: {mapping}")
525
```
526
527
### Index Templates
528
529
```python
530
from elasticsearch_dsl import IndexTemplate
531
532
# Create index template for log indices
533
template = IndexTemplate('logs-template')
534
template.body(
535
index_patterns=['logs-*'],
536
template={
537
'settings': {
538
'number_of_shards': 1,
539
'number_of_replicas': 1,
540
'refresh_interval': '10s'
541
},
542
'mappings': {
543
'properties': {
544
'timestamp': {'type': 'date'},
545
'level': {'type': 'keyword'},
546
'message': {
547
'type': 'text',
548
'analyzer': 'standard'
549
},
550
'host': {'type': 'keyword'},
551
'service': {'type': 'keyword'}
552
}
553
}
554
},
555
priority=100,
556
version=1
557
)
558
559
# Create the template
560
template.create()
561
562
# Any new index matching 'logs-*' will use this template
563
log_index = Index('logs-2023-10')
564
log_index.create() # Will automatically apply template settings
565
```
566
567
### Index Aliases
568
569
```python
570
from elasticsearch_dsl import put_alias, get_alias, update_aliases
571
572
# Create alias for current month's logs
573
put_alias(
574
index='logs-2023-10',
575
name='logs-current',
576
body={
577
'filter': {
578
'range': {
579
'timestamp': {
580
'gte': '2023-10-01'
581
}
582
}
583
}
584
}
585
)
586
587
# Get alias information
588
aliases = get_alias(name='logs-current')
589
print(f"Current logs alias: {aliases}")
590
591
# Atomic alias operations - switch to new month
592
update_aliases({
593
'actions': [
594
{'remove': {'index': 'logs-2023-10', 'alias': 'logs-current'}},
595
{'add': {'index': 'logs-2023-11', 'alias': 'logs-current'}}
596
]
597
})
598
```
599
600
### Advanced Index Configuration
601
602
```python
603
from elasticsearch_dsl import Index, Document, Text, Keyword, Date
604
605
# Define document first
606
class LogEntry(Document):
607
timestamp = Date()
608
level = Keyword()
609
message = Text(analyzer='log_analyzer')
610
host = Keyword()
611
service = Keyword()
612
613
class Index:
614
name = 'application-logs'
615
settings = {
616
'number_of_shards': 3,
617
'number_of_replicas': 2,
618
'refresh_interval': '5s',
619
'max_result_window': 50000,
620
'analysis': {
621
'analyzer': {
622
'log_analyzer': {
623
'type': 'custom',
624
'tokenizer': 'standard',
625
'filter': [
626
'lowercase',
627
'stop',
628
'log_patterns'
629
]
630
}
631
},
632
'filter': {
633
'log_patterns': {
634
'type': 'pattern_replace',
635
'pattern': r'\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}',
636
'replacement': 'TIMESTAMP'
637
}
638
}
639
}
640
}
641
642
# Initialize index from document
643
LogEntry.init()
644
645
# Or create index manually with same configuration
646
index = Index('application-logs')
647
index.settings(**LogEntry._index._settings)
648
index.mapping(LogEntry._doc_type.mapping.to_dict())
649
index.create()
650
```
651
652
### Index Lifecycle Management
653
654
```python
655
from elasticsearch_dsl import Index, connections
656
from datetime import datetime, timedelta
657
658
def rotate_logs():
659
"""Rotate log indices daily."""
660
today = datetime.now().strftime('%Y-%m-%d')
661
yesterday = (datetime.now() - timedelta(days=1)).strftime('%Y-%m-%d')
662
663
# Create today's index
664
today_index = Index(f'logs-{today}')
665
today_index.settings(
666
number_of_shards=1,
667
number_of_replicas=1,
668
refresh_interval='30s'
669
)
670
671
if not today_index.exists():
672
today_index.create()
673
print(f"Created index: logs-{today}")
674
675
# Update alias to point to today's index
676
from elasticsearch_dsl import update_aliases
677
678
actions = [
679
{'add': {'index': f'logs-{today}', 'alias': 'logs-current'}}
680
]
681
682
# Remove yesterday's alias if exists
683
yesterday_index = Index(f'logs-{yesterday}')
684
if yesterday_index.exists():
685
actions.append({
686
'remove': {'index': f'logs-{yesterday}', 'alias': 'logs-current'}
687
})
688
689
update_aliases({'actions': actions})
690
print(f"Updated logs-current alias to point to logs-{today}")
691
692
# Run daily rotation
693
rotate_logs()
694
```
695
696
### Async Index Operations
697
698
```python
699
import asyncio
700
from elasticsearch_dsl import AsyncIndex, async_connections
701
702
async def async_index_operations():
703
# Setup async connection
704
await async_connections.create_connection(hosts=['localhost:9200'])
705
706
# Create async index
707
index = AsyncIndex('async-test')
708
index.settings(
709
number_of_shards=1,
710
number_of_replicas=0
711
)
712
713
# Async operations
714
if not await index.exists():
715
create_response = await index.create()
716
print(f"Created index: {create_response}")
717
718
# Get settings asynchronously
719
settings = await index.get_settings()
720
print(f"Index settings: {settings}")
721
722
# Refresh index
723
await index.refresh()
724
725
# Close and reopen
726
await index.close()
727
await index.open()
728
729
# Run async operations
730
asyncio.run(async_index_operations())
731
```