As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # netuno.read () O Neptune suporta `CALL` um `neptune.read` procedimento para ler dados do Amazon S3 e, em seguida, executar uma consulta OpenCypher (ler, inserir, atualizar) usando os dados. O procedimento produz cada linha no arquivo como uma linha de variável de resultado declarada. Ele usa as credenciais do IAM do chamador para acessar os dados no Amazon S3. Consulte [Gerenciando permissões para neptune.read ()](access-graph-opencypher-21-extensions-s3-read-permissions.md) para configurar as permissões. A AWS região do bucket do Amazon S3 deve estar na mesma região em que a instância está localizada. Atualmente, não há suporte para leituras entre regiões. **Sintaxe** ``` CALL neptune.read( { source: "string", format: "parquet/csv", concurrency: 10 } ) YIELD row ... ``` **Entradas** + **source** (obrigatório) - URI do Amazon S3 para um **único** objeto. O prefixo Amazon S3 para vários objetos não é suportado. + **formato** (obrigatório) - `parquet` e `csv` são suportados. + Mais detalhes sobre o formato Parquet compatível podem ser encontrados em[Tipos de coluna de parquet suportados](access-graph-opencypher-21-extensions-s3-read-parquet.md#access-graph-opencypher-21-extensions-s3-read-parquet-column-types). + Para obter mais informações sobre o formato csv compatível, consulte[Formato de carregamento para dados do openCypher](bulk-load-tutorial-format-opencypher.md). + **concorrência** (opcional) - Tipo: número inteiro 0 ou maior. Padrão: 0. Especifica o número de segmentos a serem usados para ler o arquivo. Se o valor for 0, o número máximo de threads permitido pelo recurso será usado. Para Parquet, é recomendável definir vários grupos de linhas. **Saídas** O neptune.read retorna: + **linha** - Tipo: mapa + Cada linha no arquivo, onde as chaves são as colunas e os valores são os dados encontrados em cada coluna. + Você pode acessar os dados de cada coluna como uma propriedade access (`row.col`). ## Melhores práticas para neptune.read () As operações de leitura do Neptune S3 podem consumir muita memória. Use tipos de instância adequados para cargas de trabalho de produção, conforme descrito em [Escolha de tipos de instância para o Amazon Neptune](instance-types.md). O uso da memória e o desempenho das `neptune.read()` solicitações são afetados por vários fatores, como tamanho do arquivo, número de colunas, número de linhas e formato do arquivo. Dependendo da estrutura, arquivos pequenos (por exemplo, arquivos CSV de 100 MB ou menos, arquivos Parquet de 20 MB ou menos) podem funcionar de forma confiável na maioria dos tipos de instância adequados à produção, enquanto arquivos maiores podem exigir memória substancial que tipos de instância menores não podem fornecer. Ao testar esse recurso, é recomendável começar com arquivos pequenos e escalar gradualmente para garantir que sua carga de trabalho de leitura possa ser acomodada pelo tamanho da instância. Se você observar `neptune.read()` solicitações que levam a out-of-memory exceções ou reinicializações de instâncias, considere dividir seus arquivos em partes menores, reduzir a complexidade dos arquivos ou fazer o upgrade para tipos de instância maiores. # Exemplos de consulta usando parquet O exemplo de consulta a seguir retorna o número de linhas em um determinado arquivo Parquet: ``` CALL neptune.read( { source: "", format: "parquet" } ) YIELD row RETURN count(row) ``` Você pode executar o exemplo de consulta usando a `execute-open-cypher-query` operação no AWS CLI executando o seguinte código: ``` 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 ``` Uma consulta pode ser flexível no que ela faz com linhas lidas de um arquivo Parquet. Por exemplo, a consulta a seguir cria um nó com um campo sendo definido para dados encontrados no arquivo Parquet: ``` CALL neptune.read( { source: "", format: "parquet" } ) YIELD row CREATE (n {someField: row.someCol}) RETURN n ``` **Atenção** Não é considerado uma boa prática usar uma grande cláusula produtora de resultados, como `MATCH(n)` antes de uma cláusula. `CALL` Isso levaria a uma consulta de longa duração, devido ao cruzamento entre soluções recebidas de cláusulas anteriores e as linhas lidas por neptune.read. É recomendável iniciar a consulta com `CALL` neptune.read. ## Tipos de coluna de parquet suportados **Tipos de dados de parquet:** + NULL + BOOLEAN + FLOAT + DOUBLE + STRING + NÚMERO INTEIRO ASSINADO: UINT8,, UINT16, UINT32 UINT64 + MAP: suporta apenas um nível. Não suporta aninhado. + LISTA: Suporta apenas um nível. Não suporta aninhado. **Tipos de dados específicos do Neptune:** Ao contrário dos cabeçalhos das colunas de propriedades do formato CSV, os cabeçalhos das colunas de propriedades do formato Parquet precisam ter apenas os nomes das propriedades, portanto, não é necessário ter os nomes dos tipos nem a cardinalidade. No entanto, existem alguns tipos de colunas especiais no formato Parquet que exigem anotações nos metadados, incluindo o tipo Qualquer tipo, o tipo Data, o tipo DateTime e o tipo Geometria. O objeto a seguir é um exemplo da anotação de metadados necessária para arquivos que contêm colunas desses tipos especiais: ``` "metadata": { "anyTypeColumns": ["UserCol1"], "dateTypeColumns": ["UserCol2"], "dateTimeTypeColumns": ["UserCol3"], "geometryTypeColumns": ["UserCol4"] } ``` Abaixo estão os detalhes sobre a carga útil esperada associada a esses tipos: + Um tipo de coluna Qualquer é suportado nas colunas do usuário. Um tipo Qualquer é um tipo de “açúcar sintático” para todos os outros tipos que oferecemos suporte. É extremamente útil se uma coluna de usuário tiver vários tipos. A carga útil de um valor de qualquer tipo é uma lista de strings json da seguinte forma:`{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`, que tem um campo de valor e um campo de tipo em cada string json individual. O valor de cardinalidade de uma coluna Qualquer é definido, o que significa que a coluna pode aceitar vários valores. + O Neptune suporta os seguintes tipos em qualquer tipo: Bool (ou booleano), Byte, Short, Int, Long,,,,, Float, Double UnsignedByte UnsignedShort, Date UnsignedInt UnsignedLong, DateTime, String e Geometry. + O tipo de vetor não é suportado em Qualquer tipo. + Aninhado Qualquer tipo não é suportado. Por exemplo, .`{"value": {"value": "10", "type": "Int"}, "type": "Any"}` + As colunas do tipo Date e Datetime são suportadas nas colunas do usuário. A carga útil dessas colunas deve ser fornecida como strings seguindo o formato XSD ou um dos formatos abaixo: + aaaa-MM-dd + AAA-mm-ddthh:mm + YYYY-MM-ddthh:mm:ss + aaa-mm-ddthh: mm: ssz + aaa-mm-ddthh: mm: ss.sssz + aaaa-mm-ddthh:mm:ss [\$1\$1-] hhmm + aaaa-mm-ddthh:mm:ss.sss [\$1\$1-] hhmm + Um tipo de coluna Geometry é suportado nas colunas do usuário. A carga útil dessas colunas deve conter somente primitivas de geometria do tipo Point, fornecidas como cadeias de caracteres no formato Texto conhecido (WKT). Por exemplo, POINT (30 10) seria um valor de geometria válido. ## Exemplo de saída de parquet Dado um arquivo Parquet como este: ``` 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 | +--------+---------+-------------+----------------------+------------+------------+----------+ ``` Aqui está um exemplo da saída retornada por neptune.read usando a seguinte consulta: ``` 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" } }] } ``` Atualmente, não há como definir um rótulo de nó ou borda em um campo de dados proveniente de um arquivo Parquet. É recomendável particionar as consultas em várias consultas, uma para cada rótulo/tipo. ``` 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) ``` # Exemplos de consulta usando CSV Neste exemplo, a consulta retorna o número de linhas em um determinado arquivo CSV: ``` CALL neptune.read( { source: "", format: "csv" } ) YIELD row RETURN count(row) ``` Você pode executar o exemplo de consulta usando a execute-open-cypher-query operação no AWS CLI executando o seguinte código: ``` 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 ``` Uma consulta pode ser flexível no que ela faz com linhas lidas de um arquivo CSV. Por exemplo, a consulta a seguir cria um nó com um campo definido para dados de um arquivo CSV: ``` CALL neptune.read( { source: "", format: "csv" } ) YIELD row CREATE (n {someField: row.someCol}) RETURN n ``` **Atenção** Não é considerado uma boa prática usar uma grande cláusula produtora de resultados como MATCH (n) antes de uma cláusula CALL. Isso levaria a uma consulta de longa duração devido ao cruzamento entre soluções recebidas de cláusulas anteriores e as linhas lidas por neptune.read. É recomendável iniciar a consulta com CALL neptune.read. ## Cabeçalhos de colunas de propriedade É possível especificar uma coluna (`:`) para uma propriedade usando a sintaxe a seguir. Os nomes dos tipos não diferenciam maiúsculas de minúsculas. Se dois pontos aparecerem no nome de uma propriedade, eles devem ser escapados precedendo-os com uma barra invertida:. `\:` ``` propertyname:type ``` **nota** Espaços, vírgulas, caracteres de retorno e de nova linha não são permitidos nos cabeçalhos de coluna, portanto, os nomes de propriedades não podem incluir esses caracteres. Você pode especificar uma coluna para um tipo de matriz adicionando `[]` para o tipo: ``` propertyname:type[] ``` As propriedades de borda podem ter apenas um único valor e causarão um erro se um tipo de matriz é especificado ou um segundo valor é especificado. O exemplo a seguir mostra o cabeçalho da coluna de uma propriedade chamada age do tipo Int: ``` age:Int ``` Cada linha no arquivo precisa ter um número inteiro nessa posição ou ser deixada em branco. Matrizes de strings são permitidas, mas as strings em uma matriz não podem incluir o caractere ponto e vírgula (`;`), a menos que ele seja escapado usando uma barra invertida (). `\;` ## Tipos de coluna CSV compatíveis + **BOOL (ou BOOLEAN)** - Valores permitidos: verdadeiro, falso. Indica um campo booliano. Qualquer valor diferente de verdadeiro será tratado como falso. + **FLOAT** - Intervalo: ponto flutuante IEEE 754 de 32 bits, incluindo Infinity, INF, -Infinity, -INF e NaN (). not-a-number + Intervalo **DUPLO**: ponto flutuante IEEE 754 de 64 bits, incluindo Infinity, INF, -Infinity, -INF e NaN (). not-a-number + **SEQUÊNCIA** - + Aspas são opcionais. Vírgulas, nova linha e caracteres de retorno de carro escapam automaticamente se forem incluídos em uma string cercada por aspas duplas (“). Exemplo: “Hello, World”. + Para incluir aspas em uma string entre aspas, você pode escapar das aspas usando duas em uma linha: Exemplo: “Hello “" World" "”. + Matrizes de cadeias de caracteres são permitidas, mas as cadeias de caracteres em uma matriz não podem incluir o caractere ponto e vírgula (;), a menos que ele seja escapado usando uma barra invertida (\$1;). + Se desejar usar sequências entre aspas em uma matriz, você deverá colocar a matriz inteira entre um conjunto de aspas. Exemplo: “String one; String 2; String 3". + **DATE, DATETIME** - Os valores de data e hora podem ser fornecidos no formato XSD ou em um dos seguintes formatos: + aaaa-MM-dd + AAA-mm-ddthh:mm + YYYY-MM-ddthh:mm:ss + aaa-mm-ddthh: mm: ssz + aaa-mm-ddthh: mm: ss.sssz + aaaa-mm-ddthh:mm:ss [\$1\$1-] hhmm + aaaa-mm-ddthh:mm:ss.sss [\$1\$1-] hhmm + **NÚMERO INTEIRO ASSINADO** - + Byte: -128 a 127 + Curto: -32768 a 32767 + Int: -2^31 a 2^31-1 + Longo: -2^63 a 2^63-1 **Tipos de coluna específicos para Netuno:** + Um tipo de coluna Qualquer é suportado nas colunas do usuário. Um tipo Qualquer é um tipo de “açúcar sintático” para todos os outros tipos que oferecemos suporte. É extremamente útil se uma coluna de usuário tiver vários tipos. A carga útil de um valor de qualquer tipo é uma lista de strings json da seguinte forma:`{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`, que tem um campo de valor e um campo de tipo em cada string json individual. O cabeçalho da coluna de um tipo Any é propertyName:any. O valor de cardinalidade de uma coluna Qualquer é definido, o que significa que a coluna pode aceitar vários valores. + O Neptune suporta os seguintes tipos em qualquer tipo: Bool (ou booleano), Byte, Short, Int, Long,,,,, Float, Double UnsignedByte UnsignedShort, Date UnsignedInt UnsignedLong, DateTime, String e Geometry. + O tipo de vetor não é suportado em Qualquer tipo. + Aninhado Qualquer tipo não é suportado. Por exemplo, .`{"value": {"value": "10", "type": "Int"}, "type": "Any"}` + Um tipo de coluna Geometry é suportado nas colunas do usuário. A carga útil dessas colunas deve conter somente primitivas de geometria do tipo Point, fornecidas como cadeias de caracteres no formato Texto conhecido (WKT). Por exemplo, POINT (30 10) seria um valor de geometria válido. ## Exemplo de saída CSV Dado o seguinte arquivo 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 ``` Este exemplo mostra a saída retornada por neptune.read usando a seguinte consulta: ``` 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 } }] } ``` Atualmente, não há como definir um rótulo de nó ou borda em um campo de dados proveniente de um arquivo CSV. É recomendável particionar as consultas em várias consultas, uma para cada rótulo/tipo. ``` 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) ``` # Gerenciando permissões para neptune.read () ## Políticas do IAM exigidas Para executar consultas do OpenCypher que usam`neptune.read()`, você deve ter as permissões apropriadas para acessar dados em seu banco de dados Neptune. As consultas somente para leitura exigem a ação. `ReadDataViaQuery` As consultas que modificam dados exigem `WriteDataViaQuery` inserções ou exclusões`DeleteDataViaQuery`. O exemplo abaixo concede todas as três ações no cluster especificado. Além disso, você precisa de permissões para acessar o bucket do S3 que contém seus arquivos de dados. A declaração de política do Neptunes3Access concede as permissões necessárias do S3: + **`s3:ListBucket`**: necessária para verificar a existência do bucket e o conteúdo da lista. + **`s3:GetObject`**: necessário para acessar o objeto especificado para que seu conteúdo possa ser lido para integração às consultas do OpenCypher. Se seu bucket do S3 usa criptografia do lado do servidor com AWS KMS, você também deve conceder permissões de KMS. A KMSAccess declaração de política do NeptuneS3 permite que o Neptune decifre dados e gere chaves de dados ao acessar objetos criptografados do S3. A condição restringe as operações do KMS às solicitações originadas dos serviços do S3 e do RDS em sua região. + **`kms:Decrypt`**: necessário para realizar a descriptografia do objeto criptografado para que seus dados possam ser lidos por Neptune. + **`kms:GenerateDataKey`**: também exigido pela API do S3 usada para recuperar objetos para serem lidos. ``` { "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" ] } } } ``` ## Pré-requisitos importantes Essas permissões e pré-requisitos garantem a integração segura e confiável dos dados do S3 nas consultas do OpenCypher, mantendo os controles de acesso e as medidas de proteção de dados adequados. + **Autenticação do IAM**: esse recurso só é compatível com clusters do Neptune com a autenticação do IAM ativada. Consulte [Protegendo seu banco de dados do Amazon](security.md) Neptune para obter instruções detalhadas sobre como criar e se conectar a clusters habilitados para autenticação do IAM. + **Endpoint VPC:** + um endpoint da VPC do tipo gateway para o Amazon S3 é necessário para permitir que o Neptune se comunique com o Amazon S3. + Para usar AWS KMS criptografia personalizada na consulta, AWS KMS é necessário um endpoint VPC do tipo interface para permitir que o Neptune se comunique com. AWS KMS + Para obter instruções detalhadas sobre como configurar esse endpoint, consulte [Criação do endpoint VPC do Amazon S3](bulk-load-tutorial-IAM.md).