Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # neptune.read () Neptune prend en charge une `CALL` procédure `neptune.read` permettant de lire les données d'Amazon S3, puis d'exécuter une requête OpenCypher (lecture, insertion, mise à jour) à l'aide de ces données. La procédure génère chaque ligne du fichier en tant que ligne de variable de résultat déclarée. Il utilise les informations d'identification IAM de l'appelant pour accéder aux données dans Amazon S3. Consultez [Gérer les autorisations pour neptune.read ()](access-graph-opencypher-21-extensions-s3-read-permissions.md) pour configurer les autorisations. La AWS région du compartiment Amazon S3 doit se trouver dans la même région que celle où se trouve l'instance. Actuellement, les lectures entre régions ne sont pas prises en charge. **Syntaxe** ``` CALL neptune.read( { source: "string", format: "parquet/csv", concurrency: 10 } ) YIELD row ... ``` **Inputs** + **source** (obligatoire) - URI Amazon S3 vers un **seul** objet. Le préfixe Amazon S3 désignant plusieurs objets n'est pas pris en charge. + **format** (obligatoire) - `parquet` et `csv` sont pris en charge. + Vous trouverez plus de détails sur le format Parquet pris en charge dans[Types de colonnes de parquet pris en charge](access-graph-opencypher-21-extensions-s3-read-parquet.md#access-graph-opencypher-21-extensions-s3-read-parquet-column-types). + Pour plus d'informations sur le format csv pris en charge, consultez[Format de chargement des données openCypher](bulk-load-tutorial-format-opencypher.md). + **simultanéité** (facultatif) - Type : entier égal ou supérieur à 0. Valeur par défaut : 0. Spécifie le nombre de threads à utiliser pour lire le fichier. Si la valeur est 0, le nombre maximum de threads autorisés par la ressource sera utilisé. Pour le parquet, il est recommandé de définir un certain nombre de groupes de lignes. **Sorties** Le fichier neptune.read renvoie : + **ligne** - Type : carte + Chaque ligne du fichier, où les clés sont les colonnes et les valeurs sont les données présentes dans chaque colonne. + Vous pouvez accéder aux données de chaque colonne sous la forme d'un accès aux propriétés (`row.col`). ## Meilleures pratiques pour neptune.read () Les opérations de lecture de Neptune S3 peuvent être gourmandes en mémoire. Veuillez utiliser des types d'instance adaptés aux charges de travail de production, comme indiqué dans la section [Choix des types d'instance pour Amazon Neptune](instance-types.md). L'utilisation de la mémoire et les performances des `neptune.read()` requêtes sont affectées par divers facteurs tels que la taille du fichier, le nombre de colonnes, le nombre de lignes et le format du fichier. Selon la structure, les petits fichiers (par exemple, les fichiers CSV de 100 Mo ou moins, les fichiers Parquet de 20 Mo ou moins) peuvent fonctionner de manière fiable sur la plupart des types d'instances adaptés à la production, tandis que les fichiers plus volumineux peuvent nécessiter une mémoire importante que les types d'instances plus petits ne peuvent pas fournir. Lorsque vous testez cette fonctionnalité, il est recommandé de commencer par de petits fichiers et de procéder à une mise à l'échelle progressive afin de garantir que votre charge de travail de lecture puisse être adaptée à la taille de votre instance. Si vous remarquez que des `neptune.read()` demandes entraînent out-of-memory des exceptions ou des redémarrages d'instances, envisagez de diviser vos fichiers en plus petits morceaux, de réduire la complexité des fichiers ou de passer à des types d'instances plus importants. # Exemples de requêtes utilisant du parquet L'exemple de requête suivant renvoie le nombre de lignes d'un fichier Parquet donné : ``` CALL neptune.read( { source: "", format: "parquet" } ) YIELD row RETURN count(row) ``` Vous pouvez exécuter l'exemple de requête à l'aide de l'`execute-open-cypher-query`opération décrite dans le en AWS CLI exécutant le code suivant : ``` 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 ``` Une requête peut être flexible quant à l'utilisation des lignes lues à partir d'un fichier Parquet. Par exemple, la requête suivante crée un nœud dont le champ est défini sur la base des données trouvées dans le fichier Parquet : ``` CALL neptune.read( { source: "", format: "parquet" } ) YIELD row CREATE (n {someField: row.someCol}) RETURN n ``` **Avertissement** Il n'est pas considéré comme une bonne pratique d'utiliser une clause volumineuse produisant des résultats comme `MATCH(n)` avant une `CALL` clause. Cela entraînerait une requête de longue durée, en raison d'un produit croisé entre les solutions entrantes issues des clauses précédentes et les lignes lues par neptune.read. Il est recommandé de démarrer la requête avec `CALL` neptune.read. ## Types de colonnes de parquet pris en charge **Types de données sur le parquet :** + NULL + BOOLEAN + FLOAT + DOUBLE + CHAÎNE + ENTIER SIGNÉ : UINT8, UINT16, UINT32, UINT64 + MAP : ne prend en charge qu'un seul niveau. Ne prend pas en charge le mode imbriqué. + LISTE : ne prend en charge qu'un seul niveau. Ne prend pas en charge le mode imbriqué. **Types de données spécifiques à Neptune :** Contrairement aux en-têtes de colonne de propriétés au format CSV, les en-têtes de colonne de propriétés du format Parquet doivent uniquement contenir les noms des propriétés, il n'est donc pas nécessaire d'avoir les noms des types ni la cardinalité. Certains types de colonnes spéciaux au format Parquet nécessitent toutefois une annotation dans les métadonnées, notamment le type Any, le type Date, le type DateTime et le type Geometry. L'objet suivant est un exemple de l'annotation de métadonnées requise pour les fichiers contenant des colonnes de ces types spéciaux : ``` "metadata": { "anyTypeColumns": ["UserCol1"], "dateTypeColumns": ["UserCol2"], "dateTimeTypeColumns": ["UserCol3"], "geometryTypeColumns": ["UserCol4"] } ``` Vous trouverez ci-dessous des informations détaillées sur la charge utile attendue associée à ces types : + Un type de colonne Any est pris en charge dans les colonnes utilisateur. Un type quelconque est un « sucre syntaxique » pour tous les autres types que nous prenons en charge. C'est extrêmement utile si une colonne utilisateur contient plusieurs types. La charge utile d'une valeur de type Any est une liste de chaînes json comme suit :`{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`, qui contient un champ de valeur et un champ de type dans chaque chaîne json individuelle. La valeur de cardinalité d'une colonne Any est définie, ce qui signifie que la colonne peut accepter plusieurs valeurs. + Neptune prend en charge les types suivants dans tous les types : Bool (ou Boolean), Byte, Short, Int, Long,,,,, Float UnsignedByte UnsignedShort, Double UnsignedInt, Date UnsignedLong, DateTime, String et Geometry. + Le type de vecteur n'est pris en charge dans aucun type. + Nested Tous les types ne sont pas pris en charge. Par exemple, `{"value": {"value": "10", "type": "Int"}, "type": "Any"}`. + Les colonnes de type Date et Datetime sont prises en charge dans les colonnes utilisateur. La charge utile de ces colonnes doit être fournie sous forme de chaînes suivant le format XSD ou l'un des formats ci-dessous : + 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:SSS [\$1\$1-] hhmm + Un type de colonne de géométrie est pris en charge dans les colonnes utilisateur. La charge utile de ces colonnes ne doit contenir que des primitives de géométrie de type Point, fournies sous forme de chaînes au format WKT (texte connu). Par exemple, POINT (30 10) serait une valeur de géométrie valide. ## Exemple de sortie pour parquet Étant donné un fichier Parquet comme celui-ci : ``` 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 | +--------+---------+-------------+----------------------+------------+------------+----------+ ``` Voici un exemple de sortie renvoyée par neptune.read à l'aide de la requête suivante : ``` 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" } }] } ``` Il n'existe actuellement aucun moyen de définir une étiquette de nœud ou de bord pour un champ de données provenant d'un fichier Parquet. Il est recommandé de partitionner les requêtes en plusieurs requêtes, une pour chaque étiquette/type. ``` 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) ``` # Exemples de requêtes à l'aide de CSV Dans cet exemple, la requête renvoie le nombre de lignes d'un fichier CSV donné : ``` CALL neptune.read( { source: "", format: "csv" } ) YIELD row RETURN count(row) ``` Vous pouvez exécuter l'exemple de requête à l'aide de l' execute-open-cypher-queryopération décrite dans le en AWS CLI exécutant le code suivant : ``` 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 ``` Une requête peut être flexible quant à l'utilisation des lignes lues à partir d'un fichier CSV. Par exemple, la requête suivante crée un nœud avec un champ défini sur les données d'un fichier CSV : ``` CALL neptune.read( { source: "", format: "csv" } ) YIELD row CREATE (n {someField: row.someCol}) RETURN n ``` **Avertissement** Il n'est pas considéré comme une bonne pratique d'utiliser une clause de grande taille produisant des résultats telle que MATCH (n) avant une clause CALL. Cela entraînerait une requête de longue durée en raison d'un produit croisé entre les solutions entrantes issues des clauses précédentes et les lignes lues par neptune.read. Il est recommandé de démarrer la requête avec CALL neptune.read. ## En-têtes de colonnes de propriétés Vous pouvez spécifier une colonne (`:`) pour une propriété à l'aide de la syntaxe suivante. Les noms de type ne sont pas sensibles à la casse. Si deux points apparaissent dans le nom d'une propriété, il faut l'éviter en le faisant précéder d'une barre oblique inverse :. `\:` ``` propertyname:type ``` **Note** Les espaces, les virgules, le retour en chariot et les caractères de nouvelle ligne ne sont pas autorisés dans les en-têtes de colonne. Les noms de propriétés ne peuvent donc pas inclure ces caractères. Vous pouvez spécifier une colonne pour un type de tableau en ajoutant `[]` au type : ``` propertyname:type[] ``` Les propriétés d'arc ne peuvent avoir qu'une seule valeur et provoquent une erreur si un type de tableau ou une seconde valeur est spécifié. L'exemple suivant montre l'en-tête de colonne d'une propriété nommée age de type Int : ``` age:Int ``` Chaque ligne du fichier doit obligatoirement avoir un nombre entier dans cette position ou rester vide. Les tableaux de chaînes sont autorisés, mais les chaînes d'un tableau ne peuvent pas inclure le point-virgule (`;`) à moins qu'il ne soit évité par une barre oblique inverse (). `\;` ## Types de colonnes CSV pris en charge + **BOOL (ou BOOLEAN)** - Valeurs autorisées : true, false. Indique un champ booléen. Toute valeur autre que true sera traitée comme fausse. + **FLOAT** - Plage : virgule flottante IEEE 754 32 bits, y compris Infinity, INF, -Infinity, -INF et NaN (). not-a-number + **DOUBLE** : plage : virgule flottante IEEE 754 64 bits, y compris Infinity, INF, -Infinity, -INF et NaN (). not-a-number + **CHAÎNE** - + Les guillemets sont facultatifs. Les virgules, les nouvelles lignes et les caractères renvoyant le chariot sont automatiquement ignorés s'ils sont inclus dans une chaîne entourée de guillemets doubles («). Exemple : « Bonjour tout le monde ». + Pour inclure des guillemets dans une chaîne entre guillemets, vous pouvez éviter les guillemets en utilisant deux guillemets d'affilée : « Hello «" World" "». + Les tableaux de chaînes sont autorisés, mais les chaînes d'un tableau ne peuvent pas inclure le point-virgule (;) à moins qu'il ne soit évité par une barre oblique inverse (\$1 ;). + Si vous souhaitez placer des chaînes d'un tableau entre guillemets, vous devez entourer la totalité du tableau par un ensemble de guillemets. Exemple : « Chaîne 1 ; Chaîne 2 ; Chaîne 3 ». + **DATE, DATETIME** - Les valeurs de date/heure peuvent être fournies au format XSD ou dans l'un des formats suivants : + 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:SSS [\$1\$1-] hhmm + **ENTIER SIGNÉ** - + Octet : -128 à 127 + Court : -32768 à 32767 + Int : -2^31 à 2^31-1 + Longue : -2^63 à 2^63-1 **Types de colonnes spécifiques à Neptune :** + Un type de colonne Any est pris en charge dans les colonnes utilisateur. Un type quelconque est un « sucre syntaxique » pour tous les autres types que nous prenons en charge. C'est extrêmement utile si une colonne utilisateur contient plusieurs types. La charge utile d'une valeur de type Any est une liste de chaînes json comme suit :`{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`, qui contient un champ de valeur et un champ de type dans chaque chaîne json individuelle. L'en-tête de colonne d'un type Any est PropertyName:Any. La valeur de cardinalité d'une colonne Any est définie, ce qui signifie que la colonne peut accepter plusieurs valeurs. + Neptune prend en charge les types suivants dans tous les types : Bool (ou Boolean), Byte, Short, Int, Long,,,,, Float UnsignedByte UnsignedShort, Double UnsignedInt, Date UnsignedLong, DateTime, String et Geometry. + Le type de vecteur n'est pris en charge dans aucun type. + Nested Tous les types ne sont pas pris en charge. Par exemple, `{"value": {"value": "10", "type": "Int"}, "type": "Any"}`. + Un type de colonne de géométrie est pris en charge dans les colonnes utilisateur. La charge utile de ces colonnes ne doit contenir que des primitives de géométrie de type Point, fournies sous forme de chaînes au format WKT (texte connu). Par exemple, POINT (30 10) serait une valeur de géométrie valide. ## Exemple de sortie CSV Compte tenu du fichier CSV suivant : ``` 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 ``` Cet exemple montre le résultat renvoyé par neptune.read à l'aide de la requête suivante : ``` 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 } }] } ``` Il n'existe actuellement aucun moyen de définir une étiquette de nœud ou de bordure pour un champ de données provenant d'un fichier CSV. Il est recommandé de partitionner les requêtes en plusieurs requêtes, une pour chaque étiquette/type. ``` 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) ``` # Gérer les autorisations pour neptune.read () ## Politiques IAM requises Pour exécuter les requêtes OpenCypher utilisées`neptune.read()`, vous devez disposer des autorisations appropriées pour accéder aux données de votre base de données Neptune. Les requêtes en lecture seule nécessitent cette action. `ReadDataViaQuery` Les requêtes qui modifient les données nécessitent `WriteDataViaQuery` des insertions ou `DeleteDataViaQuery` des suppressions. L'exemple ci-dessous autorise les trois actions sur le cluster spécifié. En outre, vous devez disposer d'autorisations pour accéder au compartiment S3 contenant vos fichiers de données. La déclaration de politique de Neptunes3Access accorde les autorisations S3 requises : + **`s3:ListBucket`**: obligatoire pour vérifier l'existence du bucket et le contenu de la liste. + **`s3:GetObject`**: Nécessaire pour accéder à l'objet spécifié afin que son contenu puisse être lu en vue de son intégration dans les requêtes OpenCypher. Si votre compartiment S3 utilise le chiffrement côté serveur avec AWS KMS, vous devez également accorder des autorisations KMS. La KMSAccess déclaration de politique de Neptunes3 permet à Neptune de déchiffrer les données et de générer des clés de données lors de l'accès à des objets S3 chiffrés. Cette condition limite les opérations KMS aux demandes provenant des services S3 et RDS de votre région. + **`kms:Decrypt`**: Nécessaire pour effectuer le déchiffrement de l'objet chiffré afin que ses données puissent être lues par Neptune. + **`kms:GenerateDataKey`**: également requis par l'API S3 utilisée pour récupérer les objets à lire. ``` { "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" ] } } } ``` ## Conditions préalables importantes Ces autorisations et conditions préalables garantissent une intégration sûre et fiable des données S3 dans les requêtes OpenCypher, tout en maintenant des contrôles d'accès et des mesures de protection des données appropriés. + **Authentification IAM** : cette fonctionnalité n'est prise en charge que pour les clusters Neptune avec l'authentification IAM activée. Consultez [Sécurisation de votre base de données Amazon Neptune](security.md) pour obtenir des instructions détaillées sur la création et la connexion à des clusters compatibles avec l'authentification IAM. + **Point de terminaison VPC** : + Un point de terminaison VPC de type Gateway pour Amazon S3 est nécessaire pour permettre à Neptune de communiquer avec Amazon S3. + Pour utiliser un AWS KMS chiffrement personnalisé dans la requête, un point de terminaison VPC de type interface est requis AWS KMS pour permettre à Neptune de communiquer avec. AWS KMS + Pour obtenir des instructions détaillées sur la configuration de ce point de terminaison, consultez [Création du point de terminaison Amazon S3 VPC.](bulk-load-tutorial-IAM.md)