Snowflake RETURN_FAILED_ONLYについて

RETURN_FAILED_ONLYについて見ていきましょう。
COPYコマンドのオプションで指定ができます。どのような動作をするのでしょうか。。。

RETURN_FAILED_ONLYとは

ドキュメントより抜粋

RETURN_FAILED_ONLY = TRUE | FALSE
定義:ステートメント結果でロードに失敗したファイルのみを返すかどうかを指定するブール値。
デフォルト:FALSE

早速動作を見てみる

準備

DBのテーブルと外部ステージを作成する

CREATE OR REPLACE TABLE  COPY_DB.PUBLIC.ORDERS (
    ORDER_ID VARCHAR(30),
    AMOUNT VARCHAR(30),
    PROFIT INT,
    QUANTITY INT,
    CATEGORY VARCHAR(30),
    SUBCATEGORY VARCHAR(30));

CREATE OR REPLACE STAGE COPY_DB.PUBLIC.aws_stage_copy
    url='s3://snowflakebucket-copyoption/returnfailed/';

コマンド実行

COPY INTO COPY_DB.PUBLIC.ORDERS
    FROM @aws_stage_copy
    file_format= (type = csv field_delimiter=',' skip_header=1)
    pattern='.*Order.*'
    RETURN_FAILED_ONLY = TRUE

コマンド結果

以前の記事で見たようなエラー内容です。

Numeric value '7-' is not recognized ファイル「returnfailed/OrderDetails_error2 - Copy.csv」、行 2、文字 17 行 1、列 "ORDERS"["QUANTITY":4] エラーが発生してもロードを継続したい場合は、ON_ERRORオプションに「SKIP_FILE」または「CONTINUE」などの別の値を使用します。ロードのオプションの詳細については、SQLクライアントで「info loading_data」を実行してください。

ON_ERROR = CONTINUEと併用する

ON_ERROR = CONTINUEと併用することで真価が発揮されます。

COPY INTO COPY_DB.PUBLIC.ORDERS
    FROM @aws_stage_copy
    file_format= (type = csv field_delimiter=',' skip_header=1)
    pattern='.*Order.*'
    ON_ERROR =CONTINUE
    RETURN_FAILED_ONLY = TRUE

コマンド結果

ん～ちょっと分かりづらいので、さらに下にCONTINUEありでRETURN_FAILED_ONLYなしと比較してみます。
CONTINUEあり、RETURN_FAILED_ONLYあり

file	file_count	status	rows_parsed	rows_loaded	error_limit	errors_seen	first_error	first_error_line	first_error_character	first_error_column_name
-	2	LOADED	3000	3000		0
s3://snowflakebucket-copyoption/returnfailed/OrderDetails_error2 - Copy.csv	1	PARTIALLY_LOADED	285	283	285	2	Numeric value '7-' is not recognized	2	17	ORDERS""[""QUANTITY"":4]
s3://snowflakebucket-copyoption/returnfailed/OrderDetails_error.csv	1	PARTIALLY_LOADED	1500	1498	1500	2	Numeric value 'one thousand' is not recognized	2	14	ORDERS""[""PROFIT"":3]

CONTINUEあり、RETURN_FAILED_ONLYなし

file	status	rows_parsed	rows_loaded	error_limit	errors_seen	first_error	first_error_line	first_error_character	first_error_column_name
s3://snowflakebucket-copyoption/returnfailed/OrderDetails_error2 - Copy.csv	PARTIALLY_LOADED	285	283	285	2	Numeric value '7-' is not recognized	2	17	ORDERS""[""QUANTITY"":4]
s3://snowflakebucket-copyoption/returnfailed/OrderDetails_error.csv	PARTIALLY_LOADED	1500	1498	1500	2	Numeric value 'one thousand' is not recognized	2	14	ORDERS""[""PROFIT"":3]
s3://snowflakebucket-copyoption/returnfailed/Orders.csv	LOADED	1500	1500	1500	0
s3://snowflakebucket-copyoption/returnfailed/Orders2.csv	LOADED	1500	1500	1500	0

違い
一番目に付く箇所で言えば、LOADED行が1行に省略されていますね。それに伴いfile_count列も追加されています。