Transform type mappings

출처: 문서

본문

타입 매핑 변환

{: .note } 이러한 변환이 여러분의 사용 사례에 꼭 맞지 않을 수도 있지만, 변환을 만들기 위한 프레임워크는 워크로드를 수정하거나 새로운 타깃으로 옮길 때 변형, 데이터 보강, 기타 수정 작업을 처리하도록 설계되었어요.

이 가이드는 Elasticsearch 6.x 이하 버전에서 OpenSearch로 마이그레이션할 때 타입 매핑 기능의 지원 중단을 처리하는 방법을 알려줘요.

6.x 이전 버전의 Elasticsearch에서는 하나의 인덱스가 여러 타입을 포함할 수 있었고, 각 타입은 자체 매핑을 가졌어요. 이런 타입 덕분에 책이나 영화처럼 서로 다른 종류의 문서를 하나의 인덱스에 저장하고 쿼리할 수 있었죠. 예를 들어 book 타입과 movie 타입은 title 같은 공유 필드를 가지면서도, 각 타입에만 해당하는 추가 필드를 따로 가질 수 있었어요.

최신 버전의 Elasticsearch와 OpenSearch는 더 이상 여러 매핑 타입을 지원하지 않아요. 이제 각 인덱스는 단일 매핑 타입만 지원하죠. 마이그레이션할 때는 여러 타입을 사용하던 데이터를 어떻게 변환하거나 재구성할지 직접 정의해야 해요. 다음 예시는 여러 매핑 타입을 보여줘요:

GET /library/_mappings
{
  "library": {
    "mappings": {
      "book": {
        "properties": {
          "title":      { "type": "text" },
          "pageCount":  { "type": "integer" }
        }
      },
      "movie": {
        "properties": {
          "title":      { "type": "text" },
          "runTime":    { "type": "integer" }
        }
      }
    }
  }
}

자세한 내용은 매핑 타입 제거에 관한 공식 Elasticsearch 문서를 참고하세요.

타입 매핑 트랜스포머 사용하기

타입 매핑 지원 중단 문제를 해결하려면 TypeMappingsSanitizationTransformer를 사용하세요. 이 트랜스포머는 메타데이터, 문서, 요청을 포함한 데이터를 수정해서, 이전에 매핑된 데이터를 OpenSearch에서 사용할 수 있게 만들어 줘요. 매핑 트랜스포머를 사용하려면:

1. 부트스트랩 박스로 이동한 뒤 cdk.context.json 파일을 Vim으로 여세요.
2. reindexFromSnapshotExtraArgs 키를 추가하거나 업데이트해서 --doc-transformer-config-file /shared-logs-output/transformation.json을 포함시키세요.
3. trafficReplayerExtraArgs 키를 추가하거나 업데이트해서 --transformer-config-file /shared-logs-output/transformation.json을 포함시키세요.
4. Migration Assistant를 배포하세요.
5. Migration Assistant 콘솔로 이동하세요.
6. /shared-logs-output/transformation.json이라는 이름의 파일을 만드세요.
7. 파일에 변환 설정을 추가하세요. 설정 옵션에 대해서는 설정 옵션을 참고하세요.
8. 메타데이터 마이그레이션을 실행할 때는 console metadata migrate --transformer-config-file /shared-logs-output/transformation.json 명령어를 사용해 트랜스포머와 함께 설정을 실행하세요.

변환 설정이 업데이트될 때마다 변경 사항을 적용하려면 backfill과 Replayer 도구를 중지했다가 다시 시작해야 해요. 일관성 없는 상태가 되지 않도록 이전에 마이그레이션한 데이터와 메타데이터를 정리해야 할 수도 있어요.

설정 옵션

TypeMappingsSanitizationTransformer는 타입 매핑을 관리하기 위한 여러 가지 전략을 지원해요:

1. 서로 다른 타입을 별도의 인덱스로 라우팅: 서로 다른 타입을 각자의 인덱스로 분리해요.
2. 모든 타입을 하나의 인덱스로 병합: 여러 타입을 하나의 인덱스로 합쳐요.
3. 특정 타입 드롭: 특정 타입만 선택적으로 마이그레이션해요.
4. 원래 구조 유지: 새로운 타입 표준을 따르면서 동일한 인덱스 이름을 유지해요.

타입 매핑 트랜스포머 설정 스키마

타입 매핑 트랜스포머는 다음과 같은 설정 옵션을 사용해요.

다음 JSON 설정 예시는 변환 스키마를 보여줘요:

{
  "TypeMappingSanitizationTransformerProvider": {
    "staticMappings": {
      "{index-name-1}": {
        "{type-name-1}": "{target-index-name-1}",
        "{type-name-2}": "{target-index-name-2}"
      }
    },
    "regexMappings": [
      {
        "sourceIndexPattern": "{source-index-pattern}",
        "sourceTypePattern": "{source-type-pattern}",
        "targetIndexPattern": "{target-index-pattern}"
      }
    ],
    "sourceProperties": {
      "version": {
        "major": "NUMBER",
        "minor": "NUMBER"
      }
    }
  }
}

설정 예시

다음 설정 예시들은 다양한 매핑 타입 시나리오에서 트랜스포머를 사용하는 방법을 보여줘요.

서로 다른 타입을 별도의 인덱스로 라우팅하기

user와 post 타입을 가진 activity 인덱스를 별도의 인덱스로 분리하고 싶다면 다음 설정을 사용하세요:

[
  {
    "TypeMappingSanitizationTransformerProvider": {
      "staticMappings": {
        "activity": {
          "user": "new_users",
          "post": "new_posts"
        }
      },
      "sourceProperties": {
        "version": {
          "major": 6,
          "minor": 8
        }
      }
    }
  }
]

{% include copy.html %}

이 트랜스포머는 다음 작업을 수행해요:

• 타입이 user인 문서는 new_users 인덱스로 라우팅해요.
• 타입이 post인 문서는 new_posts 인덱스로 라우팅해요.

모든 타입을 하나의 인덱스로 병합하기

모든 타입을 하나의 인덱스로 병합하려면 다음 설정을 사용하세요:

[
  {
    "TypeMappingSanitizationTransformerProvider": {
      "staticMappings": {
        "activity": {
          "user": "activity",
          "post": "activity"
        }
      },
      "sourceProperties": {
        "version": {
          "major": 6,
          "minor": 8
        }
      }
    }
  }
]

{% include copy.html %}

특정 타입 드롭하기

activity 인덱스 안에서 user 타입만 마이그레이션하고, 직접 지정되지 않은 타입의 문서/요청은 모두 드롭하려면 다음 설정을 사용하세요:

[
  {
    "TypeMappingSanitizationTransformerProvider": {
      "staticMappings": {
        "activity": {
          "user": "users_only"
        }
      },
      "sourceProperties": {
        "version": {
          "major": 6,
          "minor": 8
        }
      }
    }
  }
]

{% include copy.html %}

이 설정은 user 타입의 문서만 마이그레이션하고, activity 인덱스에 있는 다른 문서 타입은 무시해요.

원래 구조 유지하기

특정 타입만 마이그레이션하면서 원래 구조를 유지하려면 다음 설정을 사용하세요:

[
  {
    "TypeMappingSanitizationTransformerProvider": {
      "regexMappings": [
        {
          "sourceIndexPattern": "(.*)",
          "sourceTypePattern": ".*",
          "targetIndexPattern": "$1"
        }
      ],
      "sourceProperties": {
        "version": {
          "major": 6,
          "minor": 8
        }
      }
    }
  }
]

{% include copy.html %}

이 설정은 모든 타입을 하나의 인덱스로 병합하는 전략과 동일하지만, 패턴 기반 라우팅 전략도 함께 사용해요.

여러 전략 조합하기

정적 매핑과 정규식 기반 매핑을 조합하면 하나의 마이그레이션에서 서로 다른 인덱스나 패턴을 관리할 수 있어요. 예를 들어 어떤 인덱스는 staticMappings를 반드시 사용해야 하고, 다른 인덱스는 regexMappings를 사용해 모든 타입을 패턴으로 라우팅할 수 있죠.

각 문서, 요청, 메타데이터 항목마다(벌크 요청은 개별 항목 단위로 처리돼요) 다음 단계가 수행돼요:

1. 인덱스를 확인해서 정적 매핑의 항목과 일치하는지 판단해요.
   • 일치하면, 해당 타입이 정적 매핑 항목의 인덱스 구성 요소와 일치하는지 확인해요.
     • 타입이 일치하면 매핑이 적용되고, 결과 인덱스에는 타입 키의 값이 포함돼요.
     • 타입이 일치하지 않으면 해당 요청/문서/메타데이터는 드롭되고 마이그레이션되지 않아요.
2. 인덱스가 정적 매핑에서 일치하지 않으면, 인덱스-타입 조합을 정규식 매핑 목록의 각 항목과 처음부터 끝까지 순서대로 확인해요. 일치하는 항목을 찾으면 매핑이 적용되고, 결과 인덱스에는 타입 키의 값이 포함되며, 이후로는 정규식 매칭을 더 이상 수행하지 않아요.
3. 앞의 경우에 해당하지 않는 요청, 문서, 메타데이터는 모두 드롭되고, 그 안에 담긴 문서는 마이그레이션되지 않아요.

다음 예시는 서로 다른 인덱스에 대해 정적 매핑과 정규식 기반 매핑을 조합하는 방법을 보여줘요:

[
  {
    "TypeMappingSanitizationTransformerProvider": {
      "staticMappings": {
        "activity": {
          "user": "users_activity",
          "post": "posts_activity"
        },
        "logs": {
          "error": "logs_error",
          "info": "logs_info"
        }
      },
      "regexMappings": [
        {
          "sourceIndexPattern": "orders.*",
          "sourceTypePattern": ".*",
          "targetIndexPattern": "all_orders"
        }
      ],
      "sourceProperties": {
        "version": {
          "major": 6,
          "minor": 8
        }
      }
    }
  }
]

{% include copy.html %}

기본값

변환 설정에 regexMappings 키가 없으면 regexMappings는 다음을 기본값으로 사용해요:

{
  "regexMappings": [
    {
      "sourceIndexPattern": "(.+)",
      "sourceTypePattern": "_doc",
      "targetIndexPattern": "$1"
    },
    {
      "sourceIndexPattern": "(.+)",
      "sourceTypePattern": "(.+)",
      "targetIndexPattern": "$1_$2"
    }
  ]
}

{% include copy.html %}

이 기본값은 Elasticsearch 6.x 이상에서 생성된 인덱스의 경우 인덱스 이름을 그대로 유지하고, Elasticsearch 5.x에서 생성된 인덱스의 경우 타입 이름과 인덱스 이름을 합치는 효과가 있어요. Elasticsearch 5.x에서 생성된 인덱스의 인덱스 이름을 유지하고 싶다면 staticMappings 옵션을 사용하거나 regexMappings 옵션으로 타입 매핑을 재정의하세요.

제한 사항

트랜스포머를 사용할 때는 다음 제한 사항을 기억하세요.

Traffic Replayer

Traffic Replayer의 경우 타입을 포함하는 요청 중 일부만 지원돼요. 해당 요청들은 다음 표에 나열되어 있어요.

Reindex-from-Snapshot

Reindex-From-Snapshot,의 경우 Elasticsearch 6.x 이상에서 생성된 인덱스는 Elasticsearch 6에서 다른 타입이 지정되었더라도 모든 문서의 타입으로 _doc을 사용해요.

더 알아보기 (Learn more)

• 원문 전체: https://docs.opensearch.org/latest/migration-assistant-classic/migration-phases/migrate-metadata/handling-type-mapping-deprecation/