tessl/pypi-elasticsearch5
Python client for Elasticsearch 5.x providing comprehensive access to all Elasticsearch APIs and features.
—
Pending
index-management.mddocs/
Index Management
Complete index lifecycle management through the indices client. Provides functionality for index creation, deletion, mapping management, settings configuration, alias operations, and maintenance tasks.
Capabilities
Index Lifecycle
Create, delete, open, close, and manage index existence.
# Accessed via es.indices
def create(index: str, body: dict = None, **params) -> dict:
"""
Create a new index with optional mappings and settings.
Parameters:
- index: Index name to create
- body: Index configuration with mappings and settings
- master_timeout: Timeout for master node
- timeout: Request timeout
- update_all_types: Update mapping for all types
- wait_for_active_shards: Wait for N shards to be active
Body structure:
{
"settings": {
"number_of_shards": 3,
"number_of_replicas": 1,
"analysis": {
"analyzer": {
"my_analyzer": {
"type": "custom",
"tokenizer": "standard",
"filter": ["lowercase", "stop"]
}
}
}
},
"mappings": {
"_doc": {
"properties": {
"title": {"type": "text", "analyzer": "my_analyzer"},
"created_at": {"type": "date"}
}
}
}
}
Returns:
dict: Creation confirmation with acknowledged status
Raises:
RequestError: If index already exists or invalid configuration
"""
def delete(index: str, **params) -> dict:
"""
Delete one or more indices.
Parameters:
- index: Index name(s) to delete (string or list)
- allow_no_indices: Ignore if no indices match
- expand_wildcards: Expand wildcard expressions
- ignore_unavailable: Ignore unavailable indices
- master_timeout: Master node timeout
- timeout: Request timeout
Returns:
dict: Deletion confirmation
Raises:
NotFoundError: If index doesn't exist and ignore_unavailable=False
"""
def exists(index: str, **params) -> bool:
"""
Check if an index exists.
Parameters:
- index: Index name(s) to check
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- local: Execute locally
Returns:
bool: True if index exists, False otherwise
"""
def open(index: str, **params) -> dict:
"""
Open a closed index to enable read/write operations.
Parameters:
- index: Index name(s) to open
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- master_timeout: Master node timeout
- timeout: Request timeout
- wait_for_active_shards: Wait for shards
Returns:
dict: Open operation confirmation
"""
def close(index: str, **params) -> dict:
"""
Close an index to disable read/write operations and reduce resource usage.
Parameters:
- index: Index name(s) to close
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- master_timeout: Master node timeout
- timeout: Request timeout
Returns:
dict: Close operation confirmation
"""
def get(index: str, feature: str = None, **params) -> dict:
"""
Get index information including settings, mappings, and aliases.
Parameters:
- index: Index name(s) to retrieve
- feature: Specific feature to retrieve ('_settings', '_mappings', '_aliases')
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- local: Execute locally
Returns:
dict: Index configuration and metadata
"""Index Maintenance
Refresh, flush, and optimize index operations for performance and consistency.
def refresh(index: str = None, **params) -> dict:
"""
Refresh indices to make recent changes searchable.
Parameters:
- index: Index name(s) to refresh (all if None)
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
Returns:
dict: Refresh operation results with shard information
"""
def flush(index: str = None, **params) -> dict:
"""
Flush indices to ensure data is written to disk.
Parameters:
- index: Index name(s) to flush
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- force: Force flush even if not necessary
- ignore_unavailable: Ignore unavailable indices
- wait_if_ongoing: Wait if flush already in progress
Returns:
dict: Flush operation results
"""
def flush_synced(index: str = None, **params) -> dict:
"""
Perform synced flush for fast recovery.
Parameters:
- index: Index name(s) for synced flush
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
Returns:
dict: Synced flush results
"""
def forcemerge(index: str = None, **params) -> dict:
"""
Force merge segments to reduce segment count and improve performance.
Parameters:
- index: Index name(s) to merge
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- flush: Flush after merge
- ignore_unavailable: Ignore unavailable indices
- max_num_segments: Target number of segments
- only_expunge_deletes: Only merge segments with deleted documents
- wait_for_merge: Wait for merge completion
Returns:
dict: Force merge operation results
"""
def clear_cache(index: str = None, **params) -> dict:
"""
Clear various caches to free memory.
Parameters:
- index: Index name(s) to clear cache
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- fielddata: Clear fielddata cache
- ignore_unavailable: Ignore unavailable indices
- query: Clear query cache
- request: Clear request cache
Returns:
dict: Cache clearing results
"""Mapping Management
Define and manage field mappings for document structure and indexing behavior.
def put_mapping(doc_type: str, body: dict, index: str = None, **params) -> dict:
"""
Create or update field mappings for document types.
Parameters:
- doc_type: Document type name
- body: Mapping definition
- index: Index name(s) to update (all if None)
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- master_timeout: Master node timeout
- timeout: Request timeout
- update_all_types: Update all types with same name
Body structure:
{
"properties": {
"title": {
"type": "text",
"analyzer": "standard",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}
}
},
"created_at": {
"type": "date",
"format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
},
"tags": {
"type": "keyword"
},
"metadata": {
"type": "object",
"properties": {
"author": {"type": "keyword"},
"category": {"type": "keyword"}
}
}
}
}
Returns:
dict: Mapping update confirmation
"""
def get_mapping(index: str = None, doc_type: str = None, **params) -> dict:
"""
Retrieve field mappings for indices and document types.
Parameters:
- index: Index name(s) to get mappings
- doc_type: Document type(s) to get mappings
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- local: Execute locally
Returns:
dict: Mapping definitions organized by index and type
"""
def get_field_mapping(fields: str, index: str = None, doc_type: str = None, **params) -> dict:
"""
Get mapping for specific fields.
Parameters:
- fields: Field name(s) to retrieve mappings
- index: Index name(s)
- doc_type: Document type(s)
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- local: Execute locally
Returns:
dict: Field mapping definitions
"""
def exists_type(index: str, doc_type: str, **params) -> bool:
"""
Check if a document type exists in an index.
Parameters:
- index: Index name to check
- doc_type: Document type to check
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- local: Execute locally
Returns:
bool: True if type exists
"""Index Aliases
Create and manage index aliases for zero-downtime operations and flexible index management.
def put_alias(index: str, name: str, body: dict = None, **params) -> dict:
"""
Create an alias for one or more indices.
Parameters:
- index: Index name(s) to alias
- name: Alias name
- body: Alias configuration with optional filter and routing
- master_timeout: Master node timeout
- timeout: Request timeout
Body structure (optional):
{
"filter": {
"term": {"user_id": 12}
},
"routing": "12",
"search_routing": "1,2",
"index_routing": "2"
}
Returns:
dict: Alias creation confirmation
"""
def get_alias(index: str = None, name: str = None, **params) -> dict:
"""
Retrieve alias information.
Parameters:
- index: Index name(s) to get aliases
- name: Alias name(s) to retrieve
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- local: Execute locally
Returns:
dict: Alias definitions organized by index
"""
def delete_alias(index: str, name: str, **params) -> dict:
"""
Delete an alias from one or more indices.
Parameters:
- index: Index name(s) to remove alias from
- name: Alias name to delete
- master_timeout: Master node timeout
- timeout: Request timeout
Returns:
dict: Alias deletion confirmation
"""
def exists_alias(index: str = None, name: str = None, **params) -> bool:
"""
Check if an alias exists.
Parameters:
- index: Index name(s) to check
- name: Alias name(s) to check
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- local: Execute locally
Returns:
bool: True if alias exists
"""
def update_aliases(body: dict, **params) -> dict:
"""
Atomically update multiple aliases in a single operation.
Parameters:
- body: List of alias actions to perform
- master_timeout: Master node timeout
- timeout: Request timeout
Body structure:
{
"actions": [
{"add": {"index": "logs-2023-01", "alias": "logs-current"}},
{"remove": {"index": "logs-2022-12", "alias": "logs-current"}},
{"add": {
"index": "logs-2023-01",
"alias": "logs-user-12",
"filter": {"term": {"user_id": 12}}
}}
]
}
Returns:
dict: Alias update confirmation
"""Index Templates
Define templates for automatic index configuration when creating new indices.
def put_template(name: str, body: dict, **params) -> dict:
"""
Create or update an index template.
Parameters:
- name: Template name
- body: Template definition
- create: Create only (fail if exists)
- master_timeout: Master node timeout
- order: Template precedence order
- timeout: Request timeout
Body structure:
{
"index_patterns": ["logs-*", "metrics-*"],
"settings": {
"number_of_shards": 1,
"number_of_replicas": 1
},
"mappings": {
"_doc": {
"properties": {
"timestamp": {"type": "date"},
"message": {"type": "text"}
}
}
},
"aliases": {
"all_logs": {}
}
}
Returns:
dict: Template creation confirmation
"""
def get_template(name: str = None, **params) -> dict:
"""
Retrieve index template definitions.
Parameters:
- name: Template name(s) to retrieve (all if None)
- flat_settings: Return flattened settings
- local: Execute locally
- master_timeout: Master node timeout
Returns:
dict: Template definitions
"""
def delete_template(name: str, **params) -> dict:
"""
Delete an index template.
Parameters:
- name: Template name to delete
- master_timeout: Master node timeout
- timeout: Request timeout
Returns:
dict: Template deletion confirmation
"""
def exists_template(name: str, **params) -> bool:
"""
Check if an index template exists.
Parameters:
- name: Template name to check
- local: Execute locally
- master_timeout: Master node timeout
Returns:
bool: True if template exists
"""Settings Management
Configure and update index settings for performance, analysis, and behavior.
def get_settings(index: str = None, name: str = None, **params) -> dict:
"""
Retrieve index settings.
Parameters:
- index: Index name(s) to get settings
- name: Setting name(s) to retrieve
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- flat_settings: Return flattened settings
- ignore_unavailable: Ignore unavailable indices
- local: Execute locally
Returns:
dict: Index settings organized by index
"""
def put_settings(body: dict, index: str = None, **params) -> dict:
"""
Update index settings.
Parameters:
- body: Settings to update
- index: Index name(s) to update (all if None)
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- flat_settings: Accept flattened settings
- ignore_unavailable: Ignore unavailable indices
- master_timeout: Master node timeout
- preserve_existing: Preserve existing settings
- timeout: Request timeout
Body structure:
{
"index": {
"number_of_replicas": 2,
"refresh_interval": "30s",
"analysis": {
"analyzer": {
"my_custom_analyzer": {
"type": "custom",
"tokenizer": "keyword",
"filter": ["lowercase"]
}
}
}
}
}
Returns:
dict: Settings update confirmation
"""Analysis and Monitoring
Analyze text and monitor index performance and health.
def analyze(index: str = None, body: dict = None, **params) -> dict:
"""
Analyze text using index analyzers or ad-hoc analysis chains.
Parameters:
- index: Index name for context-specific analysis
- body: Analysis specification
- analyzer: Named analyzer to use
- attributes: Token attributes to return
- char_filter: Character filters to apply
- explain: Include detailed token information
- field: Field to use for analysis
- filter: Token filters to apply
- normalizer: Named normalizer to use
- text: Text to analyze
- tokenizer: Tokenizer to use
Body structure:
{
"analyzer": "standard",
"text": "The quick brown fox jumps over the lazy dog"
}
Or custom analysis chain:
{
"tokenizer": "standard",
"filter": ["lowercase", "stop"],
"text": "The Quick Brown Fox"
}
Returns:
dict: Analysis results with tokens and their attributes
"""
def stats(index: str = None, metric: str = None, **params) -> dict:
"""
Get comprehensive index statistics.
Parameters:
- index: Index name(s) to get stats
- metric: Specific metrics ('_all', 'completion', 'docs', 'fielddata', 'flush', etc.)
- completion_fields: Fields for completion stats
- expand_wildcards: Wildcard expansion
- fielddata_fields: Fields for fielddata stats
- fields: Fields for field stats
- groups: Stats groups to include
- ignore_unavailable: Ignore unavailable indices
- level: Stats level ('cluster', 'indices', 'shards')
Returns:
dict: Detailed index statistics
"""
def segments(index: str = None, **params) -> dict:
"""
Get segment information for indices.
Parameters:
- index: Index name(s) to get segments
- allow_no_indices: Handle no matches
- expand_wildcards: Wildcard expansion
- ignore_unavailable: Ignore unavailable indices
- verbose: Include detailed segment information
Returns:
dict: Segment information for each index
"""
def recovery(index: str = None, **params) -> dict:
"""
Get index recovery status and progress.
Parameters:
- index: Index name(s) to get recovery info
- active_only: Show only active recoveries
- detailed: Include detailed recovery information
Returns:
dict: Recovery status for indices
"""Usage Examples
Index Creation and Configuration
from elasticsearch5 import Elasticsearch
es = Elasticsearch(['localhost:9200'])
# Create index with custom settings and mappings
index_config = {
"settings": {
"number_of_shards": 3,
"number_of_replicas": 1,
"analysis": {
"analyzer": {
"content_analyzer": {
"type": "custom",
"tokenizer": "standard",
"filter": ["lowercase", "stop", "stemmer"]
}
},
"filter": {
"stemmer": {
"type": "stemmer",
"language": "english"
}
}
}
},
"mappings": {
"_doc": {
"properties": {
"title": {
"type": "text",
"analyzer": "content_analyzer",
"fields": {
"keyword": {"type": "keyword"}
}
},
"content": {
"type": "text",
"analyzer": "content_analyzer"
},
"created_at": {"type": "date"},
"tags": {"type": "keyword"},
"metadata": {
"type": "object",
"properties": {
"author": {"type": "keyword"},
"category": {"type": "keyword"}
}
}
}
}
}
}
es.indices.create(index='articles', body=index_config)Mapping Management
# Add new field mapping
new_mapping = {
"properties": {
"view_count": {"type": "integer"},
"featured": {"type": "boolean"},
"summary": {
"type": "text",
"analyzer": "content_analyzer"
}
}
}
es.indices.put_mapping(doc_type='_doc', index='articles', body=new_mapping)
# Get current mappings
mappings = es.indices.get_mapping(index='articles')
print("Current mappings:", mappings)Alias Management
# Create aliases for zero-downtime operations
es.indices.put_alias(index='articles-2023-01', name='articles-current')
# Atomic alias switching
alias_actions = {
"actions": [
{"remove": {"index": "articles-2022-12", "alias": "articles-current"}},
{"add": {"index": "articles-2023-01", "alias": "articles-current"}},
{"add": {
"index": "articles-2023-01",
"alias": "articles-published",
"filter": {"term": {"status": "published"}}
}}
]
}
es.indices.update_aliases(body=alias_actions)
# Check if alias exists
if es.indices.exists_alias(name='articles-current'):
aliases = es.indices.get_alias(name='articles-current')
print("Current alias points to:", list(aliases.keys()))Index Templates
# Create template for log indices
log_template = {
"index_patterns": ["logs-*"],
"settings": {
"number_of_shards": 1,
"number_of_replicas": 0,
"index.lifecycle.name": "logs-policy",
"index.lifecycle.rollover_alias": "logs"
},
"mappings": {
"_doc": {
"properties": {
"@timestamp": {"type": "date"},
"level": {"type": "keyword"},
"message": {"type": "text"},
"service": {"type": "keyword"},
"host": {"type": "keyword"}
}
}
},
"aliases": {
"logs": {}
}
}
es.indices.put_template(name='logs-template', body=log_template)
# New indices matching pattern will automatically use this template
es.indices.create(index='logs-2023-01-01') # Will apply templateIndex Maintenance
# Refresh index to make changes searchable
es.indices.refresh(index='articles')
# Force merge to optimize segments
es.indices.forcemerge(index='articles', max_num_segments=1, wait_for_merge=True)
# Clear caches to free memory
es.indices.clear_cache(index='articles', fielddata=True, query=True)
# Get detailed index statistics
stats = es.indices.stats(index='articles', metric='docs,store,indexing,search')
print(f"Document count: {stats['indices']['articles']['total']['docs']['count']}")
print(f"Store size: {stats['indices']['articles']['total']['store']['size_in_bytes']}")Text Analysis
# Test analyzer
analysis_result = es.indices.analyze(
index='articles',
body={
"analyzer": "content_analyzer",
"text": "The quick brown foxes are jumping over lazy dogs"
}
)
for token in analysis_result['tokens']:
print(f"Token: {token['token']}, Position: {token['position']}")
# Test custom analysis chain
custom_analysis = es.indices.analyze(
body={
"tokenizer": "standard",
"filter": ["lowercase", "stop", "stemmer"],
"text": "Running quickly through the forest"
}
)Install with Tessl CLI
npx tessl i tessl/pypi-elasticsearch5