본문으로 건너뛰기

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

최근 업데이트 2026. 10. 03.

1. 개요​

경우에 따라 사용해야 하는 데이터를 user 또는 event 형태로 나타낼 수 없을 때가 있습니다. 예를 들어 매핑 관계 테이블이나 외부 데이터 등입니다. 이러한 데이터를 활용하려면 data_transfer 명령으로 커스텀 데이터를 AE 시스템에 가져온 후, 이벤트 테이블 및 유저 테이블과 연결하여 사용해야 합니다.

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

  • 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": "가져오기 테스트 테이블",
    "partition_value": "@[{yyyyMMdd}-{1day}]",
    "column": [
      {
        "name": "col1",
        "type": "timestamp",
        "comment": "타임스탬프"
      },
      {
        "name": "col2",
        "type": "varchar"
      }
    ]
  }
}

2.3.2 최상위 파라미터 설명​

  • parallel_num

    • 설명: 가져오기 동시 실행 스레드 수로, 가져오기 속도를 제어합니다
    • 타입: int
    • 필수: 예
    • 기본값: 없음

  • source

    • 설명: 가져오기 데이터 소스의 구체적인 파라미터 설정
    • 타입: jsonObject
    • 필수: 예
    • 기본값: 없음

  • target

    • 설명: 가져오기 대상 테이블의 구체적인 파라미터 설정
    • 타입: jsonObject
    • 필수: 예
    • 기본값: 없음

2.3.3 source 파라미터 상세 설명​

  • type

    • 설명: 가져오기 데이터 소스의 타입입니다. 현재 가져오기 도구는 txtfile, mysql, ftp 세 가지 가져오기 데이터 소스를 지원하며, 이후 더 많은 데이터 소스를 지원할 예정입니다
    • 타입: string
    • 필수: 예
    • 기본값: 없음

  • parameter

2.3.4 target 파라미터 상세 설명​

  • appid

    • 설명: 가져올 테이블에 해당하는 프로젝트 appid로, AE 시스템 백엔드에서 확인할 수 있습니다
    • 타입: string
    • 필수: 예
    • 기본값: 없음

  • table

    • 설명: AE 시스템에 가져올 테이블 이름입니다. 주의: 테이블 이름은 전역에서 중복될 수 없으므로, 프로젝트별로 구분할 수 있는 접두사 또는 접미사를 붙이는 것을 권장합니다
    • 타입: string
    • 필수: 예
    • 기본값: 없음

  • table_desc

    • 설명: 가져올 테이블의 주석입니다. 이후 테이블을 조회할 때 테이블의 의미를 명확히 알 수 있도록 가져올 때 이 파라미터를 설정하는 것을 권장합니다
    • 타입: string
    • 필수: 아니요
    • 기본값: 빈 값

  • partition_value

    • 설명: 가져오기 파티션 값입니다. AE 시스템에 가져온 커스텀 테이블에는 기본적으로 파티션 필드 $pt가 붙으므로, 가져올 때 반드시 파티션 값을 지정해야 합니다. 일반적으로 가져오는 데이터의 날짜로 설정하며(예: 20180701), 시간 매크로 치환도 지원합니다(예: @[{yyyyMMdd}-{1day}]). 구체적인 사용 방법은 2.4절에서 소개합니다
    • 타입: string
    • 필수: 예
    • 기본값: 없음

  • column

    • 설명: AE 시스템에 가져올 테이블의 필드를 정의합니다. name, type, comment 3개의 속성 값을 포함하며, 그중 name과 type은 필수 필드입니다. 예시는 다음과 같습니다.
[
  {
    "name": "col1",
    "type": "timestamp",
    "comment": "타임스탬프"
  },
  {
    "name": "col2",
    "type": "varchar"
  }
]

source 측이 mysql이고 테이블 전체를 가져오는 경우(즉, column 필드가 ["*"]인 경우) target에 column 파라미터를 전달하지 않아도 되며, 가져오기 도구는 mysql의 테이블 구조를 기준으로 합니다. 그 외의 경우에는 이 필드를 반드시 전달해야 합니다

  • 타입: jsonArray
  • 필수: 아니요
  • 기본값: mysql source 측의 테이블 schema 정의

2.4 시간 매크로 사용 방법​

설정 파일 안에서 시간 매크로로 시간 파라미터를 치환할 수 있습니다. ta-tool 도구는 가져오기 시작 시간을 기준으로 시간 매크로의 파라미터에 따라 시간 오프셋을 계산하고, 설정 파일의 시간 매크로를 치환합니다. 지원하는 시간 매크로 형식: @[{yyyyMMdd}], @[{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 세 가지 가져오기 데이터 소스를 지원하며, 데이터 소스에 따라 source의 파라미터를 조정해야 합니다

3.1 mysql 데이터 소스​

이 데이터 소스는 JDBC 커넥터로 원격 mysql 데이터베이스에 연결하고, 사용자가 설정한 정보에 따라 SELECT SQL 쿼리 문을 생성하여 원격 mysql 데이터베이스로 보낸 다음, 해당 SQL의 실행 결과를 AE 시스템의 테이블로 가져옵니다

3.1.1 설정 예시​

  • mysql 테이블 전체를 AE 시스템으로 가져오는 설정 예시:
{
  "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 테스트 테이블",
    "partition_value": "@[{yyyy-MM-dd}-{1day}]"
  }
}
  • 커스텀 sql로 AE 시스템에 가져오는 설정 예시:
{
  "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 테스트 테이블",
    "partition_value": "@[{yyyy-MM-dd}-{1day}]",
    "column": [
      {
        "name": "db_id",
        "type": "bigint",
        "comment": "db 번호"
      },
      {
        "name": "log_time",
        "type": "timestamp",
        "comment": "타임스탬프"
      }
    ]
  }
}

3.1.2 parameter 파라미터 설명​

  • jdbcUrl

    • 설명: 대상 데이터베이스에 대한 JDBC 연결 정보를 JSON 배열로 기술합니다. 주의: jdbcUrl은 connection 설정 단위 안에 포함되어야 합니다. 일반적으로 JSON 배열에는 JDBC 연결 하나만 입력하면 됩니다.
    • 타입: jsonArray
    • 필수: 예
    • 기본값: 없음

  • username

    • 설명: 데이터 소스의 사용자 이름
    • 타입: string
    • 필수: 예
    • 기본값: 없음

  • password

    • 설명: 데이터 소스에 지정한 사용자 이름의 비밀번호
    • 타입: string
    • 필수: 예
    • 기본값: 없음

  • table

    • 설명: 동기화할 테이블입니다. JSON 배열로 기술하므로 여러 테이블을 동시에 추출할 수 있습니다. 여러 테이블을 설정한 경우 여러 테이블의 schema 구조가 같은지 사용자가 직접 확인해야 하며, MysqlReader는 테이블이 같은 논리 테이블인지 검사하지 않습니다. 주의: table은 connection 설정 단위 안에 포함되어야 합니다.
    • 타입: jsonArray
    • 필수: 예
    • 기본값: 없음

  • column

    • 설명: 설정한 테이블에서 동기화할 열 이름의 집합으로, JSON 배열로 필드 정보를 기술합니다. * 기호로 모든 열을 사용하는 기본 설정을 나타낼 수 있습니다. 예: ["*"]
    • 타입: jsonArray
    • 필수: 예
    • 기본값: 없음

  • where

    • 설명: 필터 조건입니다. 지정한 column, table, where 조건으로 SQL을 조합하고, 이 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

    • 설명: 일부 비즈니스 시나리오에서는 where 설정 항목만으로 필터 조건을 충분히 기술할 수 없으므로, 사용자가 이 설정 파라미터로 필터 SQL을 직접 정의할 수 있습니다. 이 항목을 설정하면 가져오기 도구는 table, column 등의 설정 파라미터를 무시하고 이 설정 항목의 내용으로 데이터를 필터링합니다. 예를 들어 여러 테이블을 join한 후 데이터를 동기화해야 하는 경우: 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 데이터 소스는 로컬 서버의 파일을 읽어 AE의 시스템 테이블로 가져옵니다. 현재 txtfile의 사용 제한과 특성은 다음과 같습니다.

  1. TXT 파일 읽기만 지원하며, TXT의 schema는 2차원 테이블이어야 합니다
  2. CSV 유사 형식 파일과 커스텀 구분자를 지원합니다
  3. 여러 타입의 데이터 읽기(string으로 표시)를 지원하며, 열 잘라내기와 열 상수를 지원합니다
  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 테스트 테이블",
    "partition_value": "@[{yyyy-MM-dd}-{1day}]",
    "column": [
      {
        "name": "db_id",
        "type": "bigint",
        "comment": "db 번호"
      },
      {
        "name": "log_time",
        "type": "timestamp",
        "comment": "타임스탬프"
      }
    ]
  }
}

3.2.2 parameter 파라미터 설명​

  • path

    • 설명: 로컬 파일 시스템의 경로 정보이며, 여러 경로를 입력할 수 있습니다. 와일드카드를 지정하면 가져오기 도구는 여러 파일 정보를 순회합니다. 예: /data/*를 지정하면 /data 디렉토리 아래의 모든 파일을 읽습니다. 현재는 * 기호만 파일 와일드카드로 지원합니다. 특히 주의할 점은 가져오기 도구가 한 작업에서 동기화하는 모든 Text File을 같은 데이터 테이블로 간주한다는 것입니다. 사용자는 모든 File이 같은 schema 정보에 맞는지 직접 확인해야 합니다. 읽는 파일은 반드시 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
이 문서가 도움이 되었나요?
이 페이지의 내용