http://starrocks.io logo
Join Slack
Powered by
<@U0A71G31CDV> internal catalog의 테이블이 s3에 연결되어있는데,...
# questions-and-troubleshooting
s
@Rocky internal catalog의 테이블이 s3에 연결되어있는데, 그 데이블의 데이터를 s3로 dump뜰 수 있어?
r
네, 가능합니다. StarRocks의 *Internal Catalog*(내부 엔진용 테이블) 데이터가 Shared-data 모드 등을 통해 이미 S3에 저장되어 있더라도, 이를 사용자가 읽을 수 있는 일반적인 형식(Parquet, CSV 등)으로 특정 S3 경로에 Dump(Unload) 할 수 있습니다. 가장 권장되는 방식은 최신 버전(v3.1 이상)에서 지원하는 
INSERT INTO FILES()
 방식입니다. 1. INSERT INTO FILES (가장 추천) 데이터를 조회하여 바로 S3의 특정 경로에 파일로 저장합니다. Parquet, ORC, CSV 형식을 지원하며 사용법이 매우 간단합니다.
Copy code
sql
INSERT INTO FILES (
    "path" = "<s3://your-bucket/dump/path/data_>",
    "format" = "parquet",            -- 또는 "csv", "orc"
    "compression" = "lz4",          -- 압축 방식 선택
    "aws.s3.access_key" = "xxxx",
    "aws.s3.secret_key" = "xxxx",
    "aws.s3.region" = "ap-northeast-2"
)
SELECT * FROM internal_catalog.db_name.table_name;
* 특징: 
SELECT
문을 자유롭게 사용하여 특정 조건의 데이터만 추출하거나 컬럼을 가공해서 덤프를 뜰 수 있습니다. * 버전: v3.1 이상 (CSV는 v3.3 이상 권장) 2. EXPORT 구문 전통적인 방식으로, 비동기 작업을 생성하여 테이블 데이터를 S3로 내보냅니다.
Copy code
sql
EXPORT TABLE internal_catalog.db_name.table_name
TO "<s3://your-bucket/dump/path/>"
PROPERTIES (
    "format" = "csv",
    "column_separator" = ","
)
WITH BROKER (
    "aws.s3.access_key" = "xxxx",
    "aws.s3.secret_key" = "xxxx",
    "aws.s3.region" = "ap-northeast-2"
);
* 특징: 백그라운드에서 작업이 실행되므로 대용량 데이터 덤프에 적합합니다. 
SHOW EXPORT;
명령어로 진행 상황을 확인할 수 있습니다. 참고사항 * Shared-data 모드 관련: 만약 StarRocks를 Shared-data(Cloud-native) 모드로 사용 중이시라면, 내부 데이터가 이미 S3에 저장되어 있지만 이는 StarRocks 전용 포맷(세그먼트 파일)입니다. 따라서 외부 서비스(Spark, Hive 등)에서 읽으려면 위와 같이 표준 포맷(Parquet/CSV)으로 다시 내보내야 합니다. * 권한: 데이터를 내보내려는 S3 버킷에 대해 쓰기(Write) 권한이 있는 IAM Key 또는 Role이 필요합니다. References • loading/s3.md • unloading/unload_using_insert_into_files.md
s
@Rocky export를 parquet로 하는 예시를 줘
r
현재 StarRocks의 
EXPORT
명령은 공식적으로 *CSV 형식만 지원*합니다 (Parquet 형식은 
EXPORT
구문에서는 아직 지원 예정 단계입니다). 따라서 데이터를 *Parquet 형식으로 S3에 덤프(Unload)*하려면, v3.2부터 도입된 
INSERT INTO FILES()
 구문을 사용해야 합니다. 이 방식이 현재 StarRocks에서 권장하는 표준 Parquet 덤프 방법입니다. Parquet 형식으로 S3 덤프 예시 (
INSERT INTO FILES
) 이 명령은 
SELECT
결과를 지정한 S3 경로에 Parquet 파일로 즉시 저장합니다.
Copy code
sql
INSERT INTO FILES (
    "path" = "<s3://your-bucket-name/dump/my_table_data/>",
    "format" = "parquet",               -- 파일 형식 지정 (parquet)
    "compression" = "snappy",           -- 압축 방식 (snappy, lz4, zstd, gzip 등)
    "aws.s3.access_key" = "YOUR_AK",
    "aws.s3.secret_key" = "YOUR_SK",
    "aws.s3.region" = "ap-northeast-2",
    "parquet.use_legacy_encoding" = "false" -- 필요 시 설정
)
SELECT * FROM internal_catalog.your_db.your_table;
주요 특징 1. 형식 지정: `"format" = "parquet"`을 통해 Parquet로 출력함을 명시합니다. 2. 비동기 처리: `EXPORT`와 달리 `INSERT INTO FILES`는 일반 쿼리처럼 실행됩니다. 만약 대용량 데이터를 비동기로 처리하고 싶다면 별도의 클라이언트(예: Airflow, 스크립트)에서 실행하거나, `INSERT INTO FILES`를 지원하는 최신 버전의 기능을 활용하십시오. 3. 경로: 
path
마지막에 `/`를 붙이면 해당 디렉토리 안에 여러 개의 Parquet 파일이 생성됩니다. `/data_`와 같이 접두어를 붙이면 파일명이 해당 접두어로 시작합니다. 요약 * EXPORT TABLE: CSV만 가능. * INSERT INTO FILES: Parquet, ORC, CSV 가능 (권장 방식). 만약 반드시 
EXPORT
구문을 사용해야 하는 상황(비동기 작업 ID가 꼭 필요한 경우 등)이라면 현재는 CSV 포맷으로만 가능함을 유의해 주세요. References • loading/loading_introduction/feature-support-loading-and-unloading.md • sql-reference/sql-statements/loading_unloading/unloading/EXPORT.md • unloading/unload_using_insert_into_files.md References • sql-reference/sql-statements/loading_unloading/unloading/EXPORT.md • sql-reference/sql-functions/table-functions/files.md • data_source/catalog/hive_catalog.md • loading/Spark-connector-starrocks.md
s
@Rocky csv읽을떈 어떻게 읽어?
r
StarRocks에서 S3에 있는 CSV 파일을 읽는 가장 쉽고 권장되는 방법은 *`FILES()` 테이블 함수*를 사용하는 것입니다. 별도의 테이블 생성 없이 
SELECT
문만으로 즉시 데이터를 조회할 수 있습니다. 1. 
FILES()
함수로 직접 조회 (가장 간편) v3.1부터 지원되는 이 방식은 S3 경로와 파일 정보를 쿼리에 직접 입력하여 데이터를 읽습니다.
Copy code
sql
SELECT * FROM FILES(
    "path" = "<s3://your-bucket/path/to/your_data.csv>",
    "format" = "csv",
    "column_separator" = ",",         -- 구분자 (기본값은 ,)
    "row_delimiter" = "\n",            -- 줄 바꿈 기호
    "header" = "true",                 -- 첫 번째 줄이 컬럼명인 경우 true
    "aws.s3.access_key" = "YOUR_AK",
    "aws.s3.secret_key" = "YOUR_SK",
    "aws.s3.region" = "ap-northeast-2"
);
2. External Table 생성 (자주 읽을 때) 매번 S3 정보를 입력하기 번거롭다면, S3의 파일을 참조하는 *외부 테이블*을 만들어 두고 일반 테이블처럼 조회할 수 있습니다.
Copy code
sql
CREATE EXTERNAL TABLE ext_csv_table (
    id INT,
    name STRING,
    age INT
) 
ENGINE=FILE
PROPERTIES (
    "path" = "<s3://your-bucket/path/to/folder/>", -- 폴더 단위 지정 가능
    "format" = "csv",
    "column_separator" = ",",
    "aws.s3.access_key" = "YOUR_AK",
    "aws.s3.secret_key" = "YOUR_SK",
    "aws.s3.region" = "ap-northeast-2"
);

-- 생성 후 일반 테이블처럼 조회
SELECT * FROM ext_csv_table WHERE id > 10;
3. CSV 읽을 때 주요 옵션 CSV는 정형화된 형식이 아니므로 아래 옵션들을 상황에 맞게 설정해야 정확하게 읽을 수 있습니다. * 
column_separator
: 컬럼 구분자. (예: 
,
, 
\t
, 
|
) * 
row_delimiter
: 행 구분자. (일반적으로 
\n
) * 
header
: `true`로 설정하면 첫 번째 행을 데이터가 아닌 컬럼 헤더로 인식하여 건너뜁니다. * 
trim_space
: 컬럼 값 앞뒤의 공백을 제거할지 여부 (
"true"
또는 
"false"
). * 
enclosed_by
: 데이터가 큰따옴표(
"
) 등으로 감싸져 있는 경우 사용합니다 (예: 
"enclosed_by" = '"'
). 참고: 스키마 자동 추론 
FILES()
함수를 사용할 때 스키마를 모르겠다면, `DESC FUNCTION FILES(...)`를 실행하여 StarRocks가 추론한 데이터 타입을 미리 확인할 수도 있습니다. References • sql-reference/sql-functions/table-functions/files.md • loading/s3.md • data_source/file_external_table.md
s
@Rocky column_separator 지정해줬는데, 분리가 안돼 $1이라고만나와
r
`column_separator`를 지정했는데도 데이터가 분리되지 않고 `$1`이라는 하나의 컬럼에 모든 데이터가 들어온다면, 보통 다음 두 가지 이유 때문일 가능성이 매우 높습니다. 1. 속성 이름 확인 (
csv.
접두어) 
FILES()
테이블 함수를 사용하신다면, 그냥 `"column_separator"`가 아니라 반드시 *`"csv.column_separator"`*라고 작성해야 합니다. (
csv.
접두어가 붙어야 함) * 잘못된 예: 
"column_separator" = ","
* 올바른 예: 
"csv.column_separator" = ","
2. 이스케이프(Escape) 및 특수 문자 처리 탭(
\t
)이나 줄 바꿈(
\n
) 같은 보이지 않는 문자를 구분자로 사용할 경우, MySQL 클라이언트와 StarRocks 서버 사이의 이스케이프 처리를 위해 역슬래시를 두 번(
\\
) 써야 할 때가 많습니다. * 탭(Tab)인 경우: 
"csv.column_separator" = "\\\\t"
* 특수 제어 문자(예: Hive 기본 구분자 \x01)인 경우: 
"csv.column_separator" = "\\\\x01"
3. 행 구분자(
row_delimiter
) 문제 데이터의 행이 제대로 끊기지 않으면 첫 번째 줄의 구분자만 찾다가 실패할 수 있습니다. 특히 Windows 형식의 줄 바꿈(
\r\n
)인 경우 명시해주는 것이 좋습니다. * 예: 
"csv.row_delimiter" = "\\\\r\\\\n"
────────── 해결을 위한 체크리스트 예시 (FILES 함수 기준) 만약 쉼표(
,
)로 구분된 CSV 파일이라면 아래와 같이 작성해 보세요.
Copy code
sql
SELECT * FROM FILES(
    "path" = "<s3://your-bucket/data.csv>",
    "format" = "csv",
    "csv.column_separator" = ",",      -- 반드시 'csv.' 접두어 확인
    "csv.row_delimiter" = "\n",        -- 행 구분자 확인
    "csv.skip_header" = "1",           -- 첫 줄이 헤더면 필수
    "aws.s3.access_key" = "...",
    "aws.s3.secret_key" = "...",
    "aws.s3.region" = "..."
);
팁: 만약 여전히 안 된다면, `DESC FUNCTION FILES(...)`를 실행하여 StarRocks가 현재 설정으로 컬럼을 어떻게 인식하고 있는지(하나의 STRING으로 보는지 여러 개로 보는지) 먼저 확인해 보시기 바랍니다. References • sql-reference/sql-functions/table-functions/files.md • sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md References • sql-reference/sql-functions/table-functions/files.md
s
@Rocky 폴더로 지정하면 에러나
r
FILES()
함수로 폴더 내의 여러 파일을 한 번에 읽으려면, 경로 끝에 *와일드카드(
*
)*를 붙여주어야 합니다. 단순히 폴더 경로만 입력하면 해당 경로를 하나의 파일로 인식하려고 시도하기 때문에 에러가 발생할 수 있습니다. *해결 방법: 경로 끝에 
*
추가* 폴더 내의 모든 파일을 읽고 싶다면 다음과 같이 작성하세요.
Copy code
sql
SELECT * FROM FILES(
    "path" = "<s3://your-bucket/your-folder/*>",  -- 폴더 내 모든 파일
    -- 또는 "path" = "<s3://your-bucket/your-folder/*.csv>", -- 특정 확장자만
    "format" = "csv",
    "csv.column_separator" = ",",
    "aws.s3.access_key" = "...",
    "aws.s3.secret_key" = "...",
    "aws.s3.region" = "..."
);
주의사항 및 체크리스트 1. 하위 폴더까지 읽기: 만약 폴더 안에 또 다른 하위 폴더가 있고 그 안의 파일까지 읽어야 한다면, 현재 `FILES()`의 데이터 읽기 모드에서는 경로 패턴을 `"s3://bucket/folder/**/_"`와 같이 지정하거나 각 뎁스에 맞춰 `_`를 사용해야 할 수 있습니다. 2. 동일한 스키마: 폴더 내의 모든 파일은 *동일한 컬럼 구조(스키마)*를 가지고 있어야 합니다. 만약 파일마다 컬럼 개수가 다르거나 데이터 타입이 다르면 읽기 과정에서 에러가 발생합니다. 3. 불필요한 파일 제외: 폴더 안에 
_SUCCESS
같은 메타데이터 파일이나 로그 파일이 섞여 있으면, StarRocks가 이를 CSV 데이터로 읽으려다 실패합니다. 이 경우 
*.csv
처럼 확장자를 명시하여 데이터 파일만 필터링하세요. 에러 메시지가 구체적으로 어떻게 나오나요? 만약 위 방법으로도 해결되지 않는다면, 발생하는 에러 메시지를 알려주시면 더 정확한 원인을 파악해 드릴 수 있습니다. (예: 
Access Denied
, 
Not a directory
, 
Schema mismatch
등) References • sql-reference/sql-functions/table-functions/files.md • loading/s3.md References • sql-reference/sql-functions/table-functions/files.md
2 Views
Open in Slack
PreviousNext
Powered by