Elasticsearch Quick Reference Card

Common Commands

Performance Monitoring

# Show detailed stats with health checks
bundle exec rake es:stats

# Benchmark search performance
bundle exec rake es:benchmark

# Check cluster health
curl http://localhost:9200/_cluster/health?pretty

# View all indices
curl 'http://localhost:9200/_cat/indices?v'

Index Management

# Interactive reindex (recreate/update mappings)
bundle exec rake es:reindex

# Force merge to optimize performance
bundle exec rake es:optimize

# Clear fielddata cache
bundle exec rake es:clear_cache

Manual Operations

# Recreate a specific index
rails console
> Company.__elasticsearch__.delete_index!
> Company.__elasticsearch__.create_index!
> Company.index_import

# Reindex a single document
> company = Company.find_by(siren: "123456789")
> company.__elasticsearch__.index_document(id: company.siren)

# Search from console
> results = Company.search(query: { value: "PARIS" })
> results[:total_entries]  # Total hits
> results[:records]         # ActiveRecord objects
> results[:aggregations]    # Facets

Health Check Indicators

Indicator	Good	Warning	Action
Fielddata Memory	< 5 MB	> 10 MB	Check mappings, clear cache
Fielddata Evictions	0	> 0	Switch to keyword fields
Deleted Docs	< 5%	> 5%	Run force merge
Segments	< 10	> 50	Run force merge
Cache Hit Rate	> 30%	< 10%	Review query patterns
Cluster Status	GREEN	YELLOW/RED	Check nodes/replicas

Search Query Examples

Basic Search

# Text search
Company.search(
  query: { value: "PARIS" },
  pagination: { page: 1, pageSize: 20 }
)

# Filtered search
Company.search(
  filters: {
    legal_status: [1, 2, 3],
    city: [75056],
    department_id: [75]
  }
)

# With aggregations
results = Company.search(query: { value: "tech" })
results[:aggregations][:legal_status]  # Returns buckets with counts

Autocomplete

# Multi-index autocomplete
Autocompleter.call("par", ["companies", "entrepreneurs"])

Advanced Queries

# Range query on capital
Company.search(
  filters: {
    capital: [2, 4]  # Index into CAPITAL_STEPS array
  }
)

# Date range
Company.search(
  filters: {
    start_date: { gte: "2020-01-01", lte: "2023-12-31" }
  }
)

Index Field Reference

Companies Index

Field	Type	Purpose	Searchable	Sortable	Aggregatable
name	text	Full-text search	✅	❌	❌
name.keyword	keyword	Exact match	✅	❌	✅
name.sort	keyword	Sorting	❌	✅	❌
name.autocomplete	text	Prefix matching	✅	❌	❌
legal_status_id	integer	Status ID	✅	✅	✅
naf_id	integer	NAF ID reference	✅	✅	✅
city_id	integer	City reference	✅	✅	✅
department_id	integer	Department ref	✅	✅	✅
capital_amount	long	Capital value	✅	✅	✅
completion_score	integer	Data completeness	✅	✅	✅
start_date	date	Creation date	✅	✅	✅

Entrepreneurs Index

Field	Type	Purpose	Searchable	Sortable	Aggregatable
name	text	Last name search	✅	❌	❌
name.sort	keyword	Sorting	❌	✅	❌
name.autocomplete	text	Prefix matching	✅	❌	❌
f_name	text	First name search	✅	❌	❌
f_name.autocomplete	text	Prefix matching	✅	❌	❌
birthdate	date	Birth date	✅	✅	✅
city_id	integer	City reference	✅	✅	✅
department_id	integer	Department ref	✅	✅	✅

Memory Optimization Checklist

• Fielddata < 10 MB (target: < 5 MB)
• Zero fielddata evictions
• Using keyword fields for sorting (not text with fielddata)
• Doc values enabled on all aggregation fields
• Segments < 10 per index (run force merge)
• Deleted docs < 5% (run force merge)
• Query cache hit rate > 30%
• Refresh interval = 30s (not 1s)
• Compression enabled (codec: best_compression)

Troubleshooting Quick Fixes

High Memory Usage

# Clear fielddata cache immediately
bundle exec rake es:clear_cache

# Check what's using memory
bundle exec rake es:stats

# Verify mappings don't use fielddata
curl http://localhost:9200/companies_development/_mapping | jq

Slow Queries

# Run benchmark to measure
bundle exec rake es:benchmark

# Enable query profiling in development
# Add to search query: profile: true

# Check slow query log
curl 'http://localhost:9200/_nodes/stats/indices/search?pretty'

Index Too Large

# Force merge to reclaim space
bundle exec rake es:optimize

# Check compression is enabled
curl http://localhost:9200/companies_development/_settings | jq '.**.codec'

# Verify only necessary fields are stored
# Review as_indexed_json method

Performance Targets

Operation	Target	Current Baseline
Simple search (text)	< 100ms	TBD after optimization
Filtered search	< 150ms	TBD after optimization
Autocomplete	< 50ms	TBD after optimization
Aggregations	< 200ms	TBD after optimization
Index update	< 10ms	TBD after optimization

Best Practices

DO ✅

• Use keyword subfields for sorting and aggregations
• Enable doc_values on numeric/date/keyword fields
• Force merge after bulk operations
• Run stats regularly to monitor health
• Use multi-field mappings for different access patterns
• Cache repeated queries at application level
• Use edge n-grams for autocomplete

DON'T ❌

• Don't use fielddata: true on text fields
• Don't force merge on actively written indices
• Don't store unnecessary fields in _source
• Don't use wildcard queries for autocomplete
• Don't aggregate on analyzed text fields
• Don't skip monitoring (run stats weekly)
• Don't reindex without testing mappings first

Emergency Procedures

Out of Memory

# 1. Clear caches immediately
bundle exec rake es:clear_cache

# 2. Check memory usage
bundle exec rake es:stats

# 3. If fielddata is high, find rogue queries
# Review recent search logs

# 4. Restart Elasticsearch if necessary
# sudo systemctl restart elasticsearch

Index Corrupted

# 1. Check cluster health
curl http://localhost:9200/_cluster/health?pretty

# 2. If red, check which index
curl 'http://localhost:9200/_cat/indices?v&health=red'

# 3. Try to recover
curl -X POST "localhost:9200/INDEX_NAME/_recovery?pretty"

# 4. If recovery fails, recreate
bundle exec rake es:reindex

Reindex Stuck

# 1. Check running tasks
curl 'http://localhost:9200/_cat/tasks?v'

# 2. Check for errors in Rails logs
tail -f log/development.log

# 3. Cancel if needed (Ctrl+C in rake task)

# 4. Clean up and retry
# May need to delete partial index and start fresh

Useful API Endpoints

# Cluster info
curl http://localhost:9200/
curl http://localhost:9200/_cluster/health?pretty
curl http://localhost:9200/_cluster/stats?pretty

# Index info
curl 'http://localhost:9200/_cat/indices?v'
curl http://localhost:9200/companies_development/_settings?pretty
curl http://localhost:9200/companies_development/_mapping?pretty
curl http://localhost:9200/companies_development/_stats?pretty

# Node info
curl http://localhost:9200/_nodes/stats?pretty
curl 'http://localhost:9200/_cat/nodes?v'
curl 'http://localhost:9200/_cat/allocation?v'

# Cache and memory
curl 'http://localhost:9200/_cat/fielddata?v'
curl 'http://localhost:9200/_cat/segments?v'
curl http://localhost:9200/_nodes/stats/indices/fielddata?pretty

# Tasks and performance
curl 'http://localhost:9200/_cat/tasks?v'
curl 'http://localhost:9200/_cat/thread_pool?v'
curl http://localhost:9200/_nodes/hot_threads

---

Quick Start:

1. Run bundle exec rake es:stats to see current status
2. Review health checks in output
3. If warnings, run bundle exec rake es:optimize
4. Monitor regularly with rake es:stats