JSON 資料檔案 JSONPaths 檔案 JSONPath 表達式 JSONPaths 搭配 Avro Data 使用單欄資料格式參數

資料格式參數

根據預設， COPY命令預期來源資料為字元分隔 UTF-8 文字。預設分隔符號是縱線字元 ( | )。如果來源資料是其他格式，請使用下列參數來指定資料格式：

FORMAT
CSV
DELIMITER
FIXEDWIDTH
SHAPEFILE
AVRO
JSON
PARQUET
ORC

除了標準資料格式之外， COPY還支援COPY來自 Amazon S3 的下列資料欄資料格式：

ORC
PARQUET

COPY 資料欄格式支援特定限制。如需詳細資訊，請參閱COPY 從資料欄資料格式。

資料格式參數

FORMAT 【AS】

(選用) 識別資料格式關鍵字。引FORMAT數說明如下。

CSV QUOTE【【AS】 'quote_character' 】

啟用輸入資料中的CSV格式。若要自動逸出分隔符號、新行字元和歸位字元，請在 QUOTE 參數指定的字元中包含欄位。預設引號字元為雙引號 ( " )。在欄位內使用引號字元時，請多加一個引號字元來逸出此字元。例如，假設引號字元是雙引號，若要插入 A "quoted" word 字串，則輸入檔案應該包含 "A ""quoted"" word" 字串。使用 CSV 參數時，預設分隔符號為逗號（，）。您可以使用 DELIMITER 參數指定不同的分隔符號。

以引號括住欄位時，分隔字元和引號字元之間的空格會被忽略。如果分隔字元是空格字元 (例如 Tab 字元)，則不會將分隔字元視為空格。

CSV 無法與 FIXEDWIDTH、 REMOVEQUOTES或搭配使用ESCAPE。

QUOTE 【AS】 'quote_character': 選用。指定使用 CSV 參數時要用作引號字元的字元。預設值為雙引號 ( " )。如果您使用 QUOTE 參數來定義雙引號以外的引號字元，則不需要在欄位中逸出雙引號。QUOTE 參數只能與 CSV 參數搭配使用。AS 關鍵字為選用。

DELIMITER 【AS】【'delimiter_char '】

指定用來分隔輸入檔案中欄位的字元，例如管道字元 | （）、逗號 , （）、標籤（ \t ）或多個字元，例如 |~|。支援不可列印的字元。字元也可以以八進位表示為 UTF-8 碼單位。對於八進位數字，請使用格式 '\ddd'，其中 'd' 是八進位數字（0–7）。預設分隔符號為管道字元（ | ），除非使用 CSV 參數，在這種情況下，預設分隔符號為逗號（ , ）。AS 關鍵字為選用。DELIMITER 無法與搭配使用FIXEDWIDTH。

FIXEDWIDTH 'fixedwidth_spec '

從每個欄寬是固定長度 (而不是以分隔字元隔開的欄) 的檔案載入資料。fixedwidth_spec 是字串，指定使用者定義的欄標籤和欄寬。欄標籤可以是文字字串或整數 (視使用者的選擇而定)。欄標籤與欄名稱無關。標籤/寬度配對的順序必須完全符合資料表欄的順序。FIXEDWIDTH 無法與 CSV或搭配使用DELIMITER。在 Amazon Redshift 中， CHAR 和 VARCHAR資料欄的長度是以位元組表示，因此在準備要載入的檔案時，請確定您指定的資料欄寬度可容納多位元組字元的二進位長度。如需詳細資訊，請參閱字元類型。

fixedwidth_spec 的格式如下所示：


'colLabel1:colWidth1,colLabel:colWidth2, ...'

SHAPEFILE SIMPLIFY【【AUTO】【'公差'】】

啟用輸入資料中的SHAPEFILE格式。依預設，Shapefile 的第一個資料欄是 GEOMETRY 或 IDENTITY 資料欄。所有後續的資料欄都會遵循 Shapefile 中指定的順序。

您無法SHAPEFILE搭配 FIXEDWIDTH、 REMOVEQUOTES或使用 ESCAPE。

若要搭配 GEOGRAPHY 物件使用 COPY FROM SHAPEFILE，請先擷取至 GEOMETRY 欄中，然後將物件轉換為 GEOGRAPHY 物件。

SIMPLIFY 【容差】: （選用）使用 Ramer-Douglas-Peucker演算法和指定的容差，簡化擷取過程中的所有幾何。
SIMPLIFY AUTO 【容差】: (選用) 僅簡化大於最大幾何大小的幾何。如果未超過指定的公差，此簡化會使用 Ramer-Douglas-Peucker演算法和自動計算公差。此演算法會在指定公差內計算儲存物件的大小。tolerance 值是選用的。

如需載入 Shapefile 的範例，請參閱將 Shapefile 載入 Amazon Redshift。

AVRO 【AS】 'avro_option '

指定來源資料是 Avro 格式。

COPY 這些服務和通訊協定支援 Avro 格式：

Amazon S3
Amazon EMR
遠端主機（SSH）

COPY DynamoDB 不支援 Avro 的。

Avro 是資料序列化通訊協定。Avro 來源檔案包含結構描述來定義資料的結構。Avro 結構描述類型必須是 record。COPY 接受使用預設未壓縮轉碼器以及 deflate和snappy壓縮轉碼器建立的 Avro 檔案。如需 Avro 的相關資訊，請前往 Apache Avro。

avro_option 的有效值如下所示：

'auto'
'auto ignorecase'
's3://jsonpaths_file'

預設值為 'auto'。

COPY 會自動將 Avro 來源資料中的資料元素映射至目標資料表中的資料欄。它會比對 Avro 結構描述中的欄位名稱與目標資料表中的欄名稱。'auto' 的比對區分大小寫，而 'auto ignorecase' 的比對不區分大小寫。

Amazon Redshift 資料表中的欄名稱一律為小寫，因此當您使用 'auto' 選項時，相符欄位名稱也必須是小寫。如果欄位名稱並非全部小寫，您可以使用 'auto ignorecase' 選項。使用預設'auto'引數時，只會COPY辨識結構中欄位的第一層或外部欄位 。

若要將欄名稱明確映射至 Avro 欄位名稱，您可以使用 JSONPaths 檔案。

根據預設， COPY會嘗試將目標資料表中的所有資料欄與 Avro 欄位名稱比對。若要載入欄子集，您可以選擇性指定欄清單。如果目標資料表中的資料欄從資料欄清單中省略，會COPY載入目標資料欄的DEFAULT表達式。如果目標欄沒有預設值，會COPY嘗試載入 NULL。如果資料欄包含在資料欄清單中，但 Avro 資料中COPY找不到相符的欄位，會COPY嘗試載入NULL資料欄。

如果COPY嘗試NULL將指派給定義為 NOT 的欄NULL，則COPY命令會失敗。

Avro 結構描述

Avro 來源資料檔案包含結構描述來定義資料的結構。COPY 會讀取屬於 Avro 來源資料檔案一部分的結構描述，以將資料元素對應至目標資料表資料欄。下列範例顯示 Avro 結構描述。


{
    "name": "person",
    "type": "record",
    "fields": [
        {"name": "id", "type": "int"},
        {"name": "guid", "type": "string"},
        {"name": "name", "type": "string"},
        {"name": "address", "type": "string"}]
}

Avro 結構描述是使用 JSON 格式定義的。頂層JSON物件包含三個名稱值對，其中包含名稱或索引鍵 、"type"、 "name"和 "fields"。

內含物件陣列的 "fields" 金鑰對會定義資料結構中每個欄位的名稱和資料類型。根據預設， COPY會自動將欄位名稱與資料欄名稱相符。欄名稱一律為小寫，因此相符的欄位名稱也必須是小寫，除非您指定 ‘auto ignorecase’ 選項。不符合欄名稱的任何欄位名稱會被忽略。順序並不重要。在上一個範例中，會COPY映射到資料欄名稱 id、guid、 name和 address。

使用預設'auto'引數，只會將第一級物件與資料欄COPY比對。若要映射到結構描述中的更深層，或者如果欄位名稱和資料欄名稱不相符，請使用 JSONPaths 檔案定義映射。如需詳細資訊，請參閱JSONPaths 檔案。

如果與金鑰相關聯的值是複雜的 Avro 資料類型，例如位元組、陣列、記錄、地圖或連結，會將值COPY載入為字串。此處，字串是資料的JSON表示法。COPY 會將 Avro 列舉資料類型載入為字串，其中內容是類型的名稱。如需範例，請參閱COPY 從JSON格式。

Avro 檔案標頭 (包括結構描述和檔案中繼資料) 的大小上限為 1 MB。

單一 Avro 資料區塊的大小上限為 4 MB。這不同於資料列大小上限。如果超過單一 Avro 資料區塊的大小上限，即使產生的資料列大小小於 4 MB 的資料列大小限制，COPY命令也會失敗。

在計算列大小時，Amazon Redshift 會在內部將縱線字元 ( | ) 計算兩次。如果輸入資料包含非常多的縱線字元，即使資料區塊小於 4 MB，資料列大小仍可能超過 4 MB。

JSON 【AS】 'json_option '

來源資料格式為 JSON 。

JSON COPY 從這些服務和通訊協定支援的格式：

Amazon S3
COPY 從 Amazon EMR
COPY 從 SSH

JSON COPY DynamoDB 不支援的。

json_option 的有效值如下所示：

'auto'
'auto ignorecase'
's3://jsonpaths_file'
'noshred'

預設值為 'auto'。Amazon Redshift 不會在載入JSON文件時將JSON結構的屬性分割為多個資料欄。

根據預設， COPY會嘗試將目標資料表中的所有資料欄與JSON欄位名稱索引鍵比對。若要載入欄子集，您可以選擇性指定欄清單。如果JSON欄位名稱索引鍵不是全部小寫，您可以使用 'auto ignorecase'選項或 JSONPaths 檔案將資料欄名稱明確對應至JSON欄位名稱索引鍵。

如果目標資料表中的資料欄從資料欄清單中省略，則會COPY載入目標資料欄的DEFAULT表達式。如果目標欄沒有預設值，會COPY嘗試載入 NULL。如果資料欄包含在資料欄清單中，但COPY找不到相符的欄位JSON，會COPY嘗試載入NULL資料欄。

如果COPY嘗試NULL將指派給定義為 NOT 的欄NULL，則COPY命令會失敗。

COPY 會將JSON來源資料中的資料元素映射到目標資料表中的資料欄。它會將來源名稱值對中的物件金鑰 (或名稱) 比對目標資料表中的欄名稱來達成此目標。

請參閱每個 json_option 值的下列詳細資訊：

'auto'

使用此選項，比對會區分大小寫。Amazon Redshift 資料表中的資料欄名稱一律小寫，因此當您使用 'auto'選項時，相符JSON的欄位名稱也必須小寫。

'auto ignorecase'

使用此選項，比對不會區分大小寫。Amazon Redshift 資料表中的資料欄名稱一律為小寫，因此當您使用 'auto ignorecase'選項時，對應的JSON欄位名稱可以是小寫、大寫或混合大小寫。

's3://jsonpaths_file'

使用此選項， COPY會使用具名JSONPaths檔案，將JSON來源資料中的資料元素映射至目標資料表中的資料欄。s3://jsonpaths_file 引數必須是明確參考單一檔案的 Amazon S3 物件金鑰。例如 's3://amzn-s3-demo-bucket/jsonpaths.txt'。引數不能是索引鍵字首。如需使用 JSONPaths 檔案的詳細資訊，請參閱 JSONPaths 檔案。

在某些情況下，由 jsonpaths_file 指定的檔案具有與 copy_from_s3_objectpath 為資料檔指定的路徑相同的字首。如果是這樣，會將JSONPaths檔案COPY讀取為資料檔案並傳回錯誤。例如，假設資料檔案使用物件路徑，s3://amzn-s3-demo-bucket/my_data.json且JSONPaths檔案為 s3://amzn-s3-demo-bucket/my_data.jsonpaths。在此情況下，會COPY嘗試將載入my_data.jsonpaths為資料檔案。

'noshred'

使用此選項時，Amazon Redshift 不會在載入JSON文件時將JSON結構的屬性分割為多個資料欄。

JSON 資料檔案

JSON 資料檔案包含一組物件或陣列。COPY 會將每個JSON物件或陣列載入目標資料表中的一列。對應至資料列的每個物件或陣列都必須是獨立的根層級結構；也就是說，它不得是另一個JSON結構的成員。

JSON 物件的開頭和結尾為 braces （ { } ），並包含未排序的名稱值對集合。每一對名稱和值以冒號分隔，而配對以逗號分隔。根據預設，名稱值對中的物件金鑰 (或名稱) 必須符合資料表中相應欄的名稱。Amazon Redshift 資料表中的資料欄名稱一律為小寫，因此相符JSON的欄位名稱索引鍵也必須為小寫。如果您的資料欄名稱和JSON索引鍵不相符，請使用將資料欄JSONPaths 檔案明確對應至索引鍵。

JSON 物件中的順序並不重要。不符合欄名稱的任何名稱會被忽略。下列顯示簡單JSON物件的結構。


{
  "column1": "value1",
  "column2": value2,
  "notacolumn" : "ignore this value"
}

JSON 陣列以括號（【】）開頭和結尾，並包含以逗號分隔的有序值集合。如果您的資料檔案使用陣列，您必須指定一個JSONPaths檔案，將值與資料欄比對。下列顯示簡單JSON陣列的結構。


["value1", value2]

JSON 必須格式良好。例如，不能以逗號或其他任何字元 (空格除外) 來分隔物件或陣列。必須以雙引號字元括住字串。引號字元必須是簡單引號 (0x22)，而不是斜向或「智慧型」引號。

單一JSON物件或陣列的大小上限為 4 MB，包括支架或括號。這不同於資料列大小上限。如果超過單一JSON物件或陣列的大小上限，即使產生的資料列大小小於 4 MB 的資料列大小限制，COPY命令也會失敗。

在計算列大小時，Amazon Redshift 會在內部將縱線字元 ( | ) 計算兩次。如果輸入資料包含非常多的縱線字元，即使物件小於 4 MB，資料列大小仍可能超過 4 MB。

COPY \n會以新行字元載入，並以\t標籤字元載入。若要載入反斜線，請加上反斜線 ( \\ ) 來逸出。

COPY 會搜尋格式良好、有效JSON物件或陣列的指定JSON來源。如果在尋找可用JSON結構之前或在有效JSON物件或陣列之間COPY遇到任何非空格字元， COPY會傳回每個執行個體的錯誤。這些錯誤會計入MAXERROR錯誤計數。當錯誤計數等於或超過時MAXERROR， COPY會失敗。

對於每個錯誤，Amazon Redshift 會在 STL_LOAD_ERRORS 系統資料表中記錄資料列。LINE_NUMBER 欄會記錄造成錯誤的JSON物件最後一行。

如果指定 IGNOREHEADER ，會COPY忽略JSON資料中指定的行數。JSON 資料中的新行字元一律會計入IGNOREHEADER計算。

COPY 預設會將空字串載入為空欄位。如果指定 EMPTYASNULL ，會將 CHAR和 VARCHAR 欄位的空字串COPY載入為 NULL。其他資料類型的空白字串，例如 INT一律會載入 NULL。

不支援下列選項JSON：

CSV
DELIMITER
ESCAPE
FILLRECORD
FIXEDWIDTH
IGNOREBLANKLINES
NULL AS
READRATIO
REMOVEQUOTES

如需詳細資訊，請參閱COPY 從JSON格式。如需JSON資料結構的詳細資訊，請前往 https：//www.json.org。

JSONPaths 檔案

如果您從 JSON格式化或 Avro 來源資料載入，則依預設，會將來源資料中的第一層資料元素COPY映射至目標資料表中的資料欄。它會將名稱值對中的每個名稱 (或物件金鑰) 比對目標資料表中的欄名稱來達成此目標。

如果您的資料欄名稱和物件索引鍵不相符，或要映射到資料階層中的更深層，您可以使用JSONPaths檔案將JSON或 Avro 資料元素明確映射到資料欄。JSONPaths 檔案會比對目標資料表或資料欄清單中的資料欄順序，將JSON資料元素映射至資料欄。

JSONPaths 檔案只能包含單一JSON物件（非陣列）。JSON 物件是名稱值對。物件金鑰 (名稱值對中的名稱) 必須是 "jsonpaths"。名稱值對中的值是JSONPath表達式 的陣列。每個JSONPath表達式都參考JSON資料階層或 Avro 結構描述中的單一元素，類似於XPath表達式如何參考XML文件中的元素。如需詳細資訊，請參閱JSONPath 表達式。

若要使用 JSONPaths 檔案，請將 JSON或 AVRO關鍵字新增至 COPY命令。使用以下格式指定JSONPaths檔案的 S3 儲存貯體名稱和物件路徑。


COPY tablename 
FROM 'data_source' 
CREDENTIALS 'credentials-args' 
FORMAT AS { AVRO | JSON } 's3://jsonpaths_file';

s3://jsonpaths_file 值必須是明確參考單一檔案的 Amazon S3 物件金鑰，例如 's3://amzn-s3-demo-bucket/jsonpaths.txt'。它不能是索引鍵字首。

在某些情況下，如果您是從 Amazon S3 載入，則 jsonpaths_file 指定的檔案具有與 copy_from_s3_objectpath 為資料檔指定的路徑相同的字首。如果是這樣，會將JSONPaths檔案COPY讀取為資料檔案並傳回錯誤。例如，假設資料檔案使用物件路徑，s3://amzn-s3-demo-bucket/my_data.json且JSONPaths檔案為 s3://amzn-s3-demo-bucket/my_data.jsonpaths。在此情況下，會COPY嘗試將載入my_data.jsonpaths為資料檔案。

如果金鑰名稱是以外的任何字串"jsonpaths"，則COPY命令不會傳回錯誤，但會忽略 jsonpaths_file，而是使用'auto'引數。

如果發生以下任何情況，COPY命令會失敗：

格式JSON不正確。
有一個以上的JSON物件。
物件外面存在空格以外的任何字元。
陣列元素是空字串或不是字串。

MAXERROR 不適用於 JSONPaths 檔案。

即使已指定 ENCRYPTED選項，也不得加密JSONPaths檔案。

如需詳細資訊，請參閱COPY 從JSON格式。

JSONPath 表達式

JSONPaths 檔案使用JSONPath運算式將資料欄位映射至目標資料欄。每個JSONPath表達式對應至 Amazon Redshift 目標資料表中的一欄。如果使用資料欄清單，則JSONPath陣列元素的順序必須符合目標資料表或資料欄清單中的資料欄順序。

如圖所示，欄位名稱和值都需要雙引號字元。引號字元必須是簡單引號 (0x22)，而不是斜向或「智慧型」引號。

如果在JSON資料中找不到JSONPath運算式所參考的物件元素，會COPY嘗試載入NULL值。如果參考的物件格式不正確，會COPY傳回載入錯誤。

如果在 JSON或 Avro 資料中找不到JSONPath運算式所參考的陣列元素， COPY會失敗並出現下列錯誤：從來源資料中不存在JSONPaths的 Invalid JSONPath format: Not an array or index out of range. 移除任何陣列元素，並確認來源資料中的陣列是否形成良好。

JSONPath 運算式可以使用括號符號或點符號，但您無法混合符號。下列範例使用括號符號顯示JSONPath表達式。


{
    "jsonpaths": [
        "$['venuename']",
        "$['venuecity']",
        "$['venuestate']",
        "$['venueseats']"
    ]
}

下列範例顯示使用點符號的JSONPath表達式。


{
    "jsonpaths": [
        "$.venuename",
        "$.venuecity",
        "$.venuestate",
        "$.venueseats"
    ]
}

在 Amazon Redshift COPY 語法中，JSONPath表達式必須指定 JSON或 Avro 階層式資料結構中單一名稱元素的明確路徑。Amazon Redshift 不支援可能解析為不明確路徑或多個名稱JSONPath元素的任何元素，例如萬用字元或篩選條件表達式。

如需詳細資訊，請參閱COPY 從JSON格式。

JSONPaths 搭配 Avro Data 使用

下列範例示範多個層級的 Avro 結構描述。


{
    "name": "person",
    "type": "record",
    "fields": [
        {"name": "id", "type": "int"},
        {"name": "guid", "type": "string"},
        {"name": "isActive", "type": "boolean"},
        {"name": "age", "type": "int"},
        {"name": "name", "type": "string"},
        {"name": "address", "type": "string"},
        {"name": "latitude", "type": "double"},
        {"name": "longitude", "type": "double"},
        {
            "name": "tags",
            "type": {
                        "type" : "array",
                        "name" : "inner_tags",
                        "items" : "string"
                    }
        },
        {
            "name": "friends",
            "type": {
                        "type" : "array",
                        "name" : "inner_friends",
                        "items" : {
                                    "name" : "friends_record",
                                    "type" : "record",
                                    "fields" : [
                                                 {"name" : "id", "type" : "int"},
                                                 {"name" : "name", "type" : "string"}
                                               ]
                                  }
                    }
        },
        {"name": "randomArrayItem", "type": "string"}
    ]
}

下列範例顯示使用 AvroPath 運算式參考先前結構描述JSONPaths的檔案。


{
    "jsonpaths": [
        "$.id",
        "$.guid",
        "$.address",
        "$.friends[0].id"
    ]
}

此JSONPaths範例包含下列元素：

jsonpaths: 包含運算式的JSON AvroPath物件名稱。
[ … ]: 括號會括住包含路徑元素的JSON陣列。
$: 貨幣符號表示 Avro 結構描述中的根元素，即 "fields" 陣列。
"$.id",: AvroPath 表達式的目標。在此例子中，目標是 "fields" 陣列中名稱為 "id" 的元素。表達式以逗號分隔。
"$.friends[0].id": 方括號表示陣列索引。JSONPath 運算式使用以零為基礎的索引，因此此運算式參考"friends"陣列中名稱為的第一個元素"id"。

Avro 結構描述語法需要使用內部欄位來定義記錄和陣列資料類型的結構。 AvroPath 運算式會忽略內部欄位。例如，欄位 "friends" 定義名為 "inner_friends" 的陣列，此陣列接著定義名為 "friends_record" 的記錄。參考欄位的 AvroPath 表達式"id"可以忽略額外的欄位，以直接參考目標欄位。下列 AvroPath 表達式參考屬於 "friends"陣列的兩個欄位。


"$.friends[0].id"
"$.friends[0].name"

單欄資料格式參數

除了標準資料格式之外， COPY還支援COPY來自 Amazon S3 的下列資料欄資料格式。COPY 具有特定限制，支援資料欄格式。如需詳細資訊，請參閱COPY 從資料欄資料格式。

ORC: 從使用 Optimized Row Columnar （ORC）檔案格式的檔案中載入資料。
PARQUET: 從採用 Parquet 檔案格式的檔案載入資料。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

欄映射選項

檔案壓縮參數