diff --git a/mage/data/query-modules/python/import-util/import_util_graphml.png b/mage/data/query-modules/python/import-util/import_util_graphml.png new file mode 100644 index 00000000000..7e2fdc82c81 Binary files /dev/null and b/mage/data/query-modules/python/import-util/import_util_graphml.png differ diff --git a/mage/query-modules/python/export-util.md b/mage/query-modules/python/export-util.md index 1f7cb7b09e5..f98e3d700f0 100644 --- a/mage/query-modules/python/export-util.md +++ b/mage/query-modules/python/export-util.md @@ -21,7 +21,7 @@ export const Highlight = ({children, color}) => ( ); Module for exporting a graph database or query results in different formats. Currently, this -module supports [**exporting database to a JSON file format**](#jsonpath) and [**exporting query results in a CSV file format**](#csv_queryquery-file_path-stream). +module supports [**exporting database to a JSON file format**](#jsonpath), [**exporting query results in a CSV file format**](#csv_queryquery-file_path-stream) and [**exporting database to a graphML file format**](#graphmlpath-config). [![docs-source](https://img.shields.io/badge/source-export_util-FB6E00?logo=github&style=for-the-badge)](https://github.com/memgraph/mage/blob/main/python/export_util.py) @@ -165,6 +165,83 @@ where `path` is the path to a local CSV file that will be created inside the +### `graphml(path, config)` + +#### Input: + +* `path: string` ➡ path to the graphML file that will contain the exported graph database. +* `config: Map (default={})` ➡ configuration parameters explained below. + +#### Parameters: + +| Name | Type | Default | Description | +|- |- |- |- | +| stream | Bool | False | Stream the file content directly to the client into the status field. | +| format | String | " " | Set the export format to either "gephi" or "tinkerpop". | +| caption | List | [ ] | A list of keys of properties whose value is eligible as value for the `label` data element in Gephi format. Order is important and if no match is found, then there is a fallback to the node's first property. If the node has no properties then the ID is used. | +| useTypes | Bool | False | Store property values' type information. | +| leaveOutLabels | Bool | False | Do not store node's labels. | +| leaveOutProperties | Bool | False | Do not store node's properties. | + +#### Output: + +* `status: string` ➡ file content if stream is set to `True` in configuration parameters, `success` otherwise. + +#### Usage: + +The `path` you have to provide as procedure argument depends on how you started +Memgraph. + + + + + +If you ran Memgraph with Docker, database will be exported to a graphML file inside +the Docker container. We recommend exporting the database to the graphML file +inside the `/usr/lib/memgraph/query_modules` directory. + +You can call the procedure by running the following query: + +```cypher +CALL export_util.graphml(path); +``` +where `path` is the path to the graphML file inside the +`/usr/lib/memgraph/query_modules` directory in the running Docker container (e.g., +`/usr/lib/memgraph/query_modules/export.graphml`). + +:::info +You can [**copy the exported CSV file to your local file system**](/memgraph/how-to-guides/work-with-docker#how-to-copy-files-from-and-to-a-docker-container) using the [`docker cp`](https://docs.docker.com/engine/reference/commandline/cp/) command. +::: + + + + +To export database to a local graphML file create a new directory (for example, +`export_folder`) and run the following command to give the user `memgraph` the +necessary permissions: + +``` +sudo chown memgraph export_folder +``` + +Then, call the procedure by running the following query: + +```cypher +CALL export_util.graphml(path); +``` +where `path` is the path to a local graphML file that will be created inside the +`export_folder` (e.g., `/users/my_user/export_folder/export.graphml`). + + + + ## Example - Exporting database to a JSON file @@ -306,8 +383,8 @@ You can create a simple graph database by running the following queries: ```cypher CREATE (StrangerThings:TVShow {title:'Stranger Things', released:2016, program_creators:['Matt Duffer', 'Ross Duffer']}) CREATE (Eleven:Character {name:'Eleven', portrayed_by:'Millie Bobby Brown'}) -CREATE (JoyceByers:Character {name:'Joyce Byers', portrayed_by:'Millie Bobby Brown'}) -CREATE (JimHopper:Character {name:'Jim Hopper', portrayed_by:'Millie Bobby Brown'}) +CREATE (JoyceByers:Character {name:'Joyce Byers', portrayed_by:'Winona Ryder'}) +CREATE (JimHopper:Character {name:'Jim Hopper', portrayed_by:'David Harbour'}) CREATE (MikeWheeler:Character {name:'Mike Wheeler', portrayed_by:'Finn Wolfhard'}) CREATE (DustinHenderson:Character {name:'Dustin Henderson', portrayed_by:'Gaten Matarazzo'}) CREATE (LucasSinclair:Character {name:'Lucas Sinclair', portrayed_by:'Caleb McLaughlin'}) @@ -376,8 +453,8 @@ The output in the `export.csv` file looks like this: ```csv name,portrayed_by,title,released,program_creators Eleven,Millie Bobby Brown,Stranger Things,2016,"['Matt Duffer', 'Ross Duffer']" -Joyce Byers,Millie Bobby Brown,Stranger Things,2016,"['Matt Duffer', 'Ross Duffer']" -Jim Hopper,Millie Bobby Brown,Stranger Things,2016,"['Matt Duffer', 'Ross Duffer']" +Joyce Byers,Winona Ryder,Stranger Things,2016,"['Matt Duffer', 'Ross Duffer']" +Jim Hopper,David Harbour,Stranger Things,2016,"['Matt Duffer', 'Ross Duffer']" Mike Wheeler,Finn Wolfhard,Stranger Things,2016,"['Matt Duffer', 'Ross Duffer']" Dustin Henderson,Gaten Matarazzo,Stranger Things,2016,"['Matt Duffer', 'Ross Duffer']" Lucas Sinclair,Caleb McLaughlin,Stranger Things,2016,"['Matt Duffer', 'Ross Duffer']" @@ -392,3 +469,133 @@ Erica Sinclair,Priah Ferguson,Stranger Things,2016,"['Matt Duffer', 'Ross Duffer + +## Example - Exporting database to a graphML file + + + + + +You can create a simple graph database by running the following queries: + +```cypher +CREATE (StrangerThings:TVShow {title:'Stranger Things', released:2016, program_creators:['Matt Duffer', 'Ross Duffer']}) +CREATE (Eleven:Character {name:'Eleven', portrayed_by:'Millie Bobby Brown'}) +CREATE (JoyceByers:Character {name:'Joyce Byers', portrayed_by:'Winona Ryder'}) +CREATE (JimHopper:Character {name:'Jim Hopper', portrayed_by:'David Harbour'}) +CREATE (MikeWheeler:Character {name:'Mike Wheeler', portrayed_by:'Finn Wolfhard'}) +CREATE (DustinHenderson:Character {name:'Dustin Henderson', portrayed_by:'Gaten Matarazzo'}) +CREATE (LucasSinclair:Character {name:'Lucas Sinclair', portrayed_by:'Caleb McLaughlin'}) +CREATE (NancyWheeler:Character {name:'Nancy Wheeler', portrayed_by:'Natalia Dyer'}) +CREATE (JonathanByers:Character {name:'Jonathan Byers', portrayed_by:'Charlie Heaton'}) +CREATE (WillByers:Character {name:'Will Byers', portrayed_by:'Noah Schnapp'}) +CREATE (SteveHarrington:Character {name:'Steve Harrington', portrayed_by:'Joe Keery'}) +CREATE (MaxMayfield:Character {name:'Max Mayfield', portrayed_by:'Sadie Sink'}) +CREATE (RobinBuckley:Character {name:'Robin Buckley', portrayed_by:'Maya Hawke'}) +CREATE (EricaSinclair:Character {name:'Erica Sinclair', portrayed_by:'Priah Ferguson'}) +CREATE +(Eleven)-[:ACTED_IN {seasons:[1, 2, 3, 4]}]->(StrangerThings), +(JoyceByers)-[:ACTED_IN {seasons:[1, 2, 3, 4]}]->(StrangerThings), +(JimHopper)-[:ACTED_IN {seasons:[1, 2, 3, 4]}]->(StrangerThings), +(MikeWheeler)-[:ACTED_IN {seasons:[1, 2, 3, 4]}]->(StrangerThings), +(DustinHenderson)-[:ACTED_IN {seasons:[1, 2, 3, 4]}]->(StrangerThings), +(LucasSinclair)-[:ACTED_IN {seasons:[1, 2, 3, 4]}]->(StrangerThings), +(NancyWheeler)-[:ACTED_IN {seasons:[1, 2, 3, 4]}]->(StrangerThings), +(JonathanByers)-[:ACTED_IN {seasons:[1, 2, 3, 4]}]->(StrangerThings), +(WillByers)-[:ACTED_IN {seasons:[1, 2, 3, 4]}]->(StrangerThings), +(SteveHarrington)-[:ACTED_IN {seasons:[1, 2, 3, 4]}]->(StrangerThings), +(MaxMayfield)-[:ACTED_IN {seasons:[2, 3, 4]}]->(StrangerThings), +(RobinBuckley)-[:ACTED_IN {seasons:[3, 4]}]->(StrangerThings), +(EricaSinclair)-[:ACTED_IN {seasons:[2, 3, 4]}]->(StrangerThings); +``` + + + + +The image below shows the above data as a graph: + + + + + + + +If you're using **Memgraph with Docker**, the following Cypher query will +export the database to the `export.graphml` file in the +`/usr/lib/memgraph/query_modules` directory inside the running Docker container. + +```cypher +CALL export_util.graphml("/usr/lib/memgraph/query_modules/export.graphml, {useTypes: true}) +YIELD status RETURN status; +``` + +If you're using **Memgraph on Ubuntu, Debian, RPM package or WSL**, the +following Cypher query will export the database to the `export.graphml` file in the +`/users/my_user/export_folder`. + +```cypher +CALL export_util.graphml("/users/my_user/export_folder/export.graphml, {useTypes: true}) +YIELD status RETURN status; +``` + + + + + +The output in the `export.graphml` file looks like this: + + +```xml + + + + + + + + + + + +:TVShowStranger Things2016["Matt Duffer", "Ross Duffer"] +:CharacterElevenMillie Bobby Brown +:CharacterJoyce ByersWinona Ryder +:CharacterJim HopperDavid Harbour +:CharacterMike WheelerFinn Wolfhard +:CharacterDustin HendersonGaten Matarazzo +:CharacterLucas SinclairCaleb McLaughlin +:CharacterNancy WheelerNatalia Dyer +:CharacterJonathan ByersCharlie Heaton +:CharacterWill ByersNoah Schnapp +:CharacterSteve HarringtonJoe Keery +:CharacterMax MayfieldSadie Sink +:CharacterRobin BuckleyMaya Hawke +:CharacterErica SinclairPriah Ferguson +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[2, 3, 4] +ACTED_IN[3, 4] +ACTED_IN[2, 3, 4] + + +``` + + + diff --git a/mage/query-modules/python/import-util.md b/mage/query-modules/python/import-util.md index 589c53fe47a..8835ea3f3d6 100644 --- a/mage/query-modules/python/import-util.md +++ b/mage/query-modules/python/import-util.md @@ -21,7 +21,7 @@ export const Highlight = ({children, color}) => ( ); Module for importing data from different formats. Currently, this module -supports only the import of JSON file format. +supports the import of JSON and graphML file formats. [![docs-source](https://img.shields.io/badge/source-import_util-FB6E00?logo=github&style=for-the-badge)](https://github.com/memgraph/mage/blob/main/python/import_util.py) @@ -47,7 +47,7 @@ The JSON file you're importing needs to be structured the same as the JSON file that the [`export_util.json()`](/docs/mage/query-modules/python/export-util) procedure generates. The generated JSON file is a list of objects representing -nodes or relationships. If the object is node, then it looks like this: +nodes or relationships. If the object is a node, then it looks like this: ```json { @@ -65,7 +65,7 @@ nodes or relationships. If the object is node, then it looks like this: The `id` key has the value of the Memgraph's internal node ide. The `labels` key holds the information about node labels in a list. The `properties` are -key-value pairs representing properties of the certain node. Each node needs to +key-value pairs representing the properties of a certain node. Each node needs to have the value of `type` set to `"node"`. On the other hand, if the object is a relationship, then it is structured like this: @@ -83,8 +83,8 @@ On the other hand, if the object is a relationship, then it is structured like t } ``` -The `end` and `start` keys hold the information about the internal ids of start -and end node of the relationship. Each relationship also has it's internal id +The `end` and `start` keys hold the information about the internal IDs of start +and end node of the relationship. Each relationship also has its internal id exported as a value of `id` key. A relationship can only have one label which is exported to the `label` key. Properties are again key-value pairs, and the value of `type` needs to be set to `"relationship"`. @@ -139,6 +139,83 @@ where `path` is the path to a local JSON file that will be created inside the +### `graphml(path, config)` + +#### Input: + +* `path: string` ➡ path to the graphML file that is being imported. +* `config: Map (default={})` ➡ configuration parameters explained below. + +#### Parameters: + +| Name | Type | Default | Description | +|- |- |- |- | +| readLabels | Bool | False | Create node labels by using the value of the `labels` property. | +| defaultRelationshipType | String | "RELATED" | The default relationship type to use when none is specified in the import file. | +| storeNodeIds | Bool | False | Store node's id attribute as a property. | +| source | Map | { } | A map with two keys: `label` and `id`. The `label` is mandatory, while the `id`'s default value is `id`. This allows the import of relationships if the source node is absent in the file. It will search for a source node with a specific label and a property equal to the map's `id` value. The value of that property should be equal to the relationship's source node ID. For example, with a config map `{source: {id: 'serial_number', label: 'Device'}}` and an edge defined as `CONNECT`, if node "n0" doesn't exist, it will search for a source node `(:Device {serial_number: "n0"})`. | +| target | Map | { } | A map with two keys: `label` and `id`. The `label` is mandatory while the `id`'s default value is `id`. This allows the import of relationships in case the target node is absent in the file. It will search for a target node with a specific label and a property equal to the map's `id` value. The value of that property should be equal to the relationship's target node ID. For example, with a config map `{target: {id: 'serial_number', label: 'Device'}}` and an edge defined as `CONNECT`, if node "n1" doesn't exist, it will search for a target node `(:Device {serial_number: "n1"})`. | + +#### Output: + +- `status: string` ➡ `success` if no errors are generated. + +#### Usage: + +The `path` you have to provide as procedure argument depends on how you started +Memgraph. + + + + + +If you ran Memgraph with Docker, database will be exported to a graphML file inside +the Docker container. We recommend exporting the database to the graphML file +inside the `/usr/lib/memgraph/query_modules` directory. + +You can call the procedure by running the following query: + +```cypher +CALL export_util.graphML(path); +``` +where `path` is the path to the graphML file inside the +`/usr/lib/memgraph/query_modules` directory in the running Docker container (e.g., +`/usr/lib/memgraph/query_modules/export.graphml`). + +:::info +You can [**copy the exported CSV file to your local file system**](/memgraph/how-to-guides/work-with-docker#how-to-copy-files-from-and-to-a-docker-container) using the [`docker cp`](https://docs.docker.com/engine/reference/commandline/cp/) command. +::: + + + + +To export database to a local graphML file create a new directory (for example, +`export_folder`) and run the following command to give the user `memgraph` the +necessary permissions: + +``` +sudo chown memgraph export_folder +``` + +Then, call the procedure by running the following query: + +```cypher +CALL export_util.graphml(path); +``` +where `path` is the path to a local graphML file that will be created inside the +`export_folder` (e.g., `/users/my_user/export_folder/export.graphml`). + + + + + ## Example - Importing JSON file to create a database + + + +## Example - Importing graphML file to create a database + + + + +Below is the content of the `import.graphml` file. + +- If you're using **Memgraph with Docker**, then you have to save the + `import.graphml` file in the `/usr/lib/memgraph/query_modules` directory inside + the running Docker container. + +- If you're using **Memgraph on Ubuntu, Debian, RPM package or WSL**, then you + have to save the `import.graphml` file in the local + `/users/my_user/import_folder` directory. + +```xml + + + + + + + + + + + +:TVShowStranger Things2016["Matt Duffer", "Ross Duffer"] +:CharacterElevenMillie Bobby Brown +:CharacterJoyce ByersWinona Ryder +:CharacterJim HopperDavid Harbour +:CharacterMike WheelerFinn Wolfhard +:CharacterDustin HendersonGaten Matarazzo +:CharacterLucas SinclairCaleb McLaughlin +:CharacterNancy WheelerNatalia Dyer +:CharacterJonathan ByersCharlie Heaton +:CharacterWill ByersNoah Schnapp +:CharacterSteve HarringtonJoe Keery +:CharacterMax MayfieldSadie Sink +:CharacterRobin BuckleyMaya Hawke +:CharacterErica SinclairPriah Ferguson +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[1, 2, 3, 4] +ACTED_IN[2, 3, 4] +ACTED_IN[3, 4] +ACTED_IN[2, 3, 4] + + +``` + + + + +If you're using **Memgraph with Docker**, then the following Cypher query will +create a graph database from the provided graphML file: + +```cypher +CALL import_util.graphml("/usr/lib/memgraph/query_modules/import.graphml", {readLabels: true}) +YIELD status RETURN status; +``` + +If you're using **Memgraph on Ubuntu, Debian, RPM package or WSL**, then the +following Cypher query will create a graph database from the provided graphML file: + +```cypher +CALL import_util.graphml("/users/my_user/import_folder/import.graphml", {readLabels: true}) +YIELD status RETURN status; +``` + + + + + +After you import the `import.graphml` file, you get the following graph database: + + + + + \ No newline at end of file