本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# neptune.read()
Neptune 支援從 Amazon S3 `neptune.read`讀取資料，然後使用資料執行 openCypher 查詢 （讀取、插入、更新） `CALL`的程序。程序會將 檔案中的每一列產生為宣告的結果變數列。它使用發起人的 IAM 登入資料來存取 Amazon S3 中的資料。請參閱 [管理 neptune.read() 的許可](access-graph-opencypher-21-extensions-s3-read-permissions.md) 以設定許可。Amazon S3 儲存貯 AWS 體的區域必須位於執行個體所在的相同區域。目前不支援跨區域讀取。
**語法**
```
CALL neptune.read(
{
source: "string",
format: "parquet/csv",
concurrency: 10
}
)
YIELD row
...
```
**輸入**
+ **來源** （必要） - Amazon S3 URI 至**單一**物件。不支援多個物件的 Amazon S3 字首。
+ **格式** （必要） - `csv` 支援 `parquet`和 。
+ 如需支援的 Parquet 格式詳細資訊，請參閱 [支援的 Parquet 資料欄類型](access-graph-opencypher-21-extensions-s3-read-parquet.md#access-graph-opencypher-21-extensions-s3-read-parquet-column-types)。
+ 如需支援的 csv 格式的詳細資訊，請參閱 [openCypher 資料的載入格式](bulk-load-tutorial-format-opencypher.md)。
+ **並行** （選用） - 類型：0 或更大的整數。預設：0. 指定用於讀取檔案的執行緒數目。如果值為 0，則會使用資源允許的執行緒數目上限。對於 Parquet，建議設定為多個資料列群組。
**輸出**
neptune.read 會傳回：
+ **row** - type：Map
+ 檔案中的每一列，其中索引鍵是資料欄，而值是每一欄中找到的資料。
+ 您可以存取每個資料欄的資料，例如屬性存取 (`row.col`)。
## neptune.read() 的最佳實務
Neptune S3 讀取操作可能會耗用記憶體。請使用非常適合生產工作負載的執行個體類型，如[為 Amazon Neptune 選擇執行個體類型](instance-types.md)中所述。
`neptune.read()` 請求的記憶體用量和效能會受到各種因素的影響，例如檔案大小、資料欄數、資料列數和檔案格式。根據結構，小型檔案 （例如，CSV 檔案 100MB 或以下、Parquet 檔案 20MB 或以下） 可能會在大多數適合生產的執行個體類型上可靠運作，而較大的檔案可能需要較小的執行個體類型無法提供的大量記憶體。
測試此功能時，建議從小型檔案開始逐步擴展，以確保您的讀取工作負載可以適應您的執行個體大小。如果您注意到`neptune.read()`請求導致out-of-memory例外狀況或執行個體重新啟動，請考慮將檔案分割成較小的區塊、降低檔案複雜性，或升級至較大的執行個體類型。
# 使用 parquet 查詢範例
下列範例查詢會傳回指定 Parquet 檔案中的資料列數：
```
CALL neptune.read(
{
source: "",
format: "parquet"
}
)
YIELD row
RETURN count(row)
```
您可以使用 中的 `execute-open-cypher-query`操作執行查詢範例， AWS CLI 方法是執行下列程式碼：
```
aws neptunedata execute-open-cypher-query \
--open-cypher-query "CALL neptune.read({source: '', format: 'parquet'}) YIELD row RETURN count(row)" \
--endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182
```
查詢可以靈活地處理從 Parquet 檔案讀取的資料列。例如，下列查詢會建立節點，並將 欄位設定為 Parquet 檔案中找到的資料：
```
CALL neptune.read(
{
source: "",
format: "parquet"
}
)
YIELD row
CREATE (n {someField: row.someCol})
RETURN n
```
**警告**
不像在子句`MATCH(n)`之前一樣，使用大型產生結果的`CALL`子句，不被視為最佳實務。這會導致查詢長時間執行，因為先前子句的傳入解決方案與 neptune.read 讀取的資料列之間存在交叉產品。建議使用 neptune.read `CALL` 啟動查詢。
## 支援的 Parquet 資料欄類型
**Parquet 資料類型：**
+ NULL
+ BOOLEAN
+ FLOAT
+ DOUBLE
+ STRING
+ 帶正負號整數：UINT8, UINT16, UINT32, UINT64
+ MAP：僅支援單一層級。不支援巢狀。
+ LIST：僅支援單一層級。不支援巢狀。
**Neptune 特定的資料類型：**
與 CSV 格式的屬性欄標頭不同，Parquet 格式的屬性欄標頭只需要具有屬性名稱，因此不需要具有類型名稱或基數。
不過，Parquet 格式的某些特殊資料欄類型需要中繼資料中的註釋，包括任意類型、日期類型、dateTime類型和幾何類型。下列 物件是包含這些特殊類型資料欄之檔案的必要中繼資料註釋範例：
```
"metadata": {
"anyTypeColumns": ["UserCol1"],
"dateTypeColumns": ["UserCol2"],
"dateTimeTypeColumns": ["UserCol3"],
"geometryTypeColumns": ["UserCol4"]
}
```
以下是與這些類型相關聯的預期承載詳細資訊：
+ 資料欄類型 使用者資料欄中支援任何 。任何類型都是我們支援的所有其他類型的「語法糖」類型。如果使用者資料欄包含多種類型，這非常有用。Any type value 的承載是 json 字串的清單，如下所示：`{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`，每個個別 json 字串中都有一個值欄位和一個類型欄位。已設定任何資料欄的基數值，表示該資料欄可接受多個值。
+ Neptune 支援任何類型的下列類型：Bool （或布林值）、Byte、Short、Int、Long、UnsignedByte、UnsignedShort、UnsignedInt、UnsignedLong、Float、Double、Date、dateTime、String 和 Geometry。
+ 任何類型都不支援向量類型。
+ 巢狀 不支援任何類型。例如 `{"value": {"value": "10", "type": "Int"}, "type": "Any"}`。
+ 使用者資料欄中支援類型為 Date 和 Datetime 的資料欄。這些資料欄的承載必須以 XSD 格式或下列其中一種格式的字串提供：
+ yyyy-MM-dd
+ yyyy-MM-ddTHH：mm
+ yyyy-MM-ddTHH：mm：ss
+ yyyy-MM-ddTHH：mm：ssZ
+ yyyy-MM-ddTHH：mm：ss.SSSZ
+ yyyy-MM-ddTHH：mm：ss【\$1\$1-】hhmm
+ yyyy-MM-ddTHH：mm：ss.SSS【\$1\$1-】hhmm
+ 使用者資料欄中支援幾何資料欄類型。這些資料欄的承載只能包含 Point 類型的幾何基本概念，以已知文字 (WKT) 格式的字串提供。例如，POINT (30 10) 是有效的幾何值。
## 範例 parquet 輸出
指定像這樣的 Parquet 檔案：
```
Parquet Type:
int8 int16 int32 int64 float double string
+--------+---------+-------------+----------------------+------------+------------+----------+
| Byte | Short | Int | Long | Float | Double | String |
|--------+---------+-------------+----------------------+------------+------------+----------|
| -128 | -32768 | -2147483648 | -9223372036854775808 | 1.23456 | 1.23457 | first |
| 127 | 32767 | 2147483647 | 9223372036854775807 | nan | nan | second |
| 0 | 0 | 0 | 0 | -inf | -inf | third |
| 0 | 0 | 0 | 0 | inf | inf | fourth |
+--------+---------+-------------+----------------------+------------+------------+----------+
```
以下是 neptune.read 使用以下查詢傳回的輸出範例：
```
aws neptunedata execute-open-cypher-query \
--open-cypher-query "CALL neptune.read({source: '', format: 'parquet'}) YIELD row RETURN row" \
--endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182
```
```
{
"results": [{
"row": {
"Float": 1.23456,
"Byte": -128,
"Int": -2147483648,
"Long": -9223372036854775808,
"String": "first",
"Short": -32768,
"Double": 1.2345678899999999
}
}, {
"row": {
"Float": "NaN",
"Byte": 127,
"Int": 2147483647,
"Long": 9223372036854775807,
"String": "second",
"Short": 32767,
"Double": "NaN"
}
}, {
"row": {
"Float": "-INF",
"Byte": 0,
"Int": 0,
"Long": 0,
"String": "third",
"Short": 0,
"Double": "-INF"
}
}, {
"row": {
"Float": "INF",
"Byte": 0,
"Int": 0,
"Long": 0,
"String": "fourth",
"Short": 0,
"Double": "INF"
}
}]
}
```
目前，無法將節點或邊緣標籤設定為來自 Parquet 檔案的資料欄位。建議您將查詢分割成多個查詢，每個標籤/類型各一個。
```
CALL neptune.read({source: '', format: 'parquet'})
YIELD row
WHERE row.`~label` = 'airport'
CREATE (n:airport)
CALL neptune.read({source: '', format: 'parquet'})
YIELD row
WHERE row.`~label` = 'country'
CREATE (n:country)
```
# 使用 CSV 查詢範例
在此範例中，查詢會傳回指定 CSV 檔案中的資料列數：
```
CALL neptune.read(
{
source: "",
format: "csv"
}
)
YIELD row
RETURN count(row)
```
您可以執行下列程式碼，在 中使用 execute-open-cypher-query 操作 AWS CLI 來執行查詢範例：
```
aws neptunedata execute-open-cypher-query \
--open-cypher-query "CALL neptune.read({source: '', format: 'csv'}) YIELD row RETURN count(row)" \
--endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182
```
查詢可以靈活地處理從 CSV 檔案讀取的資料列。例如，下列查詢會建立將欄位設定為 CSV 檔案資料的節點：
```
CALL neptune.read(
{
source: "",
format: "csv"
}
)
YIELD row
CREATE (n {someField: row.someCol})
RETURN n
```
**警告**
不認為良好的做法是在 CALL 子句之前使用大型產生結果的子句，例如 MATCH(n)。這會導致查詢長時間執行，因為先前 子句的傳入解決方案與 neptune.read 讀取的資料列之間存在交叉產品。建議使用 CALL neptune.read 啟動查詢。
## 屬性欄標頭
您可以使用以下語法指定屬性欄 (`:`)。類型名稱不區分大小寫。如果冒號出現在屬性名稱中，則必須在冒號前面加上反斜線來逸出：`\:`。
```
propertyname:type
```
**注意**
欄標頭中不允許空格、逗號、換行字元和換行字元，因此屬性名稱不能包含這些字元。
您可以透過將 `[]` 新增至類型，來為陣列類型指定一個欄：
```
propertyname:type[]
```
邊緣屬性只能有一個值，如果指定了陣列類型或指定了第二個值，會導致錯誤。下列範例顯示名稱為 Int 類型存留期之屬性的資料欄標頭：
```
age:Int
```
檔案中的每個資料列在該位置都必須有一個整數或保留空白。允許字串陣列，但陣列中的字串不能包含分號 (`;`) 字元，除非使用反斜線 () 逸出`\;`。
## 支援的 CSV 資料欄類型
+ **BOOL （或 BOOLEAN)** - 允許的值：true、false。表示布林值欄位。非 true 的任何值都會被視為 false。
+ **FLOAT** - 範圍：32 位元 IEEE 754 浮點，包括 Infinity、INF、-Infinity、-INF 和 NaN not-a-number)。
+ **DOUBLE** - 範圍：64 位元 IEEE 754 浮點，包括 Infinity、INF、-Infinity、-INF 和 NaN not-a-number)。
+ **STRING** -
+ 引號是選用的。如果逗號、換行和換行字元包含在以雙引號 (") 括住的字串中，則會自動逸出。範例：「Hello， World」。
+ 若要在引號字串中包含引號，您可以連續使用兩個 來逸出引號：範例：「Hello ""World""」。
+ 允許字串陣列，但陣列中的字串不能包含分號 (；) 字元，除非使用反斜線 (\$1；) 逸出。
+ 如果您要使用引號包圍陣列中的字串，您必須以一組引號包圍整個陣列。範例：「字串一；字串 2；字串 3」。
+ **DATE、DATETIME** - 日期時間值可以 XSD 格式或下列其中一種格式提供：
+ yyyy-MM-dd
+ yyyy-MM-ddTHH：mm
+ yyyy-MM-ddTHH：mm：ss
+ yyyy-MM-ddTHH：mm：ssZ
+ yyyy-MM-ddTHH：mm：ss.SSSZ
+ yyyy-MM-ddTHH：mm：ss【\$1\$1-】hhmm
+ yyyy-MM-ddTHH：mm：ss.SSS【\$1\$1-】hhmm
+ **已簽署整數** -
+ 位元組：-128 到 127
+ 短：-32768 至 32767
+ 整數：-2^31 到 2^31-1
+ 長：-2^63 到 2^63-1
**Neptune 特定的欄類型：**
+ 資料欄類型 使用者資料欄中支援任何 。任何類型都是我們支援的所有其他類型的「語法糖」類型。如果使用者資料欄包含多種類型，這非常有用。Any type value 的承載是 json 字串的清單，如下所示：`{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`，每個個別 json 字串中都有一個值欄位和一個類型欄位。Any 類型的資料欄標頭是 propertyname：Any。已設定任何資料欄的基數值，表示該資料欄可接受多個值。
+ Neptune 支援任何類型的下列類型：Bool （或布林值）、Byte、Short、Int、Long、UnsignedByte、UnsignedShort、UnsignedInt、UnsignedLong、Float、Double、Date、dateTime、String 和 Geometry。
+ 任何類型都不支援向量類型。
+ 巢狀 不支援任何類型。例如 `{"value": {"value": "10", "type": "Int"}, "type": "Any"}`。
+ 使用者資料欄中支援幾何資料欄類型。這些資料欄的承載只能包含 Point 類型的幾何基本概念，以已知文字 (WKT) 格式的字串提供。例如，POINT (30 10) 是有效的幾何值。
## CSV 輸出範例
根據下列 CSV 檔案：
```
colA:byte,colB:short,colC:int,colD:long,colE:float,colF:double,colG:string
-128,-32768,-2147483648,-9223372036854775808,1.23456,1.23457,first
127,32767,2147483647,9223372036854775807,nan,nan,second
0,0,0,0,-inf,-inf,third
0,0,0,0,inf,inf,fourth
```
此範例顯示 neptune.read 使用以下查詢傳回的輸出：
```
aws neptunedata execute-open-cypher-query \
--open-cypher-query "CALL neptune.read({source: '', format: 'csv'}) YIELD row RETURN row" \
--endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182
```
```
{
"results": [{
"row": {
"colD": -9223372036854775808,
"colC": -2147483648,
"colE": 1.23456,
"colB": -32768,
"colF": 1.2345699999999999,
"colG": "first",
"colA": -128
}
}, {
"row": {
"colD": 9223372036854775807,
"colC": 2147483647,
"colE": "NaN",
"colB": 32767,
"colF": "NaN",
"colG": "second",
"colA": 127
}
}, {
"row": {
"colD": 0,
"colC": 0,
"colE": "-INF",
"colB": 0,
"colF": "-INF",
"colG": "third",
"colA": 0
}
}, {
"row": {
"colD": 0,
"colC": 0,
"colE": "INF",
"colB": 0,
"colF": "INF",
"colG": "fourth",
"colA": 0
}
}]
}
```
目前，無法將節點或邊緣標籤設定為來自 CSV 檔案的資料欄位。建議您將查詢分割成多個查詢，每個標籤/類型各一個。
```
CALL neptune.read({source: '', format: 'csv'})
YIELD row
WHERE row.`~label` = 'airport'
CREATE (n:airport)
CALL neptune.read({source: '', format: 'csv'})
YIELD row
WHERE row.`~label` = 'country'
CREATE (n:country)
```
# 管理 neptune.read() 的許可
## 必要的 IAM 政策
若要執行使用 的 openCypher 查詢`neptune.read()`，您必須具有適當的許可才能存取 Neptune 資料庫中的資料。唯讀查詢需要 `ReadDataViaQuery`動作。修改資料`WriteDataViaQuery`需要插入或刪除`DeleteDataViaQuery`的查詢。以下範例會授予指定叢集上所有三個動作。
此外，您需要許可才能存取包含資料檔案的 S3 儲存貯體。NeptuneS3Access 政策陳述式會授予必要的 S3 許可：
+ **`s3:ListBucket`**：驗證儲存貯體存在並列出內容時需要。
+ **`s3:GetObject`**：需要存取指定的物件，才能讀取其內容以整合到 openCypher 查詢。
如果您的 S3 儲存貯體搭配 伺服器端加密使用 AWS KMS，您還必須授予 KMS 許可。NeptuneS3KMSAccess 政策陳述式允許 Neptune 在存取加密的 S3 物件時解密資料並產生資料金鑰。條件會將 KMS 操作限制為來自您區域中 S3 和 RDS 服務的請求。
+ **`kms:Decrypt`**：執行加密物件的解密時需要，以便 Neptune 可以讀取其資料。
+ **`kms:GenerateDataKey`**：S3 API 也需要用來擷取要讀取的物件。
```
{
"Sid": "NeptuneQueryAccess",
"Effect": "Allow",
"Action": [
"neptune-db:ReadDataViaQuery",
"neptune-db:WriteDataViaQuery",
"neptune-db:DeleteDataViaQuery"
],
"Resource": "arn:aws:neptune-db:::/*"
},
{
"Sid": "NeptuneS3Access",
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::neptune-read-bucket",
"arn:aws:s3:::neptune-read-bucket/*"
]
},
{
"Sid": "NeptuneS3KMSAccess",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:::key/",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"s3..amazonaws.com",
"rds..amazonaws.com"
]
}
}
}
```
## 重要先決條件
這些許可和先決條件可確保將 S3 資料安全可靠地整合至 openCypher 查詢，同時維持適當的存取控制和資料保護措施。
+ **IAM 身分驗證**：此功能僅支援已啟用 IAM 身分驗證的 Neptune 叢集。如需如何建立和連線至啟用 IAM 身分驗證之叢集的詳細說明，請參閱[保護您的 Amazon Neptune 資料庫](security.md)。
+ **VPC 端點**：
+ 需要 Amazon S3 的閘道類型 VPC 端點，才能允許 Neptune 與 Amazon S3 通訊。
+ 若要在查詢中使用自訂 AWS KMS 加密， AWS KMS 需要 的界面類型 VPC 端點，才能允許 Neptune 與 通訊 AWS KMS。
+ 如需如何設定此端點的詳細說明，請參閱[建立 Amazon S3 VPC 端點](bulk-load-tutorial-IAM.md)。