Ingest Pipeline으로 데이터 전처리

Advanced Managed Search(OpenSearch)는 문서가 인덱스에 저장되기 전에 데이터를 가공, 필터링, 변환, 보강할 수 있는 Ingest Pipeline 기능을 제공합니다.
이 페이지에서는 Ingest Pipeline의 개념과 활용 목적, 그리고 기본적인 사용 방법을 설명합니다.

Ingest Pipeline이란?

Ingest Pipeline은 문서가 OpenSearch 인덱스에 저장되기 전에 실행되는 전처리 파이프라인입니다.
하나의 파이프라인에는 여러 개의 Processor가 포함될 수 있으며, 각 Processor는 특정 데이터 처리 작업을 수행합니다.

이를 통해 다음과 같은 작업을 수행할 수 있습니다.

• 필드 값 변환 및 정규화
• 문자열 대소문자 변환
• 필드 추가, 삭제, 기본값 설정
• 데이터 포맷 정리 및 보강

Ingest Pipeline은 데이터 품질을 개선하고 검색 정확도를 높이는 데 중요한 역할을 합니다.

Ingest Pipeline 사용을 위한 조건

Ingest Pipeline을 사용하기 위해서는 다음 조건을 만족해야 합니다.

• 클러스터에 ingest 노드 역할을 가진 노드가 하나 이상 존재해야 합니다.
• Ingest Pipeline 관리 권한을 가진 보안 역할이 필요합니다.
  • cluster_manage_pipelines

Ingest Pipeline 생성

다음 예시는 학생 데이터를 처리하는 Ingest Pipeline을 생성하는 예시입니다.

PUT _ingest/pipeline/my-pipeline
{
  "description": "This pipeline processes student data",
  "processors": [
    {
      "set": {
        "description": "Sets the graduation year to 2023",
        "field": "grad_year",
        "value": 2023
      }
    },
    {
      "set": {
        "description": "Sets graduated to true",
        "field": "graduated",
        "value": true
      }
    },
    {
      "uppercase": {
        "field": "name"
      }
    }
  ]
}

이 파이프라인은 다음과 같은 처리를 수행합니다.

• grad_year 값을 2023으로 설정
• graduated 값을 true로 설정
• name 필드를 대문자로 변환

Ingest Pipeline 시뮬레이션

파이프라인을 실제 데이터에 적용하기 전에, _simulate API를 사용하여 결과를 미리 확인할 수 있습니다.

POST /_ingest/pipeline/my-pipeline/_simulate
{
  "docs": [
    {
      "_index": "my-index",
      "_id": "1",
      "_source": {
        "grad_year": 2024,
        "graduated": false,
        "name": "John Doe"
      }
    },
    {
      "_index": "my-index",
      "_id": "2",
      "_source": {
        "grad_year": 2025,
        "graduated": false,
        "name": "Jane Doe"
      }
    }
  ]
}

이를 통해 파이프라인 적용 후 데이터가 어떻게 변경되는지 확인할 수 있습니다.

인덱스에 기본 파이프라인 설정

특정 인덱스에 Ingest Pipeline을 기본 파이프라인으로 설정하면, 해당 인덱스로 들어오는 모든 문서에 전처리가 자동으로 적용됩니다.

PUT my-index/_settings
{
  "settings": {
    "index.default_pipeline": "my-pipeline"
  }
}

만약 특정 색인 요청에서 파이프라인을 생략하고 싶다면 요청 쿼리에 ?pipeline=_none을 추가할 수 있습니다.

문서 색인 및 결과 확인

이제 문서를 색인하면 Ingest Pipeline이 자동으로 적용됩니다.

색인 요청

POST my-index/_doc/1
{
  "name": "open-search user",
  "grad_year": 2025,
  "graduated": false
}

결과 확인

GET my-index/_search

최종 데이터 응답

"hits": {
  "hits": [
    {
      "_source": {
        "graduated": true,            // Pipeline에 의해 true로 고정됨
        "name": "OPEN-SEARCH USER",   // Pipeline에 의해 대문자로 변환됨
        "grad_year": 2023             // Pipeline에 의해 2023으로 고정됨
      }
    }
  ]
}

입력한 문서에 대해 Ingest Pipeline이 정상적으로 적용된 것을 확인할 수 있습니다.

Ingest Pipeline 활용 사례

Ingest Pipeline은 다음과 같은 시나리오에서 유용하게 활용됩니다.

• 로그 필드 정규화 (대소문자, 포맷 통일)
• 사용자 입력 데이터 표준화
• 검색용 키워드 및 보조 필드 생성
• 데이터 정제 및 품질 관리

안내

Ingest Pipeline에서 사용할 수 있는 Processor 목록과 상세 기능은 OpenSearch 공식 문서를 참고하시기 바랍니다.