기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 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 ... ``` **입력** + **source**(필수) - **단일** 객체에 대한 Amazon S3 URI입니다. 여러 객체에 대한 Amazon S3 접두사는 지원되지 않습니다. + **format**(필수) - `parquet` 및 `csv`가 지원됩니다. + 지원되는 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는 다음을 반환합니다. + **행** - type:Map + 파일의 각 행. 여기서 키는 열이고 값은 각 열에 있는 데이터입니다. + 속성 액세스()와 같은 각 열의 데이터에 액세스할 수 있습니다`row.col`. ## neptune.read() 모범 사례 Neptune S3 읽기 작업은 메모리 집약적일 수 있습니다. [Amazon Neptune의 인스턴스 유형 선택에 설명된 대로 프로덕션 워크로드에 적합한 인스턴스 유형을](instance-types.md) 사용하세요. `neptune.read()` 요청의 메모리 사용량 및 성능은 파일 크기, 열 수, 행 수, 파일 형식과 같은 다양한 요인의 영향을 받습니다. 구조에 따라 작은 파일(예: CSV 파일 100MB 이하, Parquet 파일 20MB 이하)은 대부분의 프로덕션에 적합한 인스턴스 유형에서 안정적으로 작동할 수 있는 반면, 큰 파일은 작은 인스턴스 유형이 제공할 수 없는 상당한 메모리가 필요할 수 있습니다. 이 기능을 테스트할 때는 작은 파일로 시작하고 인스턴스 크기에 따라 읽기 워크로드를 수용할 수 있도록 점진적으로 확장하는 것이 좋습니다. out-of-memory 예외 또는 인스턴스 재시작으로 이어지는 `neptune.read()` 요청이 있는 경우 파일을 더 작은 청크로 분할하거나 파일 복잡성을 줄이거나 더 큰 인스턴스 유형으로 업그레이드하는 것이 좋습니다. # parquet를 사용한 쿼리 예제 다음 예제 쿼리는 지정된 Parquet 파일의 행 수를 반환합니다. ``` CALL neptune.read( { source: "", format: "parquet" } ) YIELD row RETURN count(row) ``` 다음 코드를 실행 AWS CLI 하여에서 `execute-open-cypher-query` 작업을 사용하여 쿼리 예제를 실행할 수 있습니다. ``` 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에서 읽은 행 간의 교차 제품 때문에 쿼리가 오래 실행됩니다. `CALL` neptune.read로 쿼리를 시작하는 것이 좋습니다. ## 지원되는 Parquet 열 유형 **Parquet 데이터 형식:** + NULL + BOOLEAN + FLOAT + DOUBLE + STRING + 부호 있는 정수: UINT8, UINT16, UINT32, UINT64 + MAP:는 단일 수준만 지원합니다. 중첩을 지원하지 않습니다. + 목록:는 한 수준만 지원합니다. 중첩을 지원하지 않습니다. **Neptune별 데이터 형식:** CSV 형식의 속성 열 헤더와 달리 Parquet 형식의 속성 열 헤더에는 속성 이름만 있으면 되므로 유형 이름이나 카디널리티가 필요하지 않습니다. 그러나 모든 유형, 날짜 유형, dateTime 유형 및 지오메트리 유형을 포함하여 메타데이터에 주석이 필요한 Parquet 형식의 일부 특수 열 유형이 있습니다. 다음 객체는 이러한 특수 유형의 열을 포함하는 파일에 필요한 메타데이터 주석의 예입니다. ``` "metadata": { "anyTypeColumns": ["UserCol1"], "dateTypeColumns": ["UserCol2"], "dateTimeTypeColumns": ["UserCol3"], "geometryTypeColumns": ["UserCol4"] } ``` 다음은 이러한 유형과 관련된 예상 페이로드에 대한 세부 정보입니다. + 열 유형 사용자 열에서 모두 지원됩니다. 모든 유형은 지원하는 다른 모든 유형에 대한 "syntactic sugar" 유형입니다. 사용자 열에 여러 유형이 있는 경우 매우 유용합니다. 모든 유형 값의 페이로드는 다음과 같은 json 문자열 목록입니다. 각 개별 json 문자열에 `{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`값 필드와 유형 필드가 있습니다. 모든 열의 카디널리티 값이 설정됩니다. 즉, 열이 여러 값을 수락할 수 있습니다. + Neptune은 모든 유형에서 Bool(또는 Boolean), Byte, Short, Int, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, Float, Double, Date, dateTime, String 및 Geometry 유형을 지원합니다. + 벡터 유형은 모든 유형에서 지원되지 않습니다. + 중첩 모든 유형은 지원되지 않습니다. 예를 들어 `{"value": {"value": "10", "type": "Int"}, "type": "Any"}`입니다. + 날짜 및 날짜/시간 유형의 열은 사용자 열에서 지원됩니다. 이러한 열의 페이로드는 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 + Geometry 열 유형은 사용자 열에서 지원됩니다. 이러한 열의 페이로드에는 WKT(Well-known text) 형식의 문자열로 제공되는 Point 유형의 지오메트리 프리미티브만 포함되어야 합니다. 예를 들어 POINT(30 10)는 유효한 Geometry 값입니다. ## 샘플 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) ``` 다음 코드를 실행 AWS CLI 하여에서 execute-open-cypher-query 작업을 사용하여 쿼리 예제를 실행할 수 있습니다. ``` 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 속성에 대한 열 헤더를 보여줍니다. ``` age:Int ``` 파일의 각 행마다 해당 위치에 정수가 있거나 비어 있어야 합니다. 문자열 배열은 허용되지만 배열의 문자열은 백슬래시(`;`)를 사용하여 이스케이프되지 않는 한 세미콜론() 문자를 포함할 수 없습니다`\;`. ## 지원되는 CSV 열 유형 + **BOOL(또는 BOOLEAN)** - 허용되는 값: true, false. 부울 필드를 나타냅니다. true 이외의 모든 값은 false로 처리됩니다. + **FLOAT** - 범위: Infinity, INF, -Infinity, -INF 및 NaN(not-a-number 포함한 32비트 IEEE 754 부동 소수점. + **DOUBLE** - 범위: Infinity, INF, -Infinity, -INF 및 NaN(not-a-number 포함한 64비트 IEEE 754 부동 소수점. + **문자열** - + 인용 부호는 선택사항입니다. 쉼표, 줄 바꿈 및 캐리지 리턴 문자는 큰따옴표(")로 묶인 문자열에 포함된 경우 자동으로 이스케이프 처리됩니다. 예: "Hello, World". + 따옴표를 따옴표로 묶으려면 "Hello ""World"" 행의 두 개를 사용하여 따옴표를 이스케이프할 수 있습니다. + 문자열 배열은 허용되지만, 백슬래시(\$1;)를 사용하여 이스케이프되지 않는 한 배열의 문자열에는 세미콜론(;) 문자가 포함될 수 없습니다. + 어레이 안의 문자열을 인용 부호로 묶으려면 전체 어레이를 한 세트의 인용 부호로 묶어야 합니다. 예: "문자열 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\$1127 + 요약: -32768\$132767 + 정수: -2^31 \$1 2^31-1 + Long: -2^63\$12^63-1 **Neptune별 열 유형:** + 열 유형 사용자 열에서 모두 지원됩니다. 모든 유형은 지원하는 다른 모든 유형에 대한 "syntactic sugar" 유형입니다. 사용자 열에 여러 유형이 있는 경우 매우 유용합니다. 모든 유형 값의 페이로드는 다음과 같은 json 문자열 목록입니다. `{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`각 개별 json 문자열에 값 필드와 유형 필드가 있습니다. 모든 유형의 열 헤더는 propertyname:Any입니다. Any 열의 카디널리티 값이 설정됩니다. 즉, 열이 여러 값을 수락할 수 있습니다. + Neptune은 모든 유형에서 Bool(또는 Boolean), Byte, Short, Int, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, Float, Double, Date, dateTime, String 및 Geometry 유형을 지원합니다. + 벡터 유형은 모든 유형에서 지원되지 않습니다. + 중첩 모든 유형은 지원되지 않습니다. 예를 들어 `{"value": {"value": "10", "type": "Int"}, "type": "Any"}`입니다. + Geometry 열 유형은 사용자 열에서 지원됩니다. 이러한 열의 페이로드에는 WKT(Well-known text) 형식의 문자열로 제공되는 Point 유형의 Geometry 프리미티브만 포함되어야 합니다. 예를 들어 POINT(30 10)는 유효한 Geometry 값입니다. ## 샘플 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 데이터베이스의 데이터에 액세스할 수 있는 적절한 권한이 `neptune.read()`있어야 합니다. 읽기 전용 쿼리에는 `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 엔드포인트: **) + Neptune이 Amazon S3와 통신할 수 있으려면 Amazon S3용 게이트웨이 유형 VPC 엔드포인트가 필요합니다. + 쿼리에서 사용자 지정 AWS KMS 암호화를 사용하려면 Neptune이 통신할 수 있도록 하려면에 대한 인터페이스 유형 VPC 엔드포인트 AWS KMS 가 필요합니다 AWS KMS. + 이 엔드포인트를 구성하는 방법에 대한 자세한 지침은 [ Amazon S3 VPC 엔드포인트 생성을 참조하세요](bulk-load-tutorial-IAM.md).