Built-in Analyzers — standard, simple, whitespace, language

Giriş — Hazır Takım Elbiseler

Bir mağazaya gidip takım elbise almak istediğinizi düşünün. İki seçeneğiniz var: Raftan hazır bir takım almak ya da terziye özel diktirmek. Hazır takımlar çoğu insan için gayet iyi çalışır — hızlıdır, test edilmiştir ve makul fiyatlıdır. Ama özel ihtiyaçlarınız varsa (özel bir beden, farklı bir kumaş) terziye gidersiniz.

Elasticsearch'ün built-in analyzer'ları bu hazır takımlara benzer. Çoğu senaryo için mükemmel çalışırlar ve sıfırdan bir şey yapılandırmanız gerekmez. Bu derste, Elasticsearch'ün sunduğu tüm built-in analyzer'ları derinlemesine inceleyeceğiz: ne zaman hangisini kullanmalısınız, avantajları ve sınırları nelerdir?

1. Built-in Analyzer Nedir?

Built-in analyzer, Elasticsearch'ün önceden yapılandırılmış ve kullanıma hazır olarak sunduğu analyzer'dır. Her biri belirli bir character filter + tokenizer + token filter kombinasyonudur.

Herhangi bir ayar yapmadan doğrudan kullanabilirsiniz:

POST _analyze
{
  "analyzer": "standard",
  "text": "Bu bir test cümlesidir."
}

Toplam 8 temel built-in analyzer vardır (artı 30+ dil analyzer'ı):

2. Standard Analyzer — Her Derde Deva

Standard analyzer, Elasticsearch'ün varsayılan analyzer'ıdır. Bir text field'ına analyzer belirtmezseniz, standard kullanılır.

Bileşenleri

• Character Filter: Yok

• Tokenizer: standard (Unicode Text Segmentation)

• Token Filters: lowercase (varsayılan), stop (devre dışı)

Nasıl Çalışır?

POST _analyze
{
  "analyzer": "standard",
  "text": "Elasticsearch 8.x sürümü, RESTful API üzerinden çalışır!"
}

Çıktı:

{
  "tokens": [
    { "token": "elasticsearch", "position": 0 },
    { "token": "8.x", "position": 1 },
    { "token": "sürümü", "position": 2 },
    { "token": "restful", "position": 3 },
    { "token": "api", "position": 4 },
    { "token": "üzerinden", "position": 5 },
    { "token": "çalışır", "position": 6 }
  ]
}

Gözlemler:

• Noktalama işaretleri (,, !) kaldırıldı

• Büyük harfler küçültüldü (Elasticsearch → elasticsearch, RESTful → restful)

• 8.x tek token olarak korundu (nokta kelime içi karakter olarak algılandı)

• Türkçe karakterler (ü, ı, ş, ç) korundu

Özelleştirme

Standard analyzer'ın davranışını max_token_length ve stopwords parametreleriyle değiştirebilirsiniz:

PUT my_index
{
  "settings": {
    "analysis": {
      "analyzer": {
        "my_standard": {
          "type": "standard",
          "max_token_length": 50,
          "stopwords": "_turkish_"
        }
      }
    }
  }
}

Test:

POST my_index/_analyze
{
  "analyzer": "my_standard",
  "text": "Bu bir Elasticsearch ve Kibana eğitimidir"
}

Çıktı: ["elasticsearch", "kibana", "eğitimidir"] — "Bu", "bir", "ve" gibi Türkçe stop words çıkarıldı.

Ne Zaman Kullanmalı?

✅ Genel amaçlı metin arama — blog, makale, ürün açıklaması ✅ Dil agnostik içerik — birden fazla dil içeren veriler ✅ Hızlı başlangıç — henüz hangi analyzer'ı kullanacağınıza karar vermediyseniz

❌ Dil-spesifik stemming gerekiyorsa (Türkçe ekleri çözemez) ❌ Log veya yapısal veri (IP, dosya yolu) aranacaksa

3. Simple Analyzer — Sadece Harfler

Simple analyzer sadece harflere bakar. Harf olmayan her karakter ayırıcıdır ve tüm token'lar küçük harfe çevrilir.

Bileşenleri

• Character Filter: Yok

• Tokenizer: letter (sadece harfler)

• Token Filters: lowercase

Nasıl Çalışır?

POST _analyze
{
  "analyzer": "simple",
  "text": "Elasticsearch 8.x sürümü — RESTful API v2.0"
}

Çıktı: ["elasticsearch", "x", "sürümü", "restful", "api", "v"]

Dikkat: Rakamlar (8, 2, 0) tamamen kayboldu! Simple analyzer rakamları ayırıcı olarak kabul eder.

Karşılaştırma: Standard vs Simple

POST _analyze
{
  "analyzer": "standard",
  "text": "user123@mail.com HTTP/1.1 200"
}
// Çıktı: ["user123", "mail.com", "http", "1.1", "200"]

POST _analyze
{
  "analyzer": "simple",
  "text": "user123@mail.com HTTP/1.1 200"
}
// Çıktı: ["user", "mail", "com", "http"]

Simple analyzer'da 123, 1.1 ve 200 tamamen kayboldu. E-posta adresi de parçalandı.

Ne Zaman Kullanmalı?

✅ Sadece kelime bazlı arama yapılacak, rakamlar önemsiz ✅ Çok basit metin alanları (ad, soyad gibi)

❌ Rakam içeren alanlar (sürüm numarası, kod, ürün kodu) ❌ E-posta, URL, IP gibi yapısal veriler

4. Whitespace Analyzer — Boşluklara Göre Böl

Whitespace analyzer en basit analyzer'dır — sadece boşluk karakterlerine göre böler, başka hiçbir dönüşüm yapmaz.

Bileşenleri

• Character Filter: Yok

• Tokenizer: whitespace

• Token Filters: Yok (lowercase bile yok!)

Nasıl Çalışır?

POST _analyze
{
  "analyzer": "whitespace",
  "text": "Elasticsearch 8.x sürümü, RESTful API!"
}

Çıktı: ["Elasticsearch", "8.x", "sürümü,", "RESTful", "API!"]

Dikkat:

• Büyük-küçük harf korunur — "Elasticsearch" ve "elasticsearch" farklı token'lardır

• Noktalama korunur — "sürümü," virgül içerir, "API!" ünlem içerir

• Rakamlar korunur

Case-Sensitivity Sorunu

// "elasticsearch" araması "Elasticsearch" token'ını BULAMAZ!
GET my_whitespace_index/_search
{
  "query": {
    "match": {
      "content": "elasticsearch"
    }
  }
}

Bu nedenle whitespace analyzer genellikle tek başına kullanılmaz — lowercase filter eklenir veya case-sensitive arama gerçekten isteniyordur.

Ne Zaman Kullanmalı?

✅ Log dosyaları — "ERROR [main] NullPointerException" gibi log mesajları ✅ Case-sensitive arama gerektiğinde ✅ Noktalama işaretlerinin korunması gerektiğinde ✅ Veriyi olduğu gibi token'lamak istediğinizde

❌ Kullanıcıya yönelik metin arama (büyük-küçük harf duyarlılığı sorun yaratır) ❌ Noktalama gereksiz olan durumlar

5. Stop Analyzer — Simple + Stop Words

Stop analyzer, simple analyzer'a stop words desteği ekler.

Bileşenleri

• Character Filter: Yok

• Tokenizer: letter

• Token Filters: lowercase, stop (varsayılan İngilizce)

Nasıl Çalışır?

POST _analyze
{
  "analyzer": "stop",
  "text": "The quick brown fox jumps over the lazy dog"
}

Çıktı: ["quick", "brown", "fox", "jumps", "over", "lazy", "dog"] — "The", "the" çıkarıldı.

Türkçe Stop Words

Varsayılan stop words listesi İngilizcedir. Türkçe için özelleştirme gerekir:

PUT tr_stop_index
{
  "settings": {
    "analysis": {
      "analyzer": {
        "turkish_stop_analyzer": {
          "type": "stop",
          "stopwords": "_turkish_"
        }
      }
    }
  }
}

POST tr_stop_index/_analyze
{
  "analyzer": "turkish_stop_analyzer",
  "text": "Bu bir Elasticsearch ve Kibana ile ilgili güzel bir kaynak"
}

Çıktı: ["elasticsearch", "kibana", "ilgili", "güzel", "kaynak"]

Ne Zaman Kullanmalı?

✅ Simple analyzer kullanacak ama stop words de çıkarmak istiyorsanız ❌ Stemming de gerekiyorsa (language analyzer tercih edin) ❌ Rakam önemliyse (letter tokenizer rakamları kaldırır)

6. Keyword Analyzer — Hiç Analiz Etme

Keyword analyzer metni hiç bölmez — tüm girdiyi tek token olarak döndürür.

Bileşenleri

• Character Filter: Yok

• Tokenizer: keyword (bölmez)

• Token Filters: Yok

Nasıl Çalışır?

POST _analyze
{
  "analyzer": "keyword",
  "text": "New York City, USA"
}

Çıktı: ["New York City, USA"] — Tüm metin tek token.

keyword Analyzer vs keyword Field Type

Bu ikisi sıklıkla karıştırılır:

// keyword field type — zaten analiz edilmez, inverted index + doc_values
"city": { "type": "keyword" }

// text field + keyword analyzer — analiz edilir ama sonuç aynı (tek token)
"city": { "type": "text", "analyzer": "keyword" }

İkisi arasındaki fark:

• keyword type: Aggregation, sorting, exact match için optimize

• text + keyword analyzer: Full-text scoring yapılır ama tek token olduğu için pratik fark azdır

Genelde `keyword` type kullanın. Keyword analyzer sadece özel durumlarda (normalizer benzeri davranış + text tipi gerekiyorsa) tercih edilir.

Ne Zaman Kullanmalı?

✅ Tam eşleşme gereken durumlar + text type zorunluluğu ✅ Case-insensitive keyword: keyword analyzer + lowercase filter

PUT case_insensitive_index
{
  "settings": {
    "analysis": {
      "analyzer": {
        "lowercase_keyword": {
          "type": "custom",
          "tokenizer": "keyword",
          "filter": ["lowercase"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "email": {
        "type": "text",
        "analyzer": "lowercase_keyword"
      }
    }
  }
}

Artık "User@Email.COM" ve "user@email.com" aynı token'a dönüşür.

7. Pattern Analyzer — Regex ile Bölme

Pattern analyzer, bir regular expression kullanarak metni token'lara böler.

Bileşenleri

• Character Filter: Yok

• Tokenizer: pattern (varsayılan: \W+ yani kelime olmayan karakterler)

• Token Filters: lowercase, stop (devre dışı)

Varsayılan Davranış

POST _analyze
{
  "analyzer": "pattern",
  "text": "user.name@email-provider.com HTTP/1.1"
}

Çıktı: ["user", "name", "email", "provider", "com", "http", "1", "1"]

Varsayılan \W+ pattern'ı, harf ve rakam olmayan her karakteri ayırıcı kabul eder.

Özelleştirme

Örneğin, camelCase metni kelimelerine bölmek:

PUT camel_case_index
{
  "settings": {
    "analysis": {
      "analyzer": {
        "camel_case_analyzer": {
          "type": "pattern",
          "pattern": "(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])|[\\s_\\-]",
          "lowercase": true
        }
      }
    }
  }
}

POST camel_case_index/_analyze
{
  "analyzer": "camel_case_analyzer",
  "text": "getUserName getHTTPResponse myVariable"
}

Çıktı: ["get", "user", "name", "get", "http", "response", "my", "variable"]

CSV Verisi Ayrıştırma

PUT csv_index
{
  "settings": {
    "analysis": {
      "analyzer": {
        "csv_analyzer": {
          "type": "pattern",
          "pattern": "[,;\\t]",
          "lowercase": false
        }
      }
    }
  }
}

POST csv_index/_analyze
{
  "analyzer": "csv_analyzer",
  "text": "Ahmet,30,İstanbul;Yazılımcı"
}

Çıktı: ["Ahmet", "30", "İstanbul", "Yazılımcı"]

Ne Zaman Kullanmalı?

✅ Özel ayırıcı karakterler olan veriler (CSV, pipe-delimited) ✅ CamelCase / snake_case bölme ✅ Yapılandırılmış metin formatları

❌ Genel metin arama (standard daha iyi) ❌ Karmaşık regex'ler — performans sorunlarına yol açabilir

8. Fingerprint Analyzer — Parmak İzi

Fingerprint analyzer, metni normalleştirip tekil bir "parmak izi" oluşturur. Deduplikasyon (kopya tespiti) için tasarlanmıştır.

Bileşenleri

• Character Filter: Yok

• Tokenizer: standard

• Token Filters: lowercase, asciifolding, stop (devre dışı), fingerprint

Nasıl Çalışır?

POST _analyze
{
  "analyzer": "fingerprint",
  "text": "Elasticsearch çok güçlü ve hızlı bir motordur"
}

Çıktı: ["bir cok elasticsearch guclü hizli motordur ve"]

Ne yaptı?

1. Küçük harfe çevirdi

2. ASCII dönüşümü yaptı (ç → c, ü → u, ı → i)

3. Token'ları alfabetik olarak sıraladı

4. Tekrar edenleri kaldırdı

5. Hepsini tek string olarak birleştirdi

Deduplikasyon Örneği

"Elasticsearch hızlı ve güçlü" → "elasticsearch guclü hizli ve"
"Güçlü ve hızlı Elasticsearch" → "elasticsearch guclü hizli ve"

İki farklı cümle aynı parmak izini üretti! Kelime sırası farklı olsa da aynı içerik.

Ne Zaman Kullanmalı?

✅ İçerik deduplikasyonu — aynı haberin farklı kaynaklardan geldiğini tespit ✅ Benzer metin tespiti

❌ Normal metin arama (tekli token aggregation/search için uygun değil) ❌ Türkçe veya dil-spesifik arama (asciifolding Türkçe karakterleri bozar)

9. Language Analyzers — Dile Özel Analiz

Elasticsearch 30'dan fazla dil için built-in analyzer sunar. Bu analyzer'lar her dilin gramer kurallarına göre stemming ve stop words uygular.

Desteklenen Diller (Öne Çıkanlar)

Turkish Analyzer Detayı

Turkish analyzer'ın bileşenleri:

• Tokenizer: standard

• Token Filters: lowercase (Türkçe özel — I → ı, İ → i), stop (Türkçe), stemmer (Snowball Turkish)

POST _analyze
{
  "analyzer": "turkish",
  "text": "Türkiye'deki geliştiriciler Elasticsearch ile çalışıyorlar"
}

Çıktı: ["türkiye'deki", "geliştirici", "elasticsearch", "çalış"]

Gözlemler:

• "geliştiriciler" → "geliştirici" (çoğul eki kaldırıldı)

• "çalışıyorlar" → "çalış" (zaman eki ve çoğul eki kaldırıldı)

• "ile" stop word olarak çıkarıldı

• Türkçeye özel büyük-küçük harf dönüşümü yapıldı

Türkçe Büyük-Küçük Harf Sorunu

Türkçe'de I → ı ve İ → i dönüşümü standart lowercase'den farklıdır:

// Standard lowercase — YANLIŞ Türkçe dönüşüm
POST _analyze
{
  "tokenizer": "standard",
  "filter": ["lowercase"],
  "text": "İSTANBUL ISPARTALILAR"
}
// Çıktı: ["istanbul", "ispartalilar"] — "ı" yerine "i" geldi!

// Turkish analyzer — DOĞRU dönüşüm
POST _analyze
{
  "analyzer": "turkish",
  "text": "İSTANBUL ISPARTALILAR"
}
// Çıktı: ["istanbul", "ispartalı"] — Türkçe karakterler doğru

⚠️ Kritik: Türkçe içerik index'liyorsanız, standard analyzer yerine turkish analyzer kullanın. Aksi halde I/İ ve ı/i dönüşümleri yanlış olur.

English Analyzer

POST _analyze
{
  "analyzer": "english",
  "text": "The developers are running quickly through the forests"
}

Çıktı: ["develop", "run", "quickli", "through", "forest"]

• "developers" → "develop" (stemming)

• "are" → kaldırıldı (stop word)

• "running" → "run" (stemming)

• "quickly" → "quickli" (stemming — Snowball algoritması)

• "forests" → "forest" (çoğul eki)

German Analyzer

POST _analyze
{
  "analyzer": "german",
  "text": "Die Entwickler arbeiten mit Elasticsearch zusammen"
}

Çıktı: ["entwickl", "arbeit", "elasticsearch", "zusamm"]

Language Analyzer'ları Özelleştirme

Built-in language analyzer'ları doğrudan özelleştiremezsiniz, ama aynı bileşenlerle custom bir analyzer oluşturabilirsiniz:

PUT custom_turkish_index
{
  "settings": {
    "analysis": {
      "filter": {
        "turkish_stop": {
          "type": "stop",
          "stopwords": "_turkish_"
        },
        "turkish_stemmer": {
          "type": "stemmer",
          "language": "turkish"
        },
        "turkish_lowercase": {
          "type": "lowercase",
          "language": "turkish"
        }
      },
      "analyzer": {
        "rebuilt_turkish": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": [
            "turkish_lowercase",
            "turkish_stop",
            "turkish_stemmer"
          ]
        }
      }
    }
  }
}

Bu sayede stop words listesine kendi kelimelerinizi ekleyebilir, stemmer'dan önce başka filter'lar koyabilirsiniz.

10. Analyzer Karşılaştırma Tablosu

Aynı metni farklı analyzer'larla analiz edelim:

Test metni: "İstanbul'daki 3 geliştiriciler, Elasticsearch ve Kibana ile çalışıyorlar!"

// Her analyzer için ayrı ayrı test edin
POST _analyze
{
  "analyzer": "ANALYZER_ADI",
  "text": "İstanbul'daki 3 geliştiriciler, Elasticsearch ve Kibana ile çalışıyorlar!"
}

Gözlemler:

• standard: Rakamları korur, stemming yapmaz

• simple: Rakamları kaybeder, apostrof'ta böler

• whitespace: Hiçbir dönüşüm yapmaz, büyük harf kalır, noktalama kalır

• stop: Simple + "ve", "ile" çıkarıldı

• keyword: Tüm metin tek token

• turkish: Stemming yaptı ("geliştiriciler" → "geliştirici"), stop words çıkardı

11. Doğru Analyzer'ı Seçme Rehberi

Karar Ağacı

Metin türü nedir?
│
├── Yapısal veri (e-posta, URL, kod, ID)?
│   └── keyword type veya uax_url_email tokenizer
│
├── Log / makine verisi?
│   └── whitespace veya pattern analyzer
│
├── Doğal dil metni?
│   ├── Tek dil mi?
│   │   ├── Evet → İlgili language analyzer (turkish, english, vb.)
│   │   └── Hayır → standard analyzer
│   └── Stemming gerekli mi?
│       ├── Evet → Language analyzer
│       └── Hayır → standard analyzer
│
├── Autocomplete / search-as-you-type?
│   └── Custom analyzer (edge_ngram) — sonraki derste
│
└── Deduplikasyon?
    └── fingerprint analyzer

Sık Kullanım Senaryoları

12. Java ile Built-in Analyzer Kullanımı

import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.elasticsearch.indices.AnalyzeRequest;
import co.elastic.clients.elasticsearch.indices.AnalyzeResponse;
import co.elastic.clients.elasticsearch.indices.analyze.AnalyzeToken;

public class BuiltinAnalyzerDemo {

    public static void analyzeWithBuiltin(ElasticsearchClient client) throws Exception {
        String testText = "İstanbul'daki geliştiriciler Elasticsearch ile çalışıyorlar";
        String[] analyzers = {"standard", "simple", "whitespace", "turkish", "keyword"};

        for (String analyzerName : analyzers) {
            AnalyzeResponse response = client.indices().analyze(a -> a
                .analyzer(analyzerName)
                .text(testText)
            );

            System.out.println("=== " + analyzerName + " ===");
            for (AnalyzeToken token : response.tokens()) {
                System.out.printf("  [%d] %s%n", token.position(), token.token());
            }
            System.out.println();
        }
    }

    public static void createIndexWithTurkishAnalyzer(ElasticsearchClient client) throws Exception {
        client.indices().create(c -> c
            .index("articles_tr")
            .mappings(m -> m
                .properties("title", p -> p
                    .text(t -> t.analyzer("turkish"))
                )
                .properties("content", p -> p
                    .text(t -> t.analyzer("turkish"))
                )
                .properties("category", p -> p
                    .keyword(k -> k)
                )
                .properties("tags", p -> p
                    .keyword(k -> k)
                )
            )
        );
        System.out.println("articles_tr index'i oluşturuldu.");
    }
}

13. Best Practices

✅ Yapın

❌ Yapmayın

14. Yaygın Hatalar ve Çözümleri

Hata 1: Türkçe İçerik + Standard Analyzer

// ❌ "çalışanlar" araması "çalışıyor" içeren dokümanı BULAMAZ
PUT wrong_index
{
  "mappings": {
    "properties": {
      "content": { "type": "text" }  // standard analyzer kullanılır
    }
  }
}

// ✅ Turkish analyzer ile stemming yapılır
PUT correct_index
{
  "mappings": {
    "properties": {
      "content": {
        "type": "text",
        "analyzer": "turkish"
      }
    }
  }
}

Hata 2: Analyzer Değiştirmek İçin Reindex Gerekmesi

Zaten veri olan bir index'in analyzer'ını değiştiremezsiniz:

// ❌ Bu hata verir
PUT existing_index/_mapping
{
  "properties": {
    "content": {
      "type": "text",
      "analyzer": "turkish"  // Analyzer değiştirilemez!
    }
  }
}

Çözüm: Yeni index oluşturun, _reindex ile veriyi taşıyın, alias ile geçiş yapın:

// 1. Yeni index oluştur
PUT new_index
{
  "mappings": {
    "properties": {
      "content": {
        "type": "text",
        "analyzer": "turkish"
      }
    }
  }
}

// 2. Veriyi taşı
POST _reindex
{
  "source": { "index": "existing_index" },
  "dest": { "index": "new_index" }
}

// 3. Alias ile geçiş
POST _aliases
{
  "actions": [
    { "remove": { "index": "existing_index", "alias": "my_alias" } },
    { "add": { "index": "new_index", "alias": "my_alias" } }
  ]
}

Hata 3: Çok Dilli İçerik İçin Tek Analyzer

// ❌ Sadece turkish analyzer — İngilizce içerik stemming yapılmaz
"content": {
  "type": "text",
  "analyzer": "turkish"
}

// ✅ Multi-field mapping ile her dil için ayrı analyzer
"content": {
  "type": "text",
  "analyzer": "standard",
  "fields": {
    "tr": {
      "type": "text",
      "analyzer": "turkish"
    },
    "en": {
      "type": "text",
      "analyzer": "english"
    }
  }
}

Aramada:

GET my_index/_search
{
  "query": {
    "multi_match": {
      "query": "geliştiriciler",
      "fields": ["content", "content.tr", "content.en"]
    }
  }
}

15. Performans Karşılaştırması

Stemming ve stop words uygulayan analyzer'lar biraz daha yavaştır ama daha az token üretir → daha küçük index.

Özet

• Standard analyzer varsayılandır ve çoğu senaryo için iyi bir başlangıçtır — ama Türkçe için yetersizdir

• Simple analyzer sadece harflerle çalışır — rakamları kaybeder, dikkatli kullanın

• Whitespace analyzer hiçbir dönüşüm yapmaz — log analizi için uygundur, genel arama için değil

• Keyword analyzer metni bölmez — tam eşleşme senaryoları için kullanılır

• Pattern analyzer regex ile özel bölme kuralları tanımlar — camelCase, CSV gibi formatlar için

• Language analyzer'lar (özellikle turkish) dile özel stemming ve stop words uygular — Türkçe içerik için şarttır

• Analyzer seçimi veri tipine ve kullanım senaryosuna göre yapılmalıdır — tek bir "en iyi" analyzer yoktur