잡학다식 개발일지

Bool Query (복합 쿼리) 개요

• 여러 개의 검색 조건을 조합하여 복합적인 검색을 수행할 수 있는 강력한 쿼리 방식입니다.
• SQL의 AND, OR, NOT과 유사하지만 완전히 동일하지 않음 → 단항 연산자로 적용됨.

Bool Query 구성 요소

• SQL과 비교
  • must ≈ AND
  • must_not ≈ NOT
  • should ≈ OR (점수 영향)
  • filter ≈ WHERE (점수 없음, 성능 최적화)

Bool Query 기본 문법

GET <인덱스명>/_search
{
  "query": {
    "bool": {
      "must": [
        { <쿼리> }
      ],
      "must_not": [
        { <쿼리> }
      ],
      "should": [
        { <쿼리> }
      ],
      "filter": [
        { <쿼리> }
      ]
    }
  }
}

• 각 키워드(must, must_not, should, filter) 안에는 여러 개의 조건을 배열 형식으로 입력 가능.

Bool Query 사용법

✅ 예제 1: "quick" 포함 + "lazy dog" 문장 포함 (AND 조건)

GET my_index/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "message": "quick" } },
        { "match_phrase": { "message": "lazy dog" } }
      ]
    }
  }
}

• "quick" 단어가 포함된 문서 + "lazy dog" 문장이 포함된 문서 검색
• 결과: "quick"과 "lazy dog"을 포함하는 문서 검색됨

✅ 예제 2: "quick" 또는 "lazy dog" (OR 조건 유사)

GET my_index/_search
{
  "query": {
    "bool": {
      "should": [
        { "match": { "message": "quick" } },
        { "match_phrase": { "message": "lazy dog" } }
      ],
      "minimum_should_match": 1
    }
  }
}

• should 사용 → "quick" 또는 "lazy dog" 중 하나라도 포함하면 검색됨
• minimum_should_match: 1 → 최소 하나의 조건을 만족하는 문서 포함
• 결과: "quick" 또는 "lazy dog" 중 하나라도 포함된 문서 검색됨

✅ 예제 3: "quick" & "lazy dog" 제외 (NOT 조건)

GET my_index/_search
{
  "query": {
    "bool": {
      "must_not": [
        { "match": { "message": "quick" } },
        { "match_phrase": { "message": "lazy dog" } }
      ]
    }
  }
}

• "quick"과 "lazy dog"이 포함되지 않은 문서만 검색
• 결과: "quick"과 "lazy dog"이 없는 문서 반환됨

✅ 예제 4: 특정 단어 포함 (must) + 특정 단어 제외 (must_not)

GET my_index/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "message": "fox" } }
      ],
      "must_not": [
        { "match": { "message": "lazy" } }
      ]
    }
  }
}

• "fox" 포함 & "lazy" 제외
• 결과: "fox"가 있는 문서 중 "lazy"가 없는 문서 검색됨

✅ 예제 5: 특정 단어 포함 (filter) - 점수 계산 없음

GET my_index/_search
{
  "query": {
    "bool": {
      "filter": [
        { "match": { "message": "fox" } }
      ]
    }
  }
}

• "fox"가 포함된 문서를 검색하지만, 점수(Score)를 계산하지 않음 → 빠름
• must와 비교하면 성능이 더 우수 (검색 결과가 많을수록 차이 커짐)

Bool Query와 SQL 비교

✅ 예제 6: SQL 스타일 변환

• SQL 스타일

  (A OR B) AND (NOT C)
  

• Bool Query 변환

  GET my_index/_search
  {
    "query": {
      "bool": {
        "must": [
          {
            "bool": {
              "should": [
                { "match": { "message": "A" } },
                { "match": { "message": "B" } }
              ],
              "minimum_should_match": 1
            }
          }
        ],
        "must_not": [
          { "match": { "message": "C" } }
        ]
      }
    }
  }
  

Bool Query 정리

🎯 추가 학습 추천

1. Boosting (검색 결과 가중치 조절)
2. Nested Query (중첩된 JSON 문서 검색)
3. Function Score Query (점수 조작)
4. Aggregations (데이터 그룹화 및 통계 분석)

Full Text Query 개요

• Elasticsearch는 강력한 풀 텍스트 검색 기능을 제공하며, 다양한 쿼리 방식이 있습니다.
• 주요 쿼리 종류
  • match_all: 전체 문서 검색
  • match: 부분 일치 검색 (OR / AND 조건 가능)
  • match_phrase: 순서 포함 정확한 구문 검색
  • query_string: 복잡한 검색 연산자 지원

예제 데이터 입력

• my_index 인덱스에 _bulk API를 사용하여 데이터 입력

POST my_index/_bulk
{"index":{"_id":1}}
{"message":"The quick brown fox"}
{"index":{"_id":2}}
{"message":"The quick brown fox jumps over the lazy dog"}
{"index":{"_id":3}}
{"message":"The quick brown fox jumps over the quick dog"}
{"index":{"_id":4}}
{"message":"Brown fox brown dog"}
{"index":{"_id":5}}
{"message":"Lazy jumping dog"}

• message 필드에 다양한 단어가 포함된 문서 5개 입력됨

match_all 쿼리 (모든 문서 검색)

✅ 쿼리 없이 실행하면 match_all 적용

GET my_index/_search

✅ 명시적으로 match_all 사용

GET my_index/_search
{
  "query": {
    "match_all": {}
  }
}

• 모든 문서를 검색
• hits.total.value에 검색된 문서 개수가 표시됨

match 쿼리 (부분 일치 검색)

✅ "dog" 포함 문서 검색

GET my_index/_search
{
  "query": {
    "match": {
      "message": "dog"
    }
  }
}

• "dog" 단어가 포함된 모든 문서 검색
• 결과: 4개 문서 검색됨 (_id: 2, 3, 4, 5)

✅ 여러 개의 검색어 (OR 조건)

GET my_index/_search
{
  "query": {
    "match": {
      "message": "quick dog"
    }
  }
}

• "quick" 또는 "dog" 중 하나라도 포함된 문서를 검색
• 결과: 5개 문서 검색됨 (_id: 1, 2, 3, 4, 5)

✅ 여러 개의 검색어 (AND 조건)

• operator: "and" 옵션을 사용

GET my_index/_search
{
  "query": {
    "match": {
      "message": {
        "query": "quick dog",
        "operator": "and"
      }
    }
  }
}

• "quick"과 "dog"을 모두 포함하는 문서만 검색
• 결과: 2개 문서 검색됨 (_id: 2, 3)

5. match_phrase 쿼리 (정확한 구문 검색)

✅ "lazy dog" 검색

GET my_index/_search
{
  "query": {
    "match_phrase": {
      "message": "lazy dog"
    }
  }
}

• **"lazy dog"**이라는 정확한 문장이 포함된 문서 검색
• 결과: 1개 문서 검색됨 (_id: 2)

✅ match_phrase + slop 옵션 (단어 간격 허용)

GET my_index/_search
{
  "query": {
    "match_phrase": {
      "message": {
        "query": "lazy dog",
        "slop": 1
      }
    }
  }
}

• 설명
  • "lazy dog" 사이에 다른 단어가 1개까지 허용
  • "lazy jumping dog" 문장도 검색됨
• 결과: 2개 문서 검색됨 (_id: 2, 5)
• 추가 설정 가능
  • slop: 2 → "lazy jumping brown dog" 같은 문장도 검색 가능

query_string 쿼리 (복잡한 검색)

• 루씬(Lucene) 문법을 활용한 고급 검색
• 연산자 사용 가능 (AND, OR, NOT)
• 필드 지정 가능 (default_field)

✅ "lazy" AND "jumping" OR "quick dog" 검색

GET my_index/_search
{
  "query": {
    "query_string": {
      "default_field": "message",
      "query": "(jumping AND lazy) OR \"quick dog\""
    }
  }
}

• "lazy"와 "jumping"을 모두 포함하거나 "quick dog" 문장을 포함하는 문서 검색
• 결과: 2개 문서 검색됨 (_id: 3, 5)

Full Text Query 정리

🎯 추가 학습 추천

1. bool 쿼리 (복합 조건 검색)
2. term 쿼리 (정확한 단어 검색)
3. wildcard & regex 검색
4. fuzzy 검색 (오타 교정 검색)

Search API 개요

• Elasticsearch의 **가장 핵심적인 기능은 검색(Querying)**입니다.
• _search API는 인덱스 단위로 검색을 수행합니다.
• 기본 사용법:

  GET <인덱스명>/_search
  

  • 쿼리를 입력하지 않으면 **모든 문서(match_all)**를 검색합니다.

URI 검색

• _search?q=검색어 형식으로 간단한 검색이 가능합니다.
• URI 검색의 장점
  • 웹 브라우저 주소창에서도 쉽게 사용 가능
  • 단순 검색에 적합

✅ 예제 1: 전체 인덱스에서 "value" 검색

GET test/_search?q=value

• 결과 (hits.total.value에 검색된 문서 개수 표시)

  {
    "hits": {
      "total": { "value": 1 },
      "hits": [ {...} ]
    }
  }
  

✅ 예제 2: "value" AND "three" 검색

GET test/_search?q=value AND three

• 설명
  • AND, OR, NOT 연산자 사용 가능 (대문자로 입력해야 함)
  • "value"와 "three"를 모두 포함하는 문서 검색

✅ 예제 3: 특정 필드에서 검색

GET test/_search?q=field:value

• 설명
  • field 필드에서 "value"를 검색

⚠ URI 검색의 한계

• 복잡한 검색 불가능 (예: 여러 개의 필드 조합, 필터링)
• Query DSL보다 기능이 제한적
• 권장: 단순 검색에만 사용하고, 복잡한 검색은 Query DSL 사용

데이터 본문(Data Body) 검색

• Elasticsearch의 Query DSL을 이용한 검색 방식
• JSON 형식의 검색 쿼리를 사용하며, 보다 강력한 검색 기능 제공

✅ 예제 1: match 쿼리 (기본 검색)

GET test/_search
{
  "query": {
    "match": {
      "field": "value"
    }
  }
}

• 설명
  • "field" 필드에서 "value"를 검색
  • match 쿼리는 자연어 검색에 적합 (부분 일치 가능)

✅ 예제 2: match_all (전체 문서 조회)

GET test/_search
{
  "query": {
    "match_all": {}
  }
}

• 설명: 모든 문서를 검색 (특정 조건 없이 전체 조회)

✅ 예제 3: 특정 필드에서 여러 키워드 검색

GET test/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "field1": "value1" } },
        { "match": { "field2": "value2" } }
      ]
    }
  }
}

• 설명
  • "field1"에서 "value1"을 찾고
  • "field2"에서 "value2"도 함께 검색
  • AND 조건 검색

멀티테넌시 (Multitenancy)

• 여러 개의 인덱스를 한 번에 검색할 수 있음
• **주로 로그 데이터 분석(Log Analysis)**에 사용됨

✅ 예제 1: 쉼표(,)로 여러 인덱스 검색

GET logs-2018-01,logs-2018-02/_search

• "logs-2018-01" 과 "logs-2018-02" 인덱스에서 검색

✅ 예제 2: 와일드카드(*)를 이용한 다중 인덱스 검색

GET logs-2018-*/_search

• "logs-2018-"로 시작하는 모든 인덱스에서 검색

✅ 예제 3: 모든 인덱스에서 검색 (_all)

GET _all/_search

• ⚠ 주의: _all은 시스템 부하를 초래할 수 있음
  • Elasticsearch 클러스터 내의 모든 인덱스를 검색하므로, 대량 데이터 환경에서는 권장되지 않음
  • 특정 인덱스 패턴을 지정하는 것이 좋음

Search API 정리

🎯 추가 학습 추천

1. 복합 쿼리(Query DSL - bool 쿼리)
   • 필터링과 랭킹을 조합한 강력한 검색 방식
2. 검색 결과 정렬 및 페이징 (from, size)
3. 어그리게이션(Aggregation) 사용법
4. Highlighting (검색어 하이라이트)

Elasticsearch의 도큐먼트 URL 구조

• Elasticsearch에서는 단일 도큐먼트마다 고유한 URL을 갖습니다.
• 도큐먼트 접근 URL 구조:

  http://<호스트>:<포트>/<인덱스>/_doc/<도큐먼트 ID>
  

• Elasticsearch 6.x 이전 버전에서는 다음과 같은 구조였으나,

  http://<호스트>:<포트>/<인덱스>/<도큐먼트 타입>/<도큐먼트 ID>
  

  Elasticsearch 7.0부터는 도큐먼트 타입 개념이 제거되고 _doc으로 접근해야 합니다.

데이터 입력 (Create & Update)

✅ PUT 요청으로 도큐먼트 입력

PUT my_index/_doc/1
{
  "name": "Jongmin Kim",
  "message": "안녕하세요 Elasticsearch"
}

• 결과 예시

  {
    "_index": "my_index",
    "_type": "_doc",
    "_id": "1",
    "_version": 1,
    "result": "created",
    "_shards": {"total": 2, "successful": 1, "failed": 0},
    "_seq_no": 0,
    "_primary_term": 1
  }
  

• 같은 ID로 다시 입력하면 기존 데이터가 덮어쓰기(Overwrite)되며 "result": "updated" 로 변경됩니다.

✅ 데이터 덮어쓰지 않고 새 도큐먼트만 입력 (_create 사용)

PUT my_index/_create/1
{
  "name": "Jongmin Kim",
  "message": "안녕하세요 Elasticsearch"
}

• 이미 ID가 존재하는 경우 오류 발생:

  {
    "error": {
      "type": "version_conflict_engine_exception",
      "reason": "document already exists"
    },
    "status": 409
  }
  

데이터 조회 (Read)

✅ GET 요청으로 도큐먼트 조회

GET my_index/_doc/1

• 응답 예시:

  {
    "_index": "my_index",
    "_type": "_doc",
    "_id": "1",
    "_version": 1,
    "found": true,
    "_source": {
      "name": "Jongmin Kim",
      "message": "안녕하세요 Elasticsearch"
    }
  }
  

• 삭제된 도큐먼트 또는 없는 도큐먼트 조회 시

  {
    "_index": "my_index",
    "_type": "_doc",
    "_id": "1",
    "found": false
  }
  

데이터 수정 (Update)

✅ 부분 업데이트 (_update API 사용)

• 특정 필드만 수정할 때 사용 (doc 키워드 활용)

POST my_index/_update/1
{
  "doc": {
    "message": "안녕하세요 Kibana"
  }
}

• 응답 결과 (_version 증가)

  {
    "_index": "my_index",
    "_type": "_doc",
    "_id": "1",
    "_version": 2,
    "result": "updated",
    "_shards": {"total": 2, "successful": 1, "failed": 0}
  }
  

• 주의사항: 내부적으로 기존 도큐먼트를 가져와 변경 후 새 도큐먼트로 재저장하는 방식이므로 부분 업데이트처럼 보이지만 실제로는 전체 덮어쓰기가 발생합니다.

데이터 삭제 (Delete)

✅ 도큐먼트 삭제

DELETE my_index/_doc/1

• 응답 결과

  {
    "_index": "my_index",
    "_type": "_doc",
    "_id": "1",
    "result": "deleted"
  }
  

• 삭제된 도큐먼트 조회 시

  {
    "_index": "my_index",
    "_type": "_doc",
    "_id": "1",
    "found": false
  }
  

✅ 전체 인덱스 삭제

DELETE my_index

• 응답 결과

  {
    "acknowledged": true
  }
  

• 삭제된 인덱스의 도큐먼트 조회 시 오류 발생

  {
    "error": {
      "type": "index_not_found_exception",
      "reason": "no such index"
    },
    "status": 404
  }
  

자동 생성되는 도큐먼트 ID 활용

✅ POST 요청으로 자동 생성되는 도큐먼트 ID

POST my_index/_doc
{
  "name": "Jongmin Kim",
  "message": "안녕하세요 Elasticsearch"
}

• 응답 결과 (_id가 자동 생성됨)

  {
    "_index": "my_index",
    "_type": "_doc",
    "_id": "ZuFv12wBspWtEG13dOut",
    "_version": 1,
    "result": "created"
  }
  

Elasticsearch 6.x 이전 버전과의 차이점

✅ 정리

🎯 추가로 알아두면 좋은 개념

1. 버전 관리 (_version): Elasticsearch는 도큐먼트의 변경 시 버전을 증가시킵니다.
2. 샤드 & 레플리카: 데이터를 분산 저장하여 고가용성을 유지합니다.
3. Query DSL: 복잡한 검색 기능을 위한 JSON 기반의 질의 언어입니다.
4. Bulk API: 대량의 데이터를 한 번에 처리할 수 있는 API입니다.

REST API 개요

• Elasticsearch는 HTTP 프로토콜 기반의 REST API를 제공합니다.
• 자원(Resource)마다 고유한 URL을 사용하며, **HTTP 메서드(PUT, POST, GET, DELETE)**로 데이터를 처리합니다.
• 이러한 시스템을 RESTFul 시스템이라고 합니다.

REST API 방식과 비 REST 방식 비교

예제: 사용자 정보(name=kim, age=38, gender=m) 처리 방식 비교

Elasticsearch REST API 활용

(1) 클러스터 정보 조회

• HTTP 요청 방법: GET http://localhost:9200
• curl 명령어 사용 예제

  curl -XGET "http://localhost:9200"
  

• 응답 예시 (JSON)

  {
    "name" : "Jongminui-MacBook-Pro.local",
    "cluster_name" : "elasticsearch",
    "cluster_uuid" : "hpmT8TPiR1Kk69YNao9V3w",
    "version" : {
      "number" : "7.3.0",
      "build_flavor" : "default",
      "build_type" : "tar",
      "build_hash" : "de777fa",
      "build_date" : "2019-07-24T18:30:11.767338Z",
      "lucene_version" : "8.1.0"
    },
    "tagline" : "You Know, for Search"
  }
  

• 응답 정보 설명

  필드명	설명
  name	노드명
  cluster_name	클러스터명
  cluster_uuid	클러스터 고유 ID
  version.number	Elasticsearch 버전
  lucene_version	Lucene 버전
  tagline	기본 태그라인

Kibana Dev Tools

• REST API를 쉽게 실행하기 위한 도구
• Kibana 실행 방법
  1. Elastic 공식 웹사이트에서 Kibana 다운로드: https://www.elastic.co
  2. 압축 해제 후 실행
     • 리눅스/Mac: bin/kibana
     • 윈도우: bin/kibana.bat
  3. 기본 실행 포트: 5601
  4. 실행 후 웹 브라우저에서 접속: http://localhost:5601
• 설정 파일 (kibana.yml) 수정
  • Elasticsearch가 다른 호스트에서 실행될 경우: 
  • elasticsearch.url: "http://localhost:9200"
  • Kibana 실행 포트를 변경하려면:

    server.port: 5601
    

• Dev Tools 주요 기능

  기능	설명
  쿼리 자동 완성	API 호출 시 자동 완성 기능 제공
  호스트 경로 자동 적용	기본적으로 http://localhost:9200를 사용
  curl 명령 복사 기능	입력한 명령을 curl 명령어로 변환 가능

REST API를 활용한 Elasticsearch 데이터 조작

추가적으로 알아야 할 내용

✅ 정리

• Elasticsearch는 HTTP REST API를 활용하여 데이터를 관리합니다.
• RESTFul 방식을 사용하여 단일 URL과 HTTP 메서드(GET, PUT, DELETE 등)로 요청을 처리합니다.
• curl 명령어를 이용하여 쉽게 API 요청을 보낼 수 있습니다.
• Kibana Dev Tools를 활용하면 REST API 호출을 간편하게 실행할 수 있습니다.
• 문서 조회, 생성, 수정, 삭제 등의 작업은 REST API를 통해 JSON 기반으로 수행됩니다.

Elasticsearch 커스텀 플러그인 개발

📌 Elasticsearch는 기본적으로 강력한 기능을 제공하지만, 특정한 기능을 추가하거나 성능을 개선하려면 커스텀 플러그인을 개발해야 합니다.

• 플러그인은 Ingest Processor 추가, Query 확장, REST API 확장 등의 기능을 수행할 수 있습니다.

Elasticsearch Plugin 개발 환경 설정

Elasticsearch 플러그인은 Java로 개발되며,
Gradle을 사용하여 빌드하고 Elasticsearch Core API를 활용합니다.

✅ (1) 개발 환경 준비

📌 필수 요구사항

• JDK 17 이상
• Elasticsearch 8.x 버전
• Gradle 7.x 이상
• IntelliJ IDEA 또는 Eclipse (권장)

✅ (2) 플러그인 프로젝트 생성

Elasticsearch의 플러그인은 Gradle 프로젝트로 구성됩니다.

mkdir my-elasticsearch-plugin
cd my-elasticsearch-plugin

✅ (3) build.gradle 설정

Gradle을 사용하여 Elasticsearch 플러그인 프로젝트를 설정합니다.

plugins {
    id 'java'
    id 'elasticsearch.esplugin' version '8.0.0'
}

group = 'org.elasticsearch.plugin'
version = '1.0'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.elasticsearch:elasticsearch:8.0.0'
    testImplementation 'junit:junit:4.13.2'
}

esplugin {
    name 'my-custom-plugin'
    description 'Custom Elasticsearch Plugin'
    classname 'org.elasticsearch.plugin.MyPlugin'
}

✅ Elasticsearch 플러그인 Gradle 설정을 완료.

커스텀 Ingest Processor 개발

Elasticsearch의 Ingest Processor는 색인 전에 데이터를 변환하는 기능을 수행합니다.

✅ (1) MyCustomProcessor.java 생성

package org.elasticsearch.plugin;

import org.elasticsearch.ingest.AbstractProcessor;
import org.elasticsearch.ingest.IngestDocument;
import org.elasticsearch.ingest.Processor;

import java.util.Map;

public class MyCustomProcessor extends AbstractProcessor {

    private final String field;
    private final String prefix;

    protected MyCustomProcessor(String tag, String field, String prefix) {
        super(tag);
        this.field = field;
        this.prefix = prefix;
    }

    @Override
    public IngestDocument execute(IngestDocument document) {
        String value = document.getFieldValue(field, String.class);
        document.setFieldValue(field, prefix + value);
        return document;
    }

    @Override
    public String getType() {
        return "my_custom";
    }

    public static class Factory implements Processor.Factory {
        @Override
        public MyCustomProcessor create(Map<String, Processor.Factory> factories, String tag, Map<String, Object> config) {
            String field = (String) config.get("field");
            String prefix = (String) config.get("prefix");
            return new MyCustomProcessor(tag, field, prefix);
        }
    }
}

✅ 이 플러그인은 특정 필드의 값을 가져와서 prefix를 추가하는 기능 수행.

✅ (2) MyPlugin.java 생성

package org.elasticsearch.plugin;

import org.elasticsearch.plugins.IngestPlugin;
import org.elasticsearch.plugins.Plugin;
import org.elasticsearch.ingest.Processor;

import java.util.Map;

public class MyPlugin extends Plugin implements IngestPlugin {
    @Override
    public Map<String, Processor.Factory> getProcessors(Processor.Parameters parameters) {
        return Map.of("my_custom", new MyCustomProcessor.Factory());
    }
}

✅ 플러그인을 Elasticsearch에 등록.

✅ (3) 플러그인 빌드 및 설치

./gradlew build

elasticsearch-plugin install file:///path/to/my-custom-plugin.zip

✅ 플러그인을 빌드하고 Elasticsearch에 설치.

✅ (4) Ingest Pipeline 설정

PUT _ingest/pipeline/custom_pipeline
{
  "description": "My Custom Processor Pipeline",
  "processors": [
    {
      "my_custom": {
        "field": "message",
        "prefix": "[CUSTOM] "
      }
    }
  ]
}

✅ message 필드에 [CUSTOM] 접두어를 추가하는 Ingest Pipeline 설정.

✅ (5) 테스트 데이터 색인

PUT my-index/_doc/1?pipeline=custom_pipeline
{
  "message": "Hello Elasticsearch"
}

GET my-index/_search

✅ 결과: "message": "[CUSTOM] Hello Elasticsearch" 로 변환됨.

Java 클라이언트 (High-Level REST Client) 사용법

Elasticsearch의 Java 클라이언트를 사용하면 Elasticsearch API를 손쉽게 호출 가능.

✅ (1) pom.xml 또는 build.gradle 설정

<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-java</artifactId>
    <version>8.0.0</version>
</dependency>

✅ Elasticsearch Java 클라이언트 추가.

✅ (2) Java에서 Elasticsearch 연결

import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.elasticsearch._types.query_dsl.Query;
import co.elastic.clients.transport.endpoints.BooleanResponse;
import co.elastic.clients.transport.rest_client.RestClientTransport;
import org.apache.http.HttpHost;
import org.elasticsearch.client.RestClient;
import org.elasticsearch.client.RestHighLevelClient;

public class ElasticsearchService {

    private static final String ELASTICSEARCH_URL = "http://localhost:9200";

    public static void main(String[] args) throws Exception {
        RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200)).build();
        ElasticsearchClient client = new ElasticsearchClient(new RestClientTransport(restClient));

        // 인덱스 존재 여부 확인
        BooleanResponse exists = client.indices().exists(c -> c.index("my-index"));
        System.out.println("Index exists: " + exists.value());

        // 문서 색인
        client.index(i -> i.index("my-index").id("1").document(Map.of("message", "Hello from Java Client")));

        // 문서 검색
        Query query = Query.of(q -> q.match(m -> m.field("message").query("Hello")));
        var response = client.search(s -> s.index("my-index").query(query), Map.class);

        System.out.println("Search result: " + response.hits().hits());
    }
}

✅ Elasticsearch에 연결하여 색인 및 검색 수행.

Elasticsearch 커스텀 플러그인 개발 정리

Elasticsearch 운영 및 모니터링

📌 Elasticsearch를 안정적으로 운영하기 위해서는 **모니터링, 메모리 관리, 인덱스 라이프사이클 관리(ILM), 애플리케이션 성능 모니터링(APM)**이 필수적입니다.

Monitoring (클러스터 및 노드 상태 모니터링)

Elasticsearch의 클러스터 및 노드 상태를 _cluster/stats, _nodes/stats API를 사용하여 실시간 모니터링할 수 있습니다.

✅ (1) 클러스터 상태 조회

GET _cluster/health

🔹 응답 예시

{
  "cluster_name": "my-cluster",
  "status": "yellow",
  "number_of_nodes": 3,
  "number_of_data_nodes": 2,
  "active_primary_shards": 5,
  "active_shards": 10,
  "unassigned_shards": 1
}

✅ "status":

• "green" → 모든 샤드가 정상적으로 할당됨.
• "yellow" → 일부 복제본(Replica)이 할당되지 않음.
• "red" → 일부 프라이머리 샤드(Primary Shard) 할당 불가 (데이터 손실 가능).

✅ (2) 클러스터 통계 조회

GET _cluster/stats

✅ 샤드 개수, 노드 수, 디스크 사용량 등 클러스터 전반적인 상태 확인.

✅ (3) 노드 상태 조회

GET _nodes/stats

✅ 각 노드의 CPU, 메모리, 디스크 사용량 확인 가능.

✅ (4) Elasticsearch에 Kibana X-Pack Monitoring 연동

• Kibana의 Stack Monitoring 기능을 사용하면 Elasticsearch의 상태를 시각적으로 모니터링 가능.
• xpack.monitoring.collection.enabled: true 설정 필요.

xpack.monitoring.collection.enabled: true

✅ Elasticsearch 클러스터와 노드 상태를 Kibana에서 실시간으로 모니터링.

Elasticsearch Heap Memory 관리

Elasticsearch는 JVM Heap Memory를 사용하기 때문에 메모리 관리가 중요합니다.
JVM Heap이 부족하면 GC(가비지 컬렉션) 오버헤드 증가 → 성능 저하 발생.

✅ (1) Heap Memory 크기 확인

GET _nodes/stats/jvm

🔹 응답 예시

{
  "nodes": {
    "node-1": {
      "jvm": {
        "mem": {
          "heap_used_percent": 75,
          "heap_used_in_bytes": 8048000000,
          "heap_max_in_bytes": 10737418240
        }
      }
    }
  }
}

✅ Heap 사용량이 75% 이상이면 메모리 최적화 필요.

✅ (2) Heap Memory 설정 (jvm.options)

-Xms4g
-Xmx4g

✅ Heap 크기는 전체 서버 메모리의 50% 이하로 설정 (최대 32GB 미만).

✅ (3) 가비지 컬렉션 튜닝 (jvm.options)

-XX:+UseG1GC

✅ G1GC(Garbage First Garbage Collector) 사용하여 GC 성능 최적화.

Index Lifecycle Management (ILM)

ILM(Index Lifecycle Management)은 인덱스의 라이프사이클을 자동으로 관리하는 기능입니다.
이를 통해 디스크 공간 절약, 성능 최적화, 자동 삭제가 가능합니다.

✅ (1) ILM 정책 생성

PUT _ilm/policy/log_policy
{
  "policy": {
    "phases": {
      "hot": {
        "min_age": "0ms",
        "actions": {
          "rollover": {
            "max_size": "50gb",
            "max_age": "7d"
          }
        }
      },
      "warm": {
        "min_age": "30d",
        "actions": {
          "allocate": {
            "number_of_replicas": 1,
            "include": { "box_type": "warm" }
          }
        }
      },
      "delete": {
        "min_age": "90d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

✅ 7일 또는 50GB가 넘으면 새로운 인덱스로 롤오버 → 30일 후 Warm 노드로 이동 → 90일 후 삭제.

✅ (2) ILM 정책을 인덱스에 적용

PUT _index_template/logs_template
{
  "index_patterns": ["logs-*"],
  "template": {
    "settings": {
      "index.lifecycle.name": "log_policy"
    }
  }
}

✅ 새로 생성되는 logs-* 인덱스에 ILM 정책 자동 적용.

Elastic APM (Application Performance Monitoring)

Elastic APM은 애플리케이션의 성능을 모니터링하고 문제를 분석할 수 있도록 도와줍니다.

✅ (1) Elastic APM 서버 설치

docker run -d --name apm-server -p 8200:8200 --user=apm-server elastic/apm-server:8.x

✅ APM 서버를 실행하여 애플리케이션 데이터를 수집할 준비 완료.

✅ (2) APM 설정 (apm-server.yml)

apm-server:
  host: "0.0.0.0:8200"

output.elasticsearch:
  hosts: ["http://localhost:9200"]

✅ APM 데이터를 Elasticsearch로 전송.

✅ (3) 애플리케이션에 APM 에이전트 적용

🔹 Node.js (Express)

require('elastic-apm-node').start({
  serviceName: 'my-node-app',
  serverUrl: 'http://localhost:8200'
});

✅ APM 에이전트를 Node.js 애플리케이션에 추가하여 성능 모니터링.

✅ (4) Kibana에서 APM 데이터 확인

• Kibana → APM 메뉴에서 응답 시간, 에러율, 트랜잭션 분석 가능.
• Slow Query 분석, 서비스간 연관 관계 분석 지원.

Elasticsearch 운영 및 모니터링 정리

Logstash 및 Beats 활용 (ELK Stack 구성)

📌 ELK Stack은 Elasticsearch, Logstash, Kibana를 포함하는 로그 및 데이터 분석 솔루션입니다.

• Logstash: 다양한 데이터 소스로부터 데이터를 수집 및 변환하여 Elasticsearch에 전달
• Beats: 경량 데이터 수집기(Filebeat, Metricbeat, Heartbeat)
• Kafka 연동: 대용량 데이터 스트리밍을 위한 Apache Kafka와 Elasticsearch 연결

Logstash를 이용한 데이터 수집 및 변환

Logstash는 다양한 소스로부터 데이터를 수집하여 필터링, 변환 후 Elasticsearch로 전송하는 도구입니다.

✅ (1) Logstash 설치

wget https://artifacts.elastic.co/downloads/logstash/logstash-8.x.x-linux-x86_64.tar.gz
tar -xzf logstash-8.x.x-linux-x86_64.tar.gz
cd logstash-8.x.x-linux-x86_64

✅ Logstash 다운로드 및 압축 해제 후 실행 준비.

✅ (2) Logstash 기본 구성 (logstash.conf)

Logstash의 설정 파일은 Input → Filter → Output 구조를 가집니다.

input {
  file {
    path => "/var/log/syslog"
    start_position => "beginning"
  }
}

filter {
  grok {
    match => { "message" => "%{SYSLOGTIMESTAMP:timestamp} %{HOSTNAME:host} %{GREEDYDATA:log}" }
  }
  date {
    match => [ "timestamp", "MMM  d HH:mm:ss", "MMM dd HH:mm:ss" ]
    target => "@timestamp"
  }
}

output {
  elasticsearch {
    hosts => ["http://localhost:9200"]
    index => "syslog-%{+YYYY.MM.dd}"
  }
}

✅ 파일 로그(/var/log/syslog)를 읽고 변환하여 Elasticsearch에 저장.
✅ grok을 사용하여 timestamp, host, log 필드로 분리.
✅ 데이터를 날짜별 인덱스로 저장 (syslog-YYYY.MM.dd).

✅ (3) Logstash 실행

bin/logstash -f logstash.conf

✅ Logstash 실행 후 데이터를 Elasticsearch로 전송.

✅ (4) Elasticsearch에서 데이터 확인

GET syslog-*/_search
{
  "query": {
    "match_all": {}
  }
}

✅ Elasticsearch에서 Logstash를 통해 수집된 로그 데이터 조회.

Beats 활용 (Filebeat, Metricbeat, Heartbeat)

Beats는 경량 데이터 수집기로, 개별 서버에서 실행되며 Logstash 또는 Elasticsearch로 데이터를 전송할 수 있습니다.

✅ (1) Filebeat - 로그 파일 수집

Filebeat는 파일 로그를 모니터링하고 전송하는 경량 데이터 수집기입니다.

📌 Filebeat 설정 (filebeat.yml)

filebeat.inputs:
  - type: log
    paths:
      - /var/log/syslog

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  index: "filebeat-%{+YYYY.MM.dd}"

✅ 파일 로그(/var/log/syslog)를 모니터링하고 Elasticsearch에 저장.

✅ (2) Metricbeat - 시스템 메트릭 수집

Metricbeat는 CPU, 메모리, 네트워크 등의 시스템 메트릭을 수집합니다.

📌 Metricbeat 설정 (metricbeat.yml)

metricbeat.modules:
  - module: system
    metricsets:
      - cpu
      - memory
      - network
    enabled: true
    period: 10s

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  index: "metricbeat-%{+YYYY.MM.dd}"

✅ CPU, 메모리, 네트워크 메트릭을 10초마다 수집하여 Elasticsearch에 저장.

✅ (3) Heartbeat - 서비스 상태 모니터링

Heartbeat는 웹 서비스 및 TCP, ICMP 등의 연결 상태를 모니터링합니다.

📌 Heartbeat 설정 (heartbeat.yml)

heartbeat.monitors:
  - type: http
    schedule: '@every 10s'
    urls:
      - "http://localhost:5601"
      - "http://localhost:9200"

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  index: "heartbeat-%{+YYYY.MM.dd}"

✅ Elasticsearch와 Kibana 상태를 10초마다 체크하여 Elasticsearch에 저장.

Kafka와 Elasticsearch 연동

대량의 로그 및 이벤트 데이터를 실시간으로 처리할 때 Kafka를 중간 버퍼로 사용하여 Elasticsearch로 전송할 수 있습니다.

✅ (1) Kafka 설치 및 실행

wget https://downloads.apache.org/kafka/3.0.0/kafka_2.13-3.0.0.tgz
tar -xzf kafka_2.13-3.0.0.tgz
cd kafka_2.13-3.0.0

# Zookeeper 실행
bin/zookeeper-server-start.sh config/zookeeper.properties

# Kafka 실행
bin/kafka-server-start.sh config/server.properties

✅ Zookeeper와 Kafka를 실행하여 메시지 큐 준비.

✅ (2) Kafka에 로그 데이터 전송

bin/kafka-topics.sh --create --topic logs --bootstrap-server localhost:9092
bin/kafka-console-producer.sh --topic logs --bootstrap-server localhost:9092

✅ Kafka 토픽(logs)을 생성하고 로그 메시지를 입력하여 테스트.

✅ (3) Logstash를 사용하여 Kafka → Elasticsearch 데이터 전송

input {
  kafka {
    bootstrap_servers => "localhost:9092"
    topics => ["logs"]
    group_id => "logstash-group"
  }
}

filter {
  json {
    source => "message"
  }
}

output {
  elasticsearch {
    hosts => ["http://localhost:9200"]
    index => "kafka-logs-%{+YYYY.MM.dd}"
  }
}

✅ Kafka에서 데이터를 읽어 Elasticsearch로 저장.

✅ (4) 데이터 확인

GET kafka-logs-*/_search
{
  "query": {
    "match_all": {}
  }
}

✅ Kafka를 통해 전달된 로그 데이터가 Elasticsearch에 정상적으로 저장되었는지 확인.

Logstash 및 Beats 활용 정리

Elasticsearch 보안 및 인증 설정

📌 Elasticsearch는 기본적으로 X-Pack Security 기능을 제공하며,

• 사용자 인증, 역할 기반 액세스 제어(RBAC), TLS/SSL 암호화, API 키 인증 등의 보안 기능을 설정할 수 있습니다.

Role-based Access Control (RBAC) - 역할 기반 접근 제어

RBAC(Role-Based Access Control)은 사용자별 역할(Role)을 정의하여 접근 권한을 제한하는 기능입니다.
이를 통해 읽기(Read), 쓰기(Write), 관리(Admin) 등의 권한을 유연하게 설정할 수 있습니다.

✅ (1) 사용자 생성

bin/elasticsearch-users useradd john_doe -p mypassword -r read_role

✅ 사용자 john_doe를 생성하고 read_role 역할 부여.

✅ (2) 역할(Role) 생성

PUT _security/role/read_role
{
  "indices": [
    {
      "names": ["logs-*"],
      "privileges": ["read"]
    }
  ]
}

✅ read_role 역할을 생성하여 logs-* 인덱스에 대한 읽기 권한만 부여.

✅ (3) 역할(Role)을 사용자에게 할당

PUT _security/user/john_doe
{
  "password": "mypassword",
  "roles": ["read_role"],
  "full_name": "John Doe",
  "email": "john@example.com"
}

✅ 사용자 john_doe에게 read_role 역할을 할당.

✅ (4) 사용자 인증 테스트

curl -u john_doe:mypassword -X GET "http://localhost:9200/logs-2024/_search"

✅ john_doe는 logs-* 인덱스에 대해 읽기(read)는 가능하지만 쓰기(write)는 불가능.

TLS/SSL 설정 (X-Pack Security)

TLS/SSL을 설정하면 Elasticsearch와 Kibana 간의 통신을 암호화하여 데이터 보호할 수 있습니다.

✅ (1) 인증서 및 키 생성

bin/elasticsearch-certutil cert --pem --keep-ca-key

✅ Elasticsearch 인증서를 생성 (config/certs 디렉토리에 저장됨).

✅ (2) Elasticsearch TLS 설정 (elasticsearch.yml)

xpack.security.enabled: true
xpack.security.transport.ssl.enabled: true
xpack.security.http.ssl.enabled: true
xpack.security.transport.ssl.keystore.path: certs/elastic-certificates.p12
xpack.security.http.ssl.keystore.path: certs/elastic-certificates.p12

✅ Elasticsearch 노드 간 통신 및 HTTP API 요청을 SSL로 보호.

✅ (3) Kibana TLS 설정 (kibana.yml)

elasticsearch.ssl.certificateAuthorities: ["/etc/kibana/certs/ca.pem"]
server.ssl.enabled: true
server.ssl.certificate: "/etc/kibana/certs/kibana.pem"
server.ssl.key: "/etc/kibana/certs/kibana-key.pem"

✅ Kibana가 TLS를 통해 Elasticsearch에 연결하도록 설정.

✅ (4) Elasticsearch 보안 설정 적용

bin/elasticsearch-setup-passwords interactive

✅ 내장 사용자(elastic, kibana_system, logstash_system 등)의 비밀번호 설정.

API Key 및 User Authentication

API Key 인증을 사용하면 사용자 비밀번호 없이 Elasticsearch API에 안전하게 접근할 수 있습니다.

✅ (1) API Key 생성

POST _security/api_key
{
  "name": "my_api_key",
  "role_descriptors": {
    "limited_access": {
      "indices": [
        {
          "names": ["logs-*"],
          "privileges": ["read"]
        }
      ]
    }
  }
}

✅ logs-* 인덱스에 대해 읽기 권한을 가진 API Key 생성.

✅ (2) API Key를 사용하여 Elasticsearch 요청

curl -H "Authorization: ApiKey <your_api_key>" -X GET "https://localhost:9200/logs-2024/_search"

✅ API Key를 사용하여 Elasticsearch에 안전하게 접근.

✅ (3) API Key 확인 및 삭제

GET _security/api_key

DELETE _security/api_key/<api_key_id>

✅ API Key의 목록을 조회하거나 특정 API Key 삭제 가능.

보안 및 인증 설정 정리

Kibana 연동 및 데이터 시각화

📌 Kibana는 Elasticsearch의 데이터를 시각화하고 분석하는 도구로,

• 강력한 UI를 제공하여 로그 분석, 모니터링, 데이터 탐색을 쉽게 수행할 수 있습니다.

Kibana 설치 및 기본 사용법

✅ (1) Kibana 설치 (로컬)

wget https://artifacts.elastic.co/downloads/kibana/kibana-8.x.x-linux-x86_64.tar.gz
tar -xzf kibana-8.x.x-linux-x86_64.tar.gz
cd kibana-8.x.x-linux-x86_64
./bin/kibana

✅ 기본적으로 http://localhost:5601에서 실행됨.

✅ (2) Kibana 설정 (kibana.yml)

server.port: 5601
elasticsearch.hosts: ["http://localhost:9200"]

✅ Elasticsearch와 연결할 주소를 설정.

✅ (3) Kibana 실행 후 첫 화면

• Index Patterns 생성 → Elasticsearch 데이터를 Kibana에서 사용할 준비
• Discover, Visualization, Dashboard 등의 기능 제공

Discover - 데이터 탐색

📌 Discover 메뉴에서 데이터를 검색하고 필터링

• Elasticsearch 인덱스 데이터를 Kibana UI에서 검색
• 시간 필터(Time Filter) 적용 가능
• JSON 원본 데이터 확인 가능

✅ 예제: 최근 7일 동안 status: 404인 로그 검색

1. Discover 메뉴에서 인덱스 선택 (logs-*)
2. 쿼리 입력

   status: 404
   

3. 시간 범위 선택 (Last 7 days)
4. 필터 추가 (host.name: "server-01")
5. 원하는 필드 선택하여 테이블로 표시

Visualization - 데이터 시각화

📌 Kibana의 시각화 기능을 사용하여 데이터를 그래프로 표현

✅ 지원하는 주요 차트 유형

✅ (1) 예제: 상태 코드별 요청 수 Bar Chart 생성

1. Kibana → Visualize → Create Visualization → Bar Chart 선택
2. Y축(Aggregation): Count 선택
3. X축(Bucket - Terms Aggregation): status.keyword 선택
4. 필터 적용 (예: 특정 서버 host.name: "server-01")
5. Save & Add to Dashboard

✅ HTTP 응답 코드(200, 404, 500 등)의 분포를 시각화 가능.

✅ (2) 예제: 평균 응답 시간(Line Chart)

1. Create Visualization → Line Chart 선택
2. Y축(Aggregation): avg(response_time) 선택
3. X축(Bucket - Date Histogram): @timestamp 선택
4. Save & Add to Dashboard

✅ 시간에 따른 응답 속도의 변화를 분석할 수 있음.

Dashboard - 대시보드 생성

📌 여러 개의 시각화 패널을 조합하여 하나의 대시보드 생성

✅ 예제: 웹 서버 모니터링 대시보드

1. Kibana → Dashboard → Create New Dashboard
2. 시각화 추가
   • 상태 코드별 요청 수 (Bar Chart)
   • 평균 응답 시간 (Line Chart)
   • 총 요청 수 (Metric)
   • 에러 발생 비율 (Pie Chart)
3. 필터 추가 (예: 특정 서버별 분석)
4. Save & 공유 가능 (Share 버튼 사용)

Dev Tools - Elasticsearch Query 실행

Kibana의 Dev Tools는 Elasticsearch Query DSL을 직접 실행할 수 있는 UI입니다.

✅ Dev Tools 실행 방법

1. Kibana → Dev Tools 클릭
2. Query 입력 & 실행 (Ctrl + Enter)

✅ (1) Elasticsearch 인덱스 조회

GET _cat/indices?v

✅ Elasticsearch에 존재하는 모든 인덱스 목록 확인.

✅ (2) 특정 문서 검색

GET logs-2024/_search
{
  "query": {
    "match": { "status": "500" }
  }
}

✅ HTTP 500 에러 로그 검색.

✅ (3) Aggregation을 활용한 상태 코드별 요청 수 집계

GET logs-2024/_search
{
  "size": 0,
  "aggs": {
    "status_count": {
      "terms": {
        "field": "status.keyword"
      }
    }
  }
}

✅ 각 상태 코드별 요청 수를 집계하여 반환.

Kibana 연동 및 데이터 시각화 정리