커스텀 테이블 데이터 가져오기

1. 개요

일부 경우, 사용하려는 데이터가 유저 또는 이벤트 형태로 표현되지 않을 수 있습니다. 예를 들어 매핑 테이블이나 외부 데이터 등이 있습니다. 이러한 데이터를 사용하려면 data_transfer 명령을 통해 TA 시스템에 사용자 정의 데이터를 가져와야 하며, 이 데이터는 이벤트 테이블과 유저 정보 테이블과 연결됩니다.

현재 다음 두 가지 데이터 소스의 가져오기를 지원합니다:

• mysql: 원격 MySQL 데이터베이스
• txtfile: 로컬 파일

2. 사용 방법

2.1 명령어 설명

데이터 가져오기 명령어는 다음과 같습니다:

ta-tool data_transfer -conf <config files> [--date xxx]

2.2 명령어 파라미터 설명

2.2.1 -conf

가져올 테이블의 구성 파일 경로를 나타냅니다. 각 테이블은 구성 파일 하나로 나타내며, 여러 테이블의 동시 가져오기를 지원합니다. 와일드카드 방식도 지원합니다, 예: /data/config/ 또는 ./config/.json

2.2.2 --date

선택적 파라미터 --date: 선택적 파라미터로, 데이터 날짜를 나타내며, 이 참조 시간을 기준으로 시간 매크로가 대체됩니다. 파라미터를 전달하지 않으면 기본적으로 현재 날짜를 가져오며, 형식은 YYYY-MM-DD입니다. 시간 매크로 사용법에 대해서는 시간 매크로 사용을 참조하십시오.

2.3 구성 파일 설명

2.3.1 단일 테이블에 대한 샘플 구성 파일은 다음과 같습니다:

{
  "parallel_num": 2,
  "source": {
    "type": "txtfile",
    "parameter": {
      "path": ["/data/home/ta/importer_test/data/*"],
      "encoding": "UTF-8",
      "column": ["*"],
      "fieldDelimiter": "\t"
    }
  },
  "target": {
    "appid": "test-appid",
    "table": "test_table",
    "table_desc": "import test table",
    "partition_value": "@[{yyyyMMdd}-{1day}]",
    "column": [
      {
        "name": "col1",
        "type": "timestamp",
        "comment": "timestamp"
      },
      {
        "name": "col2",
        "type": "varchar"
      }
    ]
  }
}

2.3.2 외부 레이어 파라미터 설명

• parallel_num
  • 설명: 가져올 동시 스레드 수를 지정하여 가져오기 속도를 제어합니다.
  • 유형: int
  • 필수 여부: 예
  • 기본 값: 없음
• source
  • 설명: 데이터 소스 가져오기에 대한 구체적인 파라미터 구성
  • 유형: jsonObject
  • 필수 여부: 예
  • 기본 값: 없음
• target
  • 설명: 타겟 테이블 내보내기에 대한 구체적인 파라미터 구성
  • 유형: jsonObject
  • 필수 여부: 예
  • 기본 값: 없음

2.3.3 소스 파라미터 사양

• type
  • 설명: 데이터 소스의 유형 가져오기, 현재 가져오기 도구는 txtfile, mysql 및 ftp의 세 가지 데이터 소스를 지원합니다. 더 많은 데이터 소스가 추후 지원될 예정입니다.
  • 유형: string
  • 필수 여부: 예
  • 기본 값: 없음
• parameter
  • 설명: 다양한 데이터 소스에 대한 구체적인 구성, III. 데이터 소스 가져오기 구성에 명시되어 있습니다.
  • 유형: jsonObject
  • 필수 여부: 예
  • 기본 값: 없음

2.3.4 타겟 파라미터 사양

• appid
  • 설명: 테이블에 해당하는 가져오기 프로젝트의 appid로, TA 시스템의 백그라운드에서 찾을 수 있습니다.
  • 유형: string
  • 필수 여부: 예
  • 기본 값: 없음
• table
  • 설명: TA 시스템에 가져올 테이블 이름. 주의: 테이블 이름은 전역적으로 중복될 수 없습니다. 다른 프로젝트를 위해 구별 가능한 접두사나 접미사를 추가하는 것을 권장합니다.
  • 유형: string
  • 필수 여부: 예
  • 기본 값: 없음
• table_desc
  • 설명: 테이블의 주석을 가져옵니다. 이후 테이블 조회 및 테이블 의미를 명확히 하기 위해 이 파라미터를 설정하는 것이 좋습니다.
  • 유형: string
  • 필수 여부: 아니오
  • 기본 값: 없음
• partition_value
  • 설명: 가져온 파티션 값. TA 시스템에서 가져온 사용자 정의 테이블은 기본적으로 $pt 파티션 필드를 가지므로, 가져올 때 파티션 값을 지정해야 합니다. 일반적으로 가져온 데이터 날짜로 설정할 수 있습니다. 예: 20180701, 시간 매크로 대체도 지원합니다. 예: @[{yyyyMMdd}-{1day}]. 2.1 섹션에서 구체적인 사용법을 소개합니다.
  • 유형: string
  • 필수 여부: 예
  • 기본 값: 없음
• column
  • 설명: TA 시스템에 가져올 테이블 필드 정의. name, type, comment의 세 가지 속성 값을 포함하며, name과 type은 필수 필드입니다. 샘플은 다음과 같습니다:

[
  {
    "name": "col1",
    "type": "timestamp",
    "comment": "timestamp"
  },
  {
    "name": "col2",
    "type": "varchar"
  }
]

소스가 MySQL이고 전체 테이블이 가져오면(즉, column 필드가 ["*"]인 경우) 타겟에서는 column 파라미터를 전달할 수 없으며, 가져오기 도구는 MySQL의 테이블 구조를 따릅니다. 나머지 경우에는 이 필드를 전달해야 합니다.

• 유형: jsonArray
• 필수: 아니요
• 기본값: MySQL 소스 테이블 스키마 정의

2.4 시간 매크로 사용

구성 파일 내에서 시간 매크로를 사용하여 시간 파라미터를 대체할 수 있습니다. ta-tool은 가져온 시작 시간을 기준으로 시간 매크로의 파라미터에 따라 시간의 오프셋을 계산하여 구성 파일 내의 시간 매크로를 대체합니다. 사용할 수 있는 시간 매크로 형식은 다음과 같습니다: @{[yyyyMMdd]}, @{[yyyyMMdd}-{nday]}, @{[yyyyMMdd}+{nday]}, @{[yyyyMMdd} + {nday}] 등.

• yyyyMMdd는 Java dateFormat으로 파싱할 수 있는 모든 날짜 형식으로 대체할 수 있습니다. 예: yyyy-MM-dd HH:mm:ss.SSS 및 yyyyMMddHH000000
• N은 시간의 오프셋 값을 나타내는 임의의 정수입니다.
• Day는 시간의 오프셋 단위로, day, hour, minute, week, month 중에서 선택할 수 있습니다.
• 예시: 현재 시간이 2018-07-01 15:13:23.234인 경우
  • @{[yyyyMMdd]}는 20180701로 대체됩니다.
  • @{[yyyy-MM-dd}-{1day]}는 2018-06-30로 대체됩니다.
  • @{[yyyyMMddHH}+{2hour]}는 2018070117로 대체됩니다.
  • @{[yyyyMMddHHmm00}-{10minute]}는 20180701150300로 대체됩니다.

3. 데이터 소스 구성

이 섹션에서는 다양한 데이터 소스의 파라미터 구성을 소개합니다. 현재 txtfile, mysql, ftp의 3가지 가져오기 데이터 소스를 지원합니다. 데이터 소스에 따라 소스의 파라미터를 조정해야 합니다.

3.1 MySQL 데이터 소스

데이터 소스는 JDBC 커넥터를 통해 원격 MySQL 데이터베이스에 연결되며, 사용자가 구성한 정보를 기반으로 쿼리 SELECT SQL 문을 생성한 후 이를 원격 MySQL 데이터베이스에 전송하여 SQL 실행 결과를 TA 시스템의 테이블로 가져옵니다.

3.1.1 샘플 구성

• MySQL 전체 테이블을 TA 시스템으로 가져오는 샘플 구성:

{
  "parallel_num": 2,
  "source": {
    "type": "mysql",
    "parameter": {
      "username": "test",
      "password": "test",
      "column": ["*"],
      "connection": [
        {
          "table": ["test_table"],
          "jdbcUrl": ["jdbc:mysql://mysql-ip:3306/testDb"]
        }
      ]
    }
  },
  "target": {
    "appid": "test-appid",
    "table": "test_table_abc",
    "table_desc": "mysql test table",
    "partition_value": "@[{yyyy-MM-dd}-{1day}]"
  }
}

• TA 시스템의 샘플 구성에 대한 Custom SQL 임포트:

{
  "parallel_num": 1,
  "source": {
    "type": "mysql",
    "parameter": {
      "username": "test",
      "password": "test",
      "connection": [
        {
          "querySql": [
            "select db_id,log_time from test_table where log_time>='@[{yyyy-MM-dd 00:00:00}-{1day}]' and log_time<'@[{yyyy-MM-dd 00:00:00}]'"
          ],
          "jdbcUrl": ["jdbc:mysql://mysql-ip:3306/testDb"]
        }
      ]
    }
  },
  "target": {
    "appid": "test-appid",
    "table": "test_table_abc",
    "table_desc": "mysql test table",
    "partition_value": "@[{yyyy-MM-dd}-{1day}]",
    "column": [
      {
        "name": "db_id",
        "type": "bigint",
        "comment": "db serial number"
      },
      {
        "name": "log_time",
        "type": "timestamp",
        "comment": "time stamp"
      }
    ]
  }
}

3.1.2 파라미터 설명

• jdbcUrl
  • 설명: 피어 데이터베이스에 대한 JDBC 연결 정보를 JSON 배열로 설명합니다. jdbcUrl은 연결 구성 유닛에 반드시 포함되어야 합니다. 일반적으로 JSON 배열은 JDBC 연결로 채워질 수 있습니다.
  • 타입: jsonArray
  • 필수 여부: 예
  • 기본값: 없음
• username
  • 설명: 데이터 소스의 사용자 이름
  • 타입: string
  • 필수 여부: 예
  • 기본값: 없음
• password
  • 설명: 데이터 소스에 지정된 사용자 이름의 비밀번호
  • 타입: string
  • 필수 여부: 예
  • 기본값: 없음
• table
  • 설명: 동기화가 필요한 선택된 테이블들. JSON 배열 설명을 사용하므로 여러 테이블을 동시에 추출할 수 있습니다. 여러 테이블을 구성할 때, 사용자는 다중 테이블이 동일한 스키마 구조를 가졌는지 확인해야 합니다. MySQL Reader는 테이블들이 동일한 논리적 테이블인지 여부를 확인하지 않습니다. 테이블은 연결 구성 유닛에 반드시 포함되어야 합니다.
  • 타입: jsonArray
  • 필수 여부: 예
  • 기본값: 없음
• column
  • 설명: 동기화가 필요한 설정된 테이블의 열 이름 집합을 JSON 배열을 사용하여 설명합니다. 기본적으로 모든 열 구성을 사용하려면 ["*"]와 같이 *를 사용할 수 있습니다.
  • 타입: jsonArray
  • 필수 여부: 예
  • 기본값: 없음
• where
  • 설명: 지정된 열, 테이블 및 where 조건에 따라 SQL을 조합하여 데이터를 추출합니다. 실제 비즈니스 시나리오에서는 이전 날의 데이터를 선택하여 동기화하는 경우가 많으며, where 조건을 log_time >= '@[{yyyy-MM-dd 00:00:00}-{1day}]' AND log_time < '@[{yyyy-MM-dd 00:00:00}]'로 지정할 수 있습니다. where 조건은 limit 10으로 지정할 수 없습니다. limit는 SQL의 유효한 where 절이 아닙니다. where 조건은 효과적으로 비즈니스 증가분을 동기화할 수 있습니다. where 문이 채워지지 않으면, 임포트 도구는 전체 데이터를 동기화하는 것으로 간주됩니다.
  • 타입: string
  • 필수 여부: 아니요
  • 기본값: 없음
• querySql
  • 설명: 일부 비즈니스 시나리오에서 이 구성 항목이 필터 조건을 설명하기에 충분하지 않은 경우, 사용자는 이 구성 파라미터를 통해 사용자 정의 필터 SQL을 사용할 수 있습니다. 사용자가 이 항목을 구성하면 임포트 도구는 table 및 column의 구성 파라미터를 무시하고 이 구성 항목의 내용을 사용하여 데이터를 필터링합니다. 예를 들어, 다중 테이블 조인 후 데이터를 동기화해야 하는 경우: select a,b from table_a join table_b on table_a.id = table_b.id. 사용자가 querySql을 구성하면 임포트 도구는 table, column 및 where 조건 구성을 무시하고 querySql 우선 순위가 table, column 및 where 옵션보다 높습니다.
  • 타입: string
  • 필수 여부: 아니요
  • 기본값: 없음

3.2 txtfile 데이터 소스

txtfile 데이터 소스는 로컬 서버의 파일을 읽어 TA의 시스템 테이블로 가져옵니다. txtfile의 현재 사용 제한 및 특성은 다음과 같습니다:

1. TXT 파일만 지원하며, TXT의 스키마는 2차원 테이블이어야 합니다.
2. 사용자 정의 구분 기호가 있는 CSV와 유사한 형식의 파일을 지원합니다.
3. 여러 유형의 데이터 읽기(문자열로 표현), 열 클리핑 및 열 상수를 지원합니다.
4. 재귀적 읽기 및 파일 이름 필터링을 지원합니다.
5. 텍스트 압축을 지원하며, 현재 지원되는 압축 형식은 zip, gzip 및 bzip2입니다.

3.2.1 샘플 구성

{
  "parallel_num": 5,
  "source": {
    "type": "txtfile",
    "parameter": {
      "path": ["/home/ftp/data/testData/*"],
      "column": [
        {
          "index": 0,
          "type": "long"
        },
        {
          "index": 1,
          "type": "string"
        }
      ],
      "encoding": "UTF-8",
      "fieldDelimiter": "\t"
    }
  },
  "target": {
    "appid": "test-appid",
    "table": "test_table_abc",
    "table_desc": "mysql test table",
    "partition_value": "@[{yyyy-MM-dd}-{1day}]",
    "column": [
      {
        "name": "db_id",
        "type": "bigint",
        "comment": "db serial number"
      },
      {
        "name": "log_time",
        "type": "timestamp",
        "comment": "time stamp"
      }
    ]
  }
}

3.2.2 파라미터 설명

• path
  • 설명: 로컬 파일 시스템의 경로 정보. 여기서 여러 경로를 채울 수 있습니다. 와일드카드를 지정할 때 임포트 도구는 여러 파일 정보를 탐색하려고 시도합니다. 예를 들어, /data/를 지정하면 /data 디렉토리의 모든 파일을 읽는 것을 의미합니다. 현재 파일 와일드카드로 기호만 지원됩니다. 특히 중요한 점은 임포트 도구가 작업 하에 동기화된 모든 텍스트 파일을 동일한 데이터 테이블로 간주한다는 것입니다. 사용자는 모든 파일이 동일한 스키마 정보를 따르는지 확인해야 합니다. 파일은 CSV와 유사한 형식으로 읽어야 합니다.
  • 타입: string
  • 필수 여부: 예
  • 기본값: 없음
• column
  • 설명: 필드 목록을 읽습니다. type은 소스 데이터의 유형을 지정하고, index는 텍스트에서 현재 열(0부터 시작)을 지정합니다. value는 현재 유형을 상수로 지정하며, 소스 파일에서 데이터를 읽지 않고 value에 따라 해당 열을 자동 생성합니다.

기본적으로 사용자는 string 타입에 따라 모든 데이터를 읽을 수 있으며, 다음과 같이 구성됩니다:

 "column": ["*"]

사용자는 Column 필드 정보를 지정할 수 있으며, 다음과 같이 구성됩니다:

({
  "type": "long",
  "index": 0
},
{
  "type": "string",
  "value": "2018-07-01 00:00:00"
})

사용자가 지정한 Column 정보에 대해 type은 반드시 채워져야 하며 index/value를 선택해야 합니다.

type의 값 범위는 long, double, string 및 boolean입니다.

• 타입: jsonArray
• 필수 여부: 예
• 기본값: 없음
• fieldDelimiter
  • 설명: 필드를 구분하는 구분 기호
  • 타입: string
  • 필수 여부: 예
  • 기본값: ,
• compress
  • 설명: 텍스트 압축 유형. 기본적으로 비어 있으면 압축이 없습니다. 지원되는 압축 유형은 zip, gzip 및 bzip2입니다.
  • 타입: string
  • 필수 여부: 아니요
  • 기본값: 압축 없음
• encoding
  • 설명: 파일의 인코딩 구성
  • 타입: string
  • 필수 여부: 아니요
  • 기본값: utf-8
• skipHeader
  • 설명: CSV와 유사한 형식의 파일에는 제목으로 헤더가 있을 수 있으며, 이를 건너뛰어야 합니다. 기본값은 건너뛰지 않습니다.
  • 타입: boolean
  • 필수 여부: 아니요
  • 기본값: false
• nullFormat
  • 설명: 텍스트 파일에서는 표준 문자열을 사용하여 null(널 포인터)을 정의할 수 없습니다. ta-tool은 nullFormat을 제공하여 null로 표현될 수 있는 문자열을 정의합니다. 예를 들어, 사용자가 nullFormat:"\N"으로 구성하면, 소스 데이터가 "\N"인 경우 ta-tool은 이를 null필드로 간주합니다.
  • 타입: string
  • 필수 여부: 아니요
  • 기본값: \N