在仔細考慮之後，我們決定停止 Amazon Kinesis Data Analytics for SQL 應用程式：
1. 從 **2025 年 9 月 1 日起，**我們不會為 Amazon Kinesis Data Analytics for SQL 應用程式提供任何錯誤修正，因為考慮到即將終止，我們將對其提供有限的支援。
2. 從 **2025 年 10 月 15 日起，**您將無法建立新的 Kinesis Data Analytics for SQL 應用程式。
3. 我們將自 **2026 年 1 月 27** 日起刪除您的應用程式。您將無法啟動或操作 Amazon Kinesis Data Analytics for SQL 應用程式。從那時起，Amazon Kinesis Data Analytics for SQL 將不再提供支援。如需詳細資訊，請參閱[Amazon Kinesis Data Analytics for SQL 應用程式終止](discontinuation.md)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 將串流來源元素映射至 SQL 輸入資料欄
**注意**
2023 年 9 月 12 日之後，如果尚未使用 Kinesis Data Analytics for SQL，您將無法使用 Kinesis Data Firehose 做為建立新應用程式的來源。如需詳細資訊，請參閱[限制](https://docs.aws.amazon.com//kinesisanalytics/latest/dev/limits.html)。
透過 Amazon Kinesis Data Analytics，您可以使用標準 SQL 來處理和分析 JSON 或 CSV 格式的串流資料。
+ 若要處理和分析串流 CSV 資料，請為輸入串流的資料欄指派欄名稱和資料類型。您的應用程式會依序從每個資料欄定義的輸入串流匯入一個資料欄。
您不必在應用程式輸入串流中包含所有資料欄，但無法略過來源串流中的資料欄。例如，您可以從包含五個元素的輸入串流匯入前三個資料欄，但不能只匯入欄 1、2 和 4。
+ 若要處理和分析串流 JSON 資料，您可以使用 JSONPath 表達式，將 JSON 元素從串流來源映射至輸入串流的 SQL 資料欄。如需搭配 Amazon Kinesis Data Analytics 使用 JSONPath 的詳細資訊，請參閱 [使用 JSONPath](about-json-path.md)。在 SQL 表中的資料欄具有從 JSON 類型映射的資料類型。關於支援的資料類型，請參閱[資料類型](https://docs.aws.amazon.com/kinesisanalytics/latest/sqlref/sql-reference-data-types.html)。如需將 JSON 資料轉換為 SQL 資料的詳細資訊，請參閱 [將 JSON 資料類型映射到 SQL 資料類型](#sch-mapping-datatypes)。
如需如何配置輸入串流的詳細資訊，請參閱 [設定應用程式輸入](how-it-works-input.md)。
## 將 JSON 資料映射至 SQL 資料欄
您可以使用 AWS 管理主控台 或 Kinesis Data Analytics API 將 JSON 元素映射至輸入資料欄。
+ 若要使用主控台將元素映射至資料欄，請參閱 [使用結構描述編輯器](console-summary-edit-schema.md)。
+ 若要使用 Kinesis Data Analytics API 將元素映射至資料欄，請參閱下節。
若要將 JSON 元素映射至應用程式內輸入串流的資料欄，您需要每個資料欄的結構描述，且其中須包含下列資訊：
+ **來源表達式：**識別資料欄資料位置的 JSONPath 表達式。
+ **資料欄名稱：**SQL 查詢用來參考資料的名稱。
+ **資料類型：**資料欄的 SQL 資料類型。
## 使用 API
若要將串流來源中的元素映射至輸入資料欄，您可以使用 Kinesis Data Analytics API [CreateApplication](API_CreateApplication.md) 動作。如要建立應用程式內串流，您必須指定一個結構描述，以將資料轉換為 SQL 中使用的架構化版本。[CreateApplication](API_CreateApplication.md) 動作可以設定您的應用程式，以從單一串流來源接收輸入。若要將 JSON 元素或 CSV 資料欄映射至 SQL 資料欄，請在 [SourceSchema](API_SourceSchema.md) `RecordColumns` 陣列中建立 [RecordColumn](API_RecordColumn.md) 物件。[RecordColumn](API_RecordColumn.md) 物件包含以下結構描述：
```
{
"Mapping": "String",
"Name": "String",
"SqlType": "String"
}
```
[RecordColumn](API_RecordColumn.md) 物件中的欄位具有下列值：
+ `Mapping`：識別輸入串流記錄資料位置的 JSONPath 表達式。CSV 格式的來源串流輸入結構描述不存在此值。
+ `Name`：應用程式內 SQL 資料串流中的資料欄名稱。
+ `SqlType`：應用程式內 SQL 資料串流中資料的類型。
### JSON 輸入結構描述範例
下列範例會示範 JSON 結構描述 `InputSchema` 值的格式。
```
"InputSchema": {
"RecordColumns": [
{
"SqlType": "VARCHAR(4)",
"Name": "TICKER_SYMBOL",
"Mapping": "$.TICKER_SYMBOL"
},
{
"SqlType": "VARCHAR(16)",
"Name": "SECTOR",
"Mapping": "$.SECTOR"
},
{
"SqlType": "TINYINT",
"Name": "CHANGE",
"Mapping": "$.CHANGE"
},
{
"SqlType": "DECIMAL(5,2)",
"Name": "PRICE",
"Mapping": "$.PRICE"
}
],
"RecordFormat": {
"MappingParameters": {
"JSONMappingParameters": {
"RecordRowPath": "$"
}
},
"RecordFormatType": "JSON"
},
"RecordEncoding": "UTF-8"
}
```
### CSV 輸入結構描述範例
下列範例會示範使用逗號分隔值 (CSV) 格式的結構描述 `InputSchema` 值格式。
```
"InputSchema": {
"RecordColumns": [
{
"SqlType": "VARCHAR(16)",
"Name": "LastName"
},
{
"SqlType": "VARCHAR(16)",
"Name": "FirstName"
},
{
"SqlType": "INTEGER",
"Name": "CustomerId"
}
],
"RecordFormat": {
"MappingParameters": {
"CSVMappingParameters": {
"RecordColumnDelimiter": ",",
"RecordRowDelimiter": "\n"
}
},
"RecordFormatType": "CSV"
},
"RecordEncoding": "UTF-8"
}
```
## 將 JSON 資料類型映射到 SQL 資料類型
JSON 資料類型轉換為相應的 SQL 資料類型，根據的是應用程式之輸入結構描述。如需支援之 SQL 資料類型的詳細資訊，請參閱[資料類型](https://docs.aws.amazon.com/kinesisanalytics/latest/sqlref/sql-reference-data-types.html)。Amazon Kinesis Data Analytics 會根據下列規則將 JSON 資料類型轉換為 SQL 資料類型。
### Null 常值
JSON 輸入串流中的 null 常值 (也就是 `"City":null`) 會轉換為 SQL null，不論目的地資料類型為何。
### 布林常值。
JSON 輸入串流中的布林常值 (也就是 `"Contacted":true`) 會轉換為 SQL 資料，如下所示：
+ 數字 (DECIMAL、INT 等)：`true` 轉換為 1；`false` 轉換為 0。
+ 二進制 (BINARY 或 VARBINARY)：
+ `true`：結果具有最低位元組，並清除剩餘位元數。
+ `false`：結果已清除所有位元數。
轉換為 VARBINARY 會產生 1 個位元的長度值。
+ 布林值：轉換為相應的 SQL 布林值。
+ 字元 (CHAR 或 VARCHAR)：轉換為對應的字串值 (`true` 或 `false`)。該值被截斷以適合欄位的長度。
+ 日期時間 (DATE、TIME 或 TIMESTAMP)：轉換失敗，強制錯誤會寫入錯誤串流。
### Number
JSON 輸入串流中的常值 (也就是 `"CustomerId":67321`) 會轉換為 SQL 資料，如下所示：
+ 數字 (DECIMAL、INT 等)：直接轉換。如果轉換後的值超過目標資料類型 (也就是轉換 `123.4` 為 INT) 的大小或精確度，則轉換會失敗，並將強制錯誤寫入錯誤串流。
+ 二進位 (BINARY 或 VARBINARY)：轉換失敗，強制錯誤會寫入錯誤串流。
+ 布林值：
+ `0`：轉換為 `false`。
+ 所有其他數字：轉換為 `true`。
+ 字符（CHAR 或 VARCHAR）：轉換為數字的字符串表示。
+ 日期時間 (DATE、TIME 或 TIMESTAMP)：轉換失敗，強制錯誤會寫入錯誤串流。
### String
JSON 輸入串流中的字串值 (也就是 `"CustomerName":"John Doe"`) 會轉換為 SQL 資料，如下所示：
+ 數字 (DECIMAL、INT 等)：Amazon Kinesis Data Analytics 會嘗試將值轉換為目標資料類型。如果無法轉換值，則轉換會失敗，並且會將強制錯誤寫入錯誤資料流。
+ 二進位 (BINARY 或 VARBINARY)：如果來源字串是有效的二進位常值 (也就是 `X'3F67A23A'`，具有偶數 f)，該值會轉換為目標資料類型。否則，轉換會失敗，並將強制錯誤寫入錯誤串流。
+ 布林值：如果來源字串為 `"true"`，則會轉換為 `true`。此比較不區分大小寫。否則，會轉換為 `false`。
+ 字元 (CHAR 或 VARCHAR)：轉換為輸入的字串值。如果值長於目標資料類型，則會截斷該值，且不會將錯誤寫入錯誤串流。
+ 日期時間 (DATE、TIME 或 TIMESTAMP)：如果來源字串的格式可轉換為目標值，則會轉換該值。否則，轉換會失敗，並將強制錯誤寫入錯誤串流。
有效的日期時間格式包括：
+ "1992-02-14"
+ "1992-02-14 18:35:44.0"
### 物件的陣列
JSON 輸入流中的陣列或物件轉換為 SQL 資料，如下所示：
+ 字元 (CHAR 或 VARCHAR)：轉換為陣列或物件的來源文字。請參閱 [存取陣列](about-json-path.md#about-json-path-arrays)。
+ 其他所有資料類型：轉換失敗，並將強制錯誤寫入錯誤串流。
如需 JSON 陣列的範例，請參閱 [使用 JSONPath](about-json-path.md)。
## 相關主題
+ [設定應用程式輸入](how-it-works-input.md)
+ [資料類型](https://docs.aws.amazon.com/kinesisanalytics/latest/sqlref/sql-reference-data-types.html)
+ [使用結構描述編輯器](console-summary-edit-schema.md)
+ [CreateApplication](API_CreateApplication.md)
+ [RecordColumn](API_RecordColumn.md)
+ [SourceSchema](API_SourceSchema.md)