Elasticsearch API'leri Nasıl Kullanılır?

TL;DR

Elasticsearch API'leri, büyük ölçekte arama ve analitik yetenekleri sağlar. Belgeleri JSON olarak indekslersiniz, güçlü bir DSL ile sorgularsınız ve analitik için sonuçları birleştirirsiniz (aggregate). Kimlik doğrulama için API anahtarları veya temel kimlik doğrulama kullanılır. Test için, üretim kümelerine dağıtmadan önce dizin eşlemelerini doğrulamak, arama sorgularını test etmek ve birleştirmeleri (aggregations) ayıklamak (debug) için Apidog'u kullanın.

Giriş

Elasticsearch, dağıtılmış bir arama ve analitik motorudur. Yapılandırılmış metin, günlükler, metrikler ve daha fazlasını işler. Şirketler, uygulamalarda tam metin arama, hata ayıklama için günlük analizi ve gerçek zamanlı analitik panoları için kullanır.

Elasticsearch, ELK yığınının (Elasticsearch, Logstash, Kibana) kalbinde yer alır. Ancak, Logstash olmadan doğrudan API'ler aracılığıyla da kullanabilirsiniz.

💡

Arama özellikleri veya günlük analizi geliştiriyorsanız, Apidog sorguları test etmenize, eşlemeleri (mappings) doğrulamanıza ve birleştirmeleri (aggregations) ayıklamanıza yardımcı olur. Arama şablonlarını kaydedebilir ve ekibinizle paylaşabilirsiniz.

button

Apidog ile Elasticsearch API'lerini test edin - ücretsiz

Bu kılavuzun sonunda şunları yapabileceksiniz:

Belgeleri indeksleme ve yönetme
Elasticsearch DSL ile arama sorguları yazma
Analitik için birleştirmeleri (aggregations) kullanma
Eşlemeleri (mappings) ve analizcileri (analyzers) yapılandırma
Küme sağlığını izleme

Başlarken

Elasticsearch'ü yerel olarak çalıştırın

# Docker
docker run -p 9200:9200 \
  -e "discovery.type=single-node" \
  elasticsearch:8.11.0

# Or download from elastic.co

Kurulumu doğrulayın

curl -X GET "http://localhost:9200"

Yanıt:

{
  "name": "elasticsearch-1",
  "cluster_name": "elasticsearch",
  "cluster_uuid": "abc123",
  "version": {
    "number": "8.11.0",
    "build_flavor": "default"
  },
  "tagline": "You know, for search"
}

Kimlik Doğrulama

Elasticsearch 8.x, varsayılan olarak kimlik doğrulama gerektirir:

curl -X GET "http://localhost:9200/_cluster/health" \
  -u elastic:your_password

Veya API anahtarlarını (Kibana'da veya API aracılığıyla oluşturulan) kullanın.

Dizinler ve belgeler

Dizin oluşturma

curl -X PUT "http://localhost:9200/products" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "name": { "type": "text" },
        "price": { "type": "float" },
        "category": { "type": "keyword" },
        "in_stock": { "type": "boolean" },
        "created_at": { "type": "date" }
      }
    }
  }'

Belgeyi indeksleme

curl -X POST "http://localhost:9200/products/_doc" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Headphones",
    "price": 79.99,
    "category": "electronics",
    "in_stock": true,
    "created_at": "2026-03-24T10:00:00Z"
  }'

Yanıt:

{
  "_index": "products",
  "_id": "abc123",
  "_version": 1,
  "result": "created",
  "_seq_no": 0,
  "_primary_term": 1
}

Belgeyi alma

curl -X GET "http://localhost:9200/products/_doc/abc123" \
  -u elastic:your_password

Belgeyi güncelleme

curl -X PUT "http://localhost:9200/products/_doc/abc123" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Headphones Pro",
    "price": 99.99,
    "category": "electronics",
    "in_stock": true,
    "created_at": "2026-03-24T10:00:00Z"
  }'

Belgeyi silme

curl -X DELETE "http://localhost:9200/products/_doc/abc123" \
  -u elastic:your_password

Toplu işlemler

Birden fazla belgeyi verimli bir şekilde indeksleyin:

curl -X POST "http://localhost:9200/products/_bulk" \
  -u elastic:your_password \
  -H "Content-Type: application/x-ndjson" \
  -d '{"index":{"_id":"1"}}
{"name":"Product A","price":10.99,"category":"books","in_stock":true}
{"index":{"_id":"2"}}
{"name":"Product B","price":20.99,"category":"electronics","in_stock":false}
'

Arama sorguları

Temel arama

curl -X GET "http://localhost:9200/products/_search" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "name": "headphones"
      }
    }
  }'

Bool sorguları

Birden fazla koşulu birleştirin:

{
  "query": {
    "bool": {
      "must": [
        { "match": { "name": "headphones" } }
      ],
      "filter": [
        { "term": { "category": "electronics" } },
        { "range": { "price": { "lte": 100 } } },
        { "term": { "in_stock": true } }
      ]
    }
  }
}

Puanlama ile tam metin arama

{
  "query": {
    "multi_match": {
      "query": "wireless audio headphones",
      "fields": ["name^2", "description"],
      "type": "best_fields",
      "fuzziness": "AUTO"
    }
  }
}

^2 ile biten alan adları, puanlamada iki kat ağırlık alır.

Deyim araması

Tam deyimleri bulun:

{
  "query": {
    "match_phrase": {
      "description": "noise canceling"
    }
  }
}

Joker karakter ve regex

{
  "query": {
    "wildcard": {
      "name": "*headphone*"
    }
  }
}

Sıralama

{
  "query": { "match_all": {} },
  "sort": [
    { "price": "asc" },
    { "_score": "desc" }
  ]
}

Sayfalandırma

{
  "from": 20,
  "size": 10,
  "query": { "match_all": {} }
}

Birleştirmeler (Aggregations)

Birleştirmeler (Aggregations), verileriniz üzerinde özet istatistikler hesaplar.

Kategoriye göre ortalama fiyat

curl -X GET "http://localhost:9200/products/_search" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "size": 0,
    "aggs": {
      "by_category": {
        "terms": { "field": "category" },
        "aggs": {
          "avg_price": { "avg": { "field": "price" } },
          "min_price": { "min": { "field": "price" } },
          "max_price": { "max": { "field": "price" } }
        }
      }
    }
  }'

Fiyat histogramı

{
  "size": 0,
  "aggs": {
    "price_histogram": {
      "histogram": {
        "field": "price",
        "interval": 25
      }
    }
  }
}

Tarih histogramları

{
  "size": 0,
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "created_at",
        "calendar_interval": "month"
      }
    }
  }
}

Kardinalite (benzersiz sayımlar)

{
  "size": 0,
  "aggs": {
    "unique_categories": {
      "cardinality": { "field": "category" }
    }
  }
}

Eşlemeler ve analizciler

Alan türleri

Tip	Kullanım amacı
`text`	Tam metin arama, analiz edilmiş
`keyword`	Tam değerler, filtreleme, sıralama
`integer`, `float`	Sayılar
`boolean`	Doğru/yanlış
`date`	Tarihler ve saatler
`object`	İç içe JSON nesneleri
`nested`	Nesne dizileri (ilişkileri korur)
`geo_point`	Enlem/boylam koordinatları

Özel analizciler

Özel metin işleme için:

{
  "settings": {
    "analysis": {
      "analyzer": {
        "autocomplete": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "autocomplete_filter"]
        }
      },
      "filter": {
        "autocomplete_filter": {
          "type": "edge_ngram",
          "min_gram": 2,
          "max_gram": 20
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "autocomplete",
        "search_analyzer": "standard"
      }
    }
  }
}

Küme yönetimi

Küme sağlığı

curl -X GET "http://localhost:9200/_cluster/health"

Yanıt:

{
  "cluster_name": "elasticsearch",
  "status": "green",
  "number_of_nodes": 3,
  "active_primary_shards": 25
}

Durumlar:

green: Tüm parçalar (shards) tahsis edildi
yellow: Replikalar tahsis edilmedi (tek düğüm)
red: Birincil parçalar (primary shards) eksik

Dizin istatistikleri

curl -X GET "http://localhost:9200/_cat/indices?v"

Düğüm istatistikleri

curl -X GET "http://localhost:9200/_nodes/stats"

Önbelleği temizle

curl -X POST "http://localhost:9200/_cache/clear"

Apidog ile test etme

Elasticsearch sorguları karmaşık olabilir. Kapsamlı bir şekilde test edin.

1. Sık kullanılan sorguları kaydedin

Arama şablonlarını Apidog'da saklayın:

{
  "query": {
    "bool": {
      "must": [
        { "match": { "{{search_field}}": "{{search_term}}" } }
      ],
      "filter": [
        { "range": { "{{price_field}}": { "lte": "{{max_price}}" } } }
      ]
    }
  }
}

2. Yanıtları doğrulayın

pm.test('Search returns results', () => {
  const response = pm.response.json()
  pm.expect(response.hits.total.value).to.be.above(0)
})

pm.test('Aggregations present', () => {
  const response = pm.response.json()
  pm.expect(response.aggregations).to.exist
})

3. Ortam ayrımı

# Local
ES_HOST: http://localhost:9200
ES_USER: elastic
ES_PASSWORD: your_password

# Production
ES_HOST: https://search.yourcompany.com
ES_API_KEY: prod_api_key

Apidog ile Elasticsearch API'lerini test edin - ücretsiz

Sık karşılaşılan hatalar ve çözümleri

403 Yasak

Neden: Kimlik doğrulama başarısız oldu veya yetersiz izinler.

Çözüm: Kimlik bilgilerini doğrulayın. API anahtarının doğru dizin izinlerine sahip olup olmadığını kontrol edin.

404 index_not_found_exception

Neden: Dizin mevcut değil.

Çözüm: Önce dizini oluşturun veya otomatik oluşturmayı kullanın (varsayılan olarak etkindir ancak üretim için önerilmez).

circuit_breaking_exception

Neden: Sorgu çok fazla bellek kullanıyor.

Çözüm: size parametresini azaltın, sorguları basitleştirin, sonuç kümesini küçültmek için filtreler ekleyin.

search_phase_execution_exception

Neden: Sorgu sözdizimi hatası.

Çözüm: JSON'unuzu kontrol edin. Sık karşılaşılan sorunlar: eksik tırnak işaretleri, yanlış alan yolları.

Alternatifler ve karşılaştırmalar

Özellik	Elasticsearch	OpenSearch	Meilisearch	Typesense
Kurulum	Kendi kendine barındırılan	Kendi kendine barındırılan	Tek ikili dosya	Tek ikili dosya
Arama kalitesi	Mükemmel	İyi	Mükemmel	İyi
Öğrenme eğrisi	Dik	Dik	Kolay	Kolay
Ölçeklenebilirlik	Mükemmel	Mükemmel	İyi	İyi
Bulut teklifi	Elastic Cloud	OpenSearch Serverless	Meilisearch Cloud	Typesense Cloud

Elasticsearch en çok özelliğe ve topluluğa sahiptir. Meilisearch ve Typesense, temel arama için daha basittir.

Gerçek dünya kullanım örnekleri

E-ticaret araması. Bir perakende sitesi 100.000 ürünü indeksler. Kullanıcılar ada, açıklamaya, kategoriye ve fiyat aralığına göre arama yapar. Otomatik tamamlama, yazarken ürünleri önerir. Filtreler, kategori ve stok durumuna göre sonuçları daraltır.

Uygulama günlükleri. Bir DevOps ekibi, Filebeat aracılığıyla günlükleri Elasticsearch'e gönderir. Mühendisler, hizmete, önem derecesine ve zaman aralığına göre günlükleri arar. Panolar, hata oranlarını ve yanıt sürelerini gösterir.

Güvenlik analizi. Bir güvenlik ekibi ağ günlüklerini indeksler. Şüpheli IP adreslerini arar, trafik modellerini görselleştirir ve birleştirmeler (aggregations) aracılığıyla tespit edilen anormallikler hakkında uyarı verir.

Özetle

İşte öğrendikleriniz:

Belgeleri JSON olarak indeksleme
Elasticsearch DSL ile sorgulama
Analitik için birleştirmeleri (aggregations) kullanma
Optimal arama için eşlemeleri (mappings) yapılandırma
Küme sağlığını izleme

Sonraki adımlarınız:

Elasticsearch'ü yerel olarak çalıştırın
Eşlemelerle bir dizin oluşturun
Bazı test belgelerini indeksleyin
Arama sorguları yazın
Birleştirmeleri (aggregations) deneyin

Apidog ile Elasticsearch API'lerini test edin - ücretsiz

button

Sıkça Sorulan Sorular

Elasticsearch ve Solr arasındaki fark nedir?Her ikisi de Lucene tabanlı arama motorlarıdır. Elasticsearch daha iyi dağıtılmış tasarıma ve API'lere sahiptir. Solr daha fazla kurumsal özelliğe sahiptir. Çoğu yeni proje Elasticsearch'ü seçer.

Aramada özel karakterleri nasıl işlerim?Özel karakterleri: ()[]{}:^\"\\+-!~*?| ters eğik çizgi (backslash) ile kaçış (escape) yapın. Veya daha hoşgörülü olan bir simple_query_string kullanın.

Parça (shard) nedir?Parçalar, bir dizinin parçalarıdır. Her parça bir Lucene dizinidir. Birincil parçalar yazma içindir, çoğaltma parçaları ise okuma ölçeklendirmesi ve hata toleransı için kopyalardır.

Kaç parça oluşturmalıyım?Genel kural: parça başına 20-50GB. 1 birincil parça ile başlayın, çoğaltmalar ekleyin. Birincil parçaları yalnızca gerektiğinde artırın (azaltılamaz).

İndekslemeden sonra eşlemeleri değiştirebilir miyim?Kısmen. Yeni alanları serbestçe ekleyebilirsiniz. Mevcut alan türlerini değiştirmek için verileri yeniden indeksleyin. Eşlemeleri tutarlı bir şekilde yönetmek için dizin şablonlarını kullanın.

_routing parametresi nedir?Belgeleri bir alan değerine göre belirli parçalara yönlendirir. Varsayılan _id'dir. Daha iyi performans için sorgular her zaman belirli bir alana (örneğin user_id) göre filtrelendiğinde yönlendirme kullanın.

Zaman tabanlı verileri nasıl işlerim?Tarih tabanlı dizinler kullanın: logs-2026.03.24. Bu, eski verileri dizinleri bırakarak silmenizi sağlar ve daha az dizin arayarak sorgu performansını artırır.