dump-segment 도구

dump-segment 도구 (dump-segment tool)

Apache Druid 세그먼트의 메타데이터나 내용을 디버깅 목적으로 덤프(dump)하는 dump-segment 도구를 설명하는 문서예요. 실행 방법과 출력 형식(행·메타데이터·비트맵·중첩 컬럼)을 다루어요.

출처: 문서

본문

DumpSegment 도구는 디버깅 목적으로 Apache Druid 세그먼트의 메타데이터나 내용을 덤프하는 데 사용할 수 있어요. 덤프는 세그먼트의 완전 동일(full-fidelity) 번역이 반드시 아니라는 점에 유의하세요. 특히 모든 메타데이터가 포함되지는 않으며, 복잡한 지표 값은 완전하지 않을 수 있어요.

도구를 실행하려면 세그먼트 디렉터리를 가리키고 출력 파일을 작성하세요.

java -classpath "/my/druid/lib/*" -Ddruid.extensions.loadList="[]" org.apache.druid.cli.Main \
  tools dump-segment \
  --directory /home/druid/path/to/segment/ \
  --out /home/druid/output.txt

JDK 17 이상을 사용한다면 다음 추가 파라미터를 넣어야 해요.

--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/sun.nio.ch=ALL-UNNAMED

다음은 예시예요.

java --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED \
  -classpath "/my/druid/lib/*" \
  -Ddruid.extensions.loadList="[]" org.apache.druid.cli.Main \
  tools dump-segment \
  --directory /home/druid/path/to/segment/ \
  --out /home/druid/output.txt

출력 형식 (Output format)

데이터 덤프 (Data dumps)

기본적으로, 또는 --dump rows와 함께 사용하면 이 도구는 각 컬럼의 기본 직렬화를 사용해 세그먼트의 행을 줄 단위 JSON 객체(줄마다 객체 하나)로 덤프해요. 일반적으로 모든 컬럼이 포함되지만, 원한다면 --column name으로 덤프를 특정 컬럼으로 제한할 수 있어요.

예를 들어 예쁘게 출력(pretty-print)할 때 한 줄은 다음과 같을 수 있어요.

{
  "__time": 1442018818771,
  "added": 36,
  "channel": "#en.wikipedia",
  "cityName": null,
  "comment": "added project",
  "count": 1,
  "countryIsoCode": null,
  "countryName": null,
  "deleted": 0,
  "delta": 36,
  "isAnonymous": "false",
  "isMinor": "false",
  "isNew": "false",
  "isRobot": "false",
  "isUnpatrolled": "false",
  "iuser": "00001553",
  "metroCode": null,
  "namespace": "Talk",
  "page": "Talk:Oswald Tilghman",
  "regionIsoCode": null,
  "regionName": null,
  "user": "GELongstreet"
}

메타데이터 덤프 (Metadata dumps)

--dump metadata와 함께 사용하면 이 도구는 행 대신 메타데이터를 덤프해요. 이 도구가 생성하는 메타데이터 덤프는 SegmentMetadata 쿼리가 반환하는 형식과 동일해요.

비트맵 덤프 (Bitmap dumps)

--dump bitmaps와 함께 사용하면 이 도구는 행 대신 비트맵 인덱스를 덤프해요. 이 도구가 생성하는 비트맵 덤프는 사전 인코딩된 문자열 컬럼만 포함해요. 출력은 세그먼트에 사용된 비트맵 타입을 설명하는 "bitmapSerdeFactory" 필드와 각 컬럼 값에 대한 비트맵을 담은 "bitmaps" 필드를 포함해요. 이들은 기본적으로 base64 인코딩되지만, --decompress-bitmaps로 행 번호 목록으로도 덤프할 수 있어요.

일반적으로 모든 컬럼이 포함되지만, 원한다면 --column name으로 덤프를 특정 컬럼으로 제한할 수 있어요.

샘플 출력:

{
  "bitmapSerdeFactory": {
    "type": "roaring"
  },
  "bitmaps": {
    "isRobot": {
      "false": "//aExfu+Nv3X...",
      "true": "gAl7OoRByQ..."
    }
  }
}

중첩 컬럼 덤프 (Nested column dumps)

--dump nested와 함께 사용하면 이 도구로 Druid 중첩 컬럼을 검사할 수 있어요. nested는 항상 정확히 하나의 --column name 인자를 요구하며, --nested-path $.path.to.field처럼 JSONPath 구문으로 특정 중첩 필드를 지정하는 선택적 인자를 받을 수 있어요.

--nested-path를 지정하지 않으면 출력은 중첩 필드 목록과 타입, 전역 값 사전(global value dictionary), null 행 목록을 포함해요.

샘플 출력:

{
  "nest": {
    "fields": [
      {
        "path": "$.x",
        "types": [
          "LONG"
        ]
      },
      {
        "path": "$.y",
        "types": [
          "DOUBLE"
        ]
      },
      {
        "path": "$.z",
        "types": [
          "STRING"
        ]
      }
    ],
    "dictionaries": {
      "strings": [
        {
          "globalId": 0,
          "value": null
        },
        {
          "globalId": 1,
          "value": "a"
        },
        {
          "globalId": 2,
          "value": "b"
        }
      ],
      "longs": [
        {
          "globalId": 3,
          "value": 100
        },
        {
          "globalId": 4,
          "value": 200
        },
        {
          "globalId": 5,
          "value": 400
        }
      ],
      "doubles": [
        {
          "globalId": 6,
          "value": 1.1
        },
        {
          "globalId": 7,
          "value": 2.2
        },
        {
          "globalId": 8,
          "value": 3.3
        }
      ],
      "nullRows": []
    }
  }
}

--nested-path를 지정하면 출력은 대신 중첩 필드의 타입, 'global' 사전 id와 값을 포함한 로컬 값 사전, 각 값에 대한 압축 해제된 비트맵 인덱스(값을 포함하는 행 번호 목록), 그리고 컬럼 자체의 덤프(행 번호, 중첩 컬럼의 원시 JSON 형태, 해당 행에 대한 필드의 로컬 사전 id, 해당 행에 대한 필드 값)를 포함해요.

샘플 출력:

{
  "bitmapSerdeFactory": {
    "type": "roaring"
  },
  "nest": {
    "$.x": {
      "types": [
        "LONG"
      ],
      "dictionary": [
        {
          "localId": 0,
          "globalId": 0,
          "value": null,
          "rows": [
            4
          ]
        },
        {
          "localId": 1,
          "globalId": 3,
          "value": "100",
          "rows": [
            3
          ]
        },
        {
          "localId": 2,
          "globalId": 4,
          "value": "200",
          "rows": [
            0,
            2
          ]
        },
        {
          "localId": 3,
          "globalId": 5,
          "value": "400",
          "rows": [
            1
          ]
        }
      ],
      "column": [
        {
          "row": 0,
          "raw": {
            "x": 200,
            "y": 2.2
          },
          "fieldId": 2,
          "fieldValue": "200"
        },
        {
          "row": 1,
          "raw": {
            "x": 400,
            "y": 1.1,
            "z": "a"
          },
          "fieldId": 3,
          "fieldValue": "400"
        },
        {
          "row": 2,
          "raw": {
            "x": 200,
            "z": "b"
          },
          "fieldId": 2,
          "fieldValue": "200"
        },
        {
          "row": 3,
          "raw": {
            "x": 100,
            "y": 1.1,
            "z": "a"
          },
          "fieldId": 1,
          "fieldValue": "100"
        },
        {
          "row": 4,
          "raw": {
            "y": 3.3,
            "z": "b"
          },
          "fieldId": 0,
          "fieldValue": null
        }
      ]
    }
  }
}

명령줄 인자 (Command line arguments)

더 알아보기 (Learn more)

• SegmentMetadata 쿼리 문서에서 메타데이터 덤프 형식의 원본을 살펴보세요.
• 중첩 컬럼 문서에서 중첩 컬럼 구조를 이해해 보아요.
• SQL JSON 함수 문서에서 JSONPath 구문을 확인해 보세요.