sonar-insert-lookup-record-batch

입력 레코드를 지정된 룩업 테이블에 입력합니다. 이미 존재하는 키의 레코드는 기본적으로 건너뛰며, update-fields 옵션을 지정한 경우에만 기존 레코드를 갱신합니다.

명령어 속성

문법

옵션

lookup=STR

레코드를 입력할 대상 룩업 테이블의 이름

[update-fields=STR]

입력하려는 레코드의 키가 이미 존재할 때 레코드를 갱신할지 여부를 결정하는 옵션. 값을 지정하면 키가 중복되는 레코드를 통째로 갱신하며, 지정하지 않으면 키가 중복된 레코드는 입력하지 않습니다. 지정한 필드 이름은 갱신 범위를 제한하지 않고 대상 룩업 스키마에 존재하는 필드인지 검사하는 데에만 쓰이며, 쉼표(,)로 구분하여 여러 필드 이름을 지정할 수 있습니다

입력 필드

출력 필드

입력 레코드의 모든 필드에 다음 필드를 추가하여 반환합니다.

오류 코드

파싱 오류

런타임 오류

해당 사항 없음

설명

sonar-insert-lookup-record-batch 명령어는 입력 레코드마다 룩업 스키마에 정의된 필드 순서대로 값을 추출하여 룩업 테이블에 입력합니다. 각 필드 값은 룩업 스키마에 정의된 최대 길이를 초과할 수 없으며, null을 허용하지 않는 필드에 빈 값을 지정할 수 없습니다.

키 필드 값이 이미 룩업 테이블에 존재하는 경우 동작이 두 가지로 나뉩니다. update-fields 옵션을 지정하지 않았다면 해당 레코드를 입력하지 않고 _error 필드에 duplicated key.를 기록합니다. update-fields 옵션을 지정했다면 update-fields에 나열한 필드만 바뀌는 것이 아니라, 룩업 스키마에 정의된 모든 필드가 입력 레코드의 값으로 대체되는 방식으로 기존 레코드 전체를 갱신합니다.

update-fields 옵션은 갱신 대상 필드를 제한하지 않습니다. 입력 레코드에 포함하지 않은 필드는 빈 값으로 대체되어 기존 값이 지워지므로, 레코드를 갱신할 때는 반드시 룩업 스키마에 정의된 모든 필드 값을 함께 전달해야 합니다.

키 필드 값이 없거나(_error: key is null.) 문자열 타입이 아니면(_error: invalid key type.) 해당 레코드는 처리하지 않고 건너뜁니다. 필드별 검증에 실패하면 <필드 이름> is empty. 또는 <필드 이름> exceed max len. 형식의 메시지가 _error 필드에 기록됩니다. 이 메시지들은 로케일과 무관하게 항상 영어로 기록됩니다.

레코드 입력·갱신이 데이터베이스 처리 단계에서 실패하는 경우(예: 중복 키, SQL 오류)에는 이 실패가 _error 필드에 기록되지 않습니다. 명령어는 이 단계의 실패를 반환값으로만 전달받을 뿐 출력 레코드에 반영하지 않으므로, _error 필드가 비어 있어도 실제로는 반영되지 않았을 수 있습니다. 정확한 반영 여부는 룩업 테이블을 직접 조회해 확인해야 합니다.

레코드를 삭제하려면 sonar-delete-lookup-record-batch 명령어를 사용하세요.

사용 예

1. 룩업 테이블에 레코드 입력

   json "[{'ip': '192.0.2.10', 'asset_name': 'web-01'}, {'ip': '192.0.2.11', 'asset_name': 'web-02'}]"
   | sonar-insert-lookup-record-batch lookup="asset-ip-map"
   

   asset-ip-map 룩업 테이블에 두 개의 레코드를 입력합니다. 키 필드 값이 이미 존재하는 레코드는 입력하지 않고 _error 필드에 duplicated key.가 기록됩니다.

2. 중복 키의 레코드를 갱신하며 입력

   json "[{'ip': '192.0.2.10', 'asset_name': 'web-01-renamed'}]"
   | sonar-insert-lookup-record-batch lookup="asset-ip-map" update-fields="asset_name"
   

   키가 이미 존재하는 레코드는 입력하는 대신 레코드 전체가 입력 레코드의 값으로 갱신됩니다. 이 예에서는 asset_name 필드만 입력 레코드에 포함했으므로, 룩업 스키마에 asset_name 외의 다른 필드가 있다면 그 필드의 기존 값은 빈 문자열로 지워집니다. 갱신할 때는 반드시 룩업 스키마에 정의된 모든 필드 값을 함께 전달해야 합니다.

변경 이력

sonar-insert-lookup-record-batch 명령어는 소나 4.0.2609.0 버전부터 사용 가능합니다.

이 명령어는 실험실(Lab) 앱이 제공하던 것을 소나 코어에 내장한 것입니다(SNR#3463). 내장되지 않은 버전에서는 실험실 앱을 설치해 사용할 수 있습니다. 실험실 앱에서는 sonar-insert-lookup-records 이름으로 제공됩니다.