Elastro

      .   *   .       .   *   .      .
    .   _   .   *   .    *    .   *
  _ __| | __ _ ___| |_ _ __ ___    .
  / _ \ |/ _` / __| __| '__/ _ \  *
 |  __/ | (_| \__ \ |_| | | (_) |  .
  \___|_|\__,_|___/\__|_|  \___/ .
      .    *     .      *    .   *

A comprehensive Python module for managing Elasticsearch operations within pipeline processes.

Overview

Elastro is a Python library designed to simplify interactions with Elasticsearch. It provides a clean, intuitive API for common Elasticsearch operations including:

• Index management (create, update, delete)
• Document operations (indexing, searching, updating)
• Datastream management
• Advanced query building and search functionality

The library offers both a programmatic API and a command-line interface for seamless integration with various workflows.

Table of Contents

• Installation
• Basic Usage (Python API)
• CLI Usage
• ILM (Index Lifecycle Management)
• Snapshot & Restore
• Documentation & Examples

Installation

Global CLI Installation (Recommended)

To heavily simplify installation across all operating systems and elegantly check your Python compatibility, run our automated install.sh via curl:

# WARNING: piping curl to bash skips checksum verification.
# Safer path (recommended): download, inspect, then run:
#   curl -sSfL https://raw.githubusercontent.com/Fremen-Labs/elastro/main/install.sh -o /tmp/elastro-install.sh
#   less /tmp/elastro-install.sh
#   bash /tmp/elastro-install.sh
# Or skip the installer entirely with pipx (below).
curl -sSfL https://raw.githubusercontent.com/Fremen-Labs/elastro/main/install.sh | bash

Alternatively, if you already have pipx installed and your Python version is compatible (>=3.10, <3.14):

# Manual installation via pipx
pipx install elastro-client

# Upgrade later
pipx upgrade elastro-client

Library Installation (For Development)

If you are using Elastro as a library in your Python project:

# Using a virtual environment
python3 -m venv venv
source venv/bin/activate
pip install elastro-client

Troubleshooting: "externally-managed-environment"

If you see an externally-managed-environment error when running pip install, it means your OS (like macOS with Homebrew) prevents system-wide package installation.

Solution: Use pipx (above) or a virtual environment. Do not use --break-system-packages unless you are certain of the consequences.

Basic Usage

Client Connection

from elastro import ElasticsearchClient

# Connect using API key
client = ElasticsearchClient(
    hosts=["https://elasticsearch:9200"], auth={"api_key": "your-api-key"}
)

# Or using basic auth
client = ElasticsearchClient(
    hosts=["https://elasticsearch:9200"],
    auth={"username": "elastic", "password": "password"},
)

# Connect to Elasticsearch
client.connect()

Index Management

from elastro import IndexManager

index_manager = IndexManager(client)

# Create an index
index_manager.create(
    name="products",
    settings={"number_of_shards": 3, "number_of_replicas": 1},
    mappings={
        "properties": {
            "name": {"type": "text"},
            "price": {"type": "float"},
            "description": {"type": "text"},
            "created": {"type": "date"},
        }
    },
)

# Check if an index exists
if index_manager.exists("products"):
    print("Products index exists!")

# Delete an index
index_manager.delete("products")

Document Operations

from elastro import DocumentManager

doc_manager = DocumentManager(client)

# Index a document
doc_manager.index(
    index="products",
    id="1",
    document={
        "name": "Laptop",
        "price": 999.99,
        "description": "High-performance laptop",
        "created": "2023-05-01T12:00:00",
    },
)

# Search for documents
results = doc_manager.search(index="products", query={"match": {"name": "laptop"}})

print(results)

CLI Usage

# Initialize configuration
elastro config init

# Launch the Elastro Local Web GUI
elastro gui

# Create an index
elastro index create products --shards 3 --replicas 1

# Interactive Template Wizard
elastro template wizard

# Interactive ILM Policy Wizard
elastro ilm create my-policy

# List ILM Policies (Table View)
elastro ilm list

# Add a document
elastro doc index products --id 1 --file ./product.json

# Search documents
elastro doc search products --term category=laptop

# Health assessment (scored findings, remediation, rollback)
elastro health assess -o table
elastro health score
elastro health assess --fix --dry-run -o table
elastro health assess --history -o table
elastro health rollback --id rb-abc123 --dry-run
elastro health shards --analyze
elastro health hotspots
elastro health lint -o table

# Classic cluster status (prefer over utils health)
elastro health status

# Data Ingest & Processing (Client-Side)
elastro ingest import data.csv --index customers --format csv
elastro ingest profile data.csv --sample-size 1000
elastro ingest auto-map data.json --sample-size 500
elastro ingest grok-builder --sample "10.0.0.1 - - [12/May/2026:07:03:12] \"GET /api/v1/users HTTP/1.1\" 200 1234"

# Manage server-side ingest pipelines
elastro ingest pipelines
elastro ingest simulate my-pipeline --docs ./docs.json

# Manage native realm security users and roles
elastro security users list
elastro security roles create my-role --privileges "monitor,manage"

# View long-running cluster tasks
elastro tasks list --detailed

ILM (Index Lifecycle Management)

Elastro provides a powerful CLI for managing ILM policies, including an interactive wizard.

# List all policies (Table View)
elastro ilm list

# List with full JSON details (limited to first 2)
elastro ilm list --full

# Create a policy using the Interactive Wizard (Recommended)
elastro ilm create my-policy
# Follow the prompts to configure Hot, Warm, Cold, and Delete phases.

# Create a policy from a file
elastro ilm create my-policy --file ./policy.json

# Explain lifecycle status for an index (includes step info for debugging)
elastro ilm explain my-index

Snapshot & Restore

Manage backup repositories and snapshots with ease.

Repositories:

# List all repositories
elastro snapshot repo list

# Create a filesystem repository
elastro snapshot repo create my_backup fs --setting location=/tmp/backups

# Create an S3 repository
elastro snapshot repo create my_s3_backup s3 --setting bucket=my-bucket --setting region=us-east-1

Snapshots:

# List snapshots in a repository
elastro snapshot list my_backup

# Create a snapshot (async default)
elastro snapshot create my_backup snapshot_1

# Create and wait for completion
elastro snapshot create my_backup snapshot_2 --wait --indices "logs-*,metrics-*"

# Restore a snapshot (Interactive Wizard)
elastro snapshot restore
# Launches a wizard to select repo -> snapshot -> indices -> rename pattern

# Restore specific indices from CLI
elastro snapshot restore my_backup snapshot_1 --indices "logs-*"

Documentation

For full details, refer to the guides in the docs/ directory:

• 📖 Getting Started
• 🩺 Health Commands
• 💻 CLI Usage
• 📋 Commands Reference
• ⚙️ API Reference
• 🚀 Advanced Features
• 🛠️ Troubleshooting

Examples

Check out the examples directory for more usage examples:

• Client Connection
• Index Management
• Document Operations
• Search Operations
• Datastream Management

Contributing

We welcome contributions to Elastro! Please see CONTRIBUTING.md for guidelines on how to get started, code standards, and submission processes.

License

MIT