Skip to content

Commit 2e302f9

Browse files
nvituccinvitucci
committed
Add integration pages
1 parent 1eafef7 commit 2e302f9

File tree

7 files changed

+283
-282
lines changed

7 files changed

+283
-282
lines changed

‎docs/antora/modules/ROOT/content-nav.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22
* xref:installation.adoc[]
33
* xref:getting-started.adoc[]
44
* xref:integration/index.adoc[]
5+
** xref:integration/pandas.adoc[]
6+
** xref:integration/gds.adoc[]
7+
** xref:integration/neo4j.adoc[]
8+
** xref:integration/gql.adoc[]
9+
** xref:integration/snowflake.adoc[]
510
* xref:rendering.adoc[]
611
* xref:customizing.adoc[]
712
* link:{tutorials-docs-uri}[Tutorials]

‎docs/antora/modules/ROOT/pages/integration/gds.adoc‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
= Neo4j Graph Data Science
2+
3+
The `neo4j-viz` library provides a convenience method for importing data from the link:https://neo4j.com/docs/graph-data-science/current/[Neo4j Graph Data Science] (GDS) library.
4+
It requires and additional dependency to be installed, which you can do by running:
5+
6+
[source, console]
7+
----
8+
pip install neo4j-viz[gds]
9+
----
10+
11+
Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_gds[`from_gds`] method
12+
to import projections from the GDS library.
13+
14+
The `from_gds` method takes two mandatory positional parameters:
15+
16+
* An initialized `GraphDataScience` object for the connection to the GDS instance, and
17+
* A `Graph` representing the projection that one wants to import.
18+
19+
The optional `max_node_count` parameter can be used to limit the number of nodes that are imported from the projection.
20+
By default, it is set to 10.000, meaning that if the projection has more than 10.000 nodes, `from_gds` will sample from it using random walk with restarts, to get a smaller graph that can be visualized.
21+
If you want to have more control of the sampling, such as choosing a specific start node for the sample, you can call a link:https://neo4j.com/docs/graph-data-science/current/management-ops/graph-creation/sampling/[sampling] method yourself and passing the resulting projection to `from_gds`.
22+
23+
The `node_properties` parameter is also optional, and should be a list of additional node properties of the projection that you want to include in the visualization.
24+
The default is `None`, which means that all properties of the nodes in the projection will be included.
25+
Apart from being visible through on-hover tooltips, these properties could be used to color the nodes, or give captions to them in the visualization, or simply included in the nodes' `Node.properties` maps without directly impacting the visualization.
26+
If you want to include node properties stored at the Neo4j database, you can include them in the visualization by using the _db_node_properties_ parameter.
27+
28+
== Example
29+
30+
In this small example, we import a graph projection from the GDS library, that has the node properties "pagerank" and
31+
"componentId".
32+
We use the "pagerank" property to determine the size of the nodes, and the "componentId" property to color the nodes.
33+
34+
[source, python]
35+
----
36+
from graphdatascience import GraphDataScience
37+
from neo4j_viz.gds import from_gds
38+
gds = GraphDataScience(...)
39+
G = gds.graph.project(...)
40+
# Compute the PageRank and Weakly Connected Components
41+
gds.pageRank.mutate(G, mutateProperty="pagerank")
42+
gds.wcc.mutate(G, mutateProperty="componentId")
43+
# Import the projection into a `VisualizationGraph`
44+
# Make sure to include `pagerank` and `componentId`
45+
VG = from_gds(
46+
gds,
47+
G,
48+
size_property="pagerank",
49+
additional_node_properties=["componentId"],
50+
)
51+
# Color the nodes by the `componentId` property, so that the nodes are
52+
# colored by the connected component they belong to
53+
VG.color_nodes(property="componentId")
54+
----
55+
56+
See the link:/tutorials/gds-example[Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial] for a more extensive example.

‎docs/antora/modules/ROOT/pages/integration/gql.adoc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
= GQL `CREATE` queries
2+
3+
The `neo4j-viz` library provides convenience for creating visualization graphs from link:https://neo4j.com/docs/cypher-manual/current/clauses/create/[GQL `CREATE` queries] via the `from_gql_create` method.
4+
5+
The link:{api-docs-uri}/from_gql_create[`from_gql_create`] method takes one mandatory positional parameter:
6+
7+
* A valid `query` representing a GQL `CREATE` query as a string.
8+
9+
== Example
10+
11+
In this small example, we create a visualization graph from a GQL `CREATE` query.
12+
13+
[source, python]
14+
----
15+
from neo4j_viz.gql_create import from_gql_create
16+
17+
query = """
18+
CREATE
19+
(a:User {name: 'Alice', age: 23}),
20+
(b:User {name: 'Bridget', age: 34}),
21+
(c:User {name: 'Charles', age: 45}),
22+
(d:User {name: 'Dana', age: 56}),
23+
(e:User {name: 'Eve', age: 67}),
24+
(f:User {name: 'Fawad', age: 78}),
25+
(a)-[:LINK {weight: 0.5}]->(b),
26+
(a)-[:LINK {weight: 4}]->(c),
27+
(e)-[:LINK {weight: 1.1}]->(d),
28+
(e)-[:LINK {weight: -2}]->(f);
29+
"""
30+
31+
VG = from_gql_create(query)
32+
----

‎docs/antora/modules/ROOT/pages/integration/index.adoc‎

Lines changed: 6 additions & 282 deletions
Original file line numberDiff line numberDiff line change
@@ -1,286 +1,10 @@
11
= Integration with other libraries
22

33
In addition to creating graphs from scratch, with `neo4j-viz` as is shown in the
4-
xref:getting-started.adoc[], you can also import data directly from external sources.
5-
In this section we will cover how to import data from link:https://pandas.pydata.org/[Pandas DataFrames],
6-
link:https://neo4j.com/docs/graph-data-science/current/[Neo4j Graph Data Science],
7-
link:https://neo4j.com/docs/python-manual/current/[Neo4j Database],
8-
link:https://neo4j.com/docs/cypher-manual/current/clauses/create/[GQL `CREATE` queries], and link:https://docs.snowflake.com/[Snowflake tables].
4+
xref:getting-started.adoc[], you can also import data directly from external sources, including:
95

10-
== Pandas DataFrames
11-
12-
The `neo4j-viz` library provides a convenience method for importing data from Pandas DataFrames.
13-
These DataFrames can be created from many sources, such as CSV files.
14-
It requires and additional dependency to be installed, which you can do by running:
15-
16-
[source, console]
17-
----
18-
pip install neo4j-viz[pandas]
19-
----
20-
21-
Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_pandas[`from_pandas`] method
22-
to import pandas DataFrames.
23-
24-
The `from_dfs` method takes two mandatory positional parameters:
25-
26-
* A Pandas `DataFrame`, or iterable (eg. list) of DataFrames representing the nodes of the graph.
27-
The rows of the DataFrame(s) should represent the individual nodes, and the columns should represent the node
28-
IDs and attributes.
29-
The node ID will be set on the link:{api-docs-uri}/node[Node], Other columns will be a key in each node's properties dictionary, that maps to the node's corresponding value in the column.
30-
If the graph has no node properties, the nodes can be derived from the relationships DataFrame alone.
31-
* A Pandas `DataFrame`, or iterable (eg. list) of DataFrames representing the relationships of the graph.
32-
The rows of the DataFrame(s) should represent the individual relationships, and the columns should represent the
33-
relationship IDs and attributes.
34-
The relationship id, source and target node IDs will be set on the link:{api-docs-uri}/relationship[Relationship].
35-
Other columns will be a key in each relationship's _properties_ dictionary, that maps to the relationship's corresponding value in the column.
36-
37-
=== Example
38-
39-
In this small example, we import a tiny toy graph representing a social network from two Pandas DataFrames.
40-
As we can see the column names of the DataFrames map directly to the fields of link:{api-docs-uri}/node[Nodes]
41-
and link:{api-docs-uri}/relationship[Relationships].
42-
43-
[source, python]
44-
----
45-
from pandas import DataFrame
46-
from neo4j_viz.pandas import from_dfs
47-
48-
nodes = DataFrame({
49-
"id": [1, 2, 3],
50-
"caption": ["Alice", "Bob", "Charlie"],
51-
"size": [20, 10, 10],
52-
})
53-
54-
relationships = DataFrame({
55-
"source": [1, 2],
56-
"target": [2, 3],
57-
"caption": ["LIKES", "KNOWS"],
58-
})
59-
60-
VG = from_dfs(nodes, relationships)
61-
----
62-
63-
== Neo4j Graph Data Science (GDS) library
64-
65-
The `neo4j-viz` library provides a convenience method for importing data from the Neo4j Graph Data Science (GDS)
66-
library.
67-
It requires and additional dependency to be installed, which you can do by running:
68-
69-
[source, console]
70-
----
71-
pip install neo4j-viz[gds]
72-
----
73-
74-
Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_gds[`from_gds`] method
75-
to import projections from the GDS library.
76-
77-
The `from_gds` method takes two mandatory positional parameters:
78-
79-
* An initialized `GraphDataScience` object for the connection to the GDS instance, and
80-
* A `Graph` representing the projection that one wants to import.
81-
82-
The optional `max_node_count` parameter can be used to limit the number of nodes that are imported from the projection.
83-
By default, it is set to 10.000, meaning that if the projection has more than 10.000 nodes, `from_gds` will sample from it using random walk with restarts, to get a smaller graph that can be visualized.
84-
If you want to have more control of the sampling, such as choosing a specific start node for the sample, you can call a link:https://neo4j.com/docs/graph-data-science/current/management-ops/graph-creation/sampling/[sampling] method yourself and passing the resulting projection to `from_gds`.
85-
86-
The `node_properties` parameter is also optional, and should be a list of additional node properties of the projection that you want to include in the visualization.
87-
The default is `None`, which means that all properties of the nodes in the projection will be included.
88-
Apart from being visible through on-hover tooltips, these properties could be used to color the nodes, or give captions to them in the visualization, or simply included in the nodes' `Node.properties` maps without directly impacting the visualization.
89-
If you want to include node properties stored at the Neo4j database, you can include them in the visualization by using the _db_node_properties_ parameter.
90-
91-
=== Example
92-
93-
In this small example, we import a graph projection from the GDS library, that has the node properties "pagerank" and
94-
"componentId".
95-
We use the "pagerank" property to determine the size of the nodes, and the "componentId" property to color the nodes.
96-
97-
[source, python]
98-
----
99-
from graphdatascience import GraphDataScience
100-
from neo4j_viz.gds import from_gds
101-
gds = GraphDataScience(...)
102-
G = gds.graph.project(...)
103-
# Compute the PageRank and Weakly Connected Components
104-
gds.pageRank.mutate(G, mutateProperty="pagerank")
105-
gds.wcc.mutate(G, mutateProperty="componentId")
106-
# Import the projection into a `VisualizationGraph`
107-
# Make sure to include `pagerank` and `componentId`
108-
VG = from_gds(
109-
gds,
110-
G,
111-
size_property="pagerank",
112-
additional_node_properties=["componentId"],
113-
)
114-
# Color the nodes by the `componentId` property, so that the nodes are
115-
# colored by the connected component they belong to
116-
VG.color_nodes(property="componentId")
117-
----
118-
119-
See the link:/tutorials/gds-example[Visualizing Neo4j Graph Data Science (GDS) Graphs tutorial] for a more extensive example.
120-
121-
== Neo4j Database
122-
123-
The `neo4j-viz` library provides a convenience method for importing data from Neo4j.
124-
It requires and additional dependency to be installed, which you can do by running:
125-
126-
[source, console]
127-
----
128-
pip install neo4j-viz[neo4j]
129-
----
130-
131-
Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_neo4j[`from_neo4j`] method
132-
to import query results from Neo4j.
133-
134-
The `from_neo4j` method takes one mandatory positional parameter: A `data` argument representing either a query result in the shape of a `neo4j.graph.Graph` or `neo4j.Result`, or a `neo4j.Driver` in which case a simple default query will be executed internally to retrieve the graph data.
135-
136-
The optional `max_rows` parameter can be used to limit the number of relationships shown in the visualization.
137-
By default, it is set to 10.000, meaning that if the database has more than 10.000 rows, a warning will be raised.
138-
Note, this only applies if the `data` parameter is a `neo4j.Driver`.
139-
140-
=== Example
141-
142-
In this small example, we import a graph from a Neo4j query result.
143-
144-
[source, python]
145-
----
146-
from neo4j import GraphDatabase, RoutingControl, Result
147-
from neo4j_viz.gds import from_gds
148-
149-
# Modify this to match your Neo4j instance's URI and credentials
150-
URI = "neo4j://localhost:7687"
151-
auth = ("neo4j", "password")
152-
153-
with GraphDatabase.driver(URI, auth=auth) as driver:
154-
driver.verify_connectivity()
155-
result = driver.execute_query(
156-
"MATCH (n)-[r]->(m) RETURN n,r,m",
157-
database_="neo4j",
158-
routing_=RoutingControl.READ,
159-
result_transformer_=Result.graph,
160-
)
161-
162-
VG = from_neo4j(result)
163-
----
164-
165-
See the link:/tutorials/neo4j-example[Visualizing Neo4j Graphs tutorial] for a more extensive example.
166-
167-
== GQL `CREATE` query
168-
169-
The `neo4j-viz` library provides convenience for creating visualization graphs from GQL `CREATE` queries via the link:{api-docs-uri}/from_gql_create[`from_gql_create`] method.
170-
171-
The `from_gql_create` method takes one mandatory positional parameter:
172-
173-
* A valid `query` representing a GQL `CREATE` query as a string.
174-
175-
=== Example
176-
177-
In this small example, we create a visualization graph from a GQL `CREATE` query.
178-
179-
[source, python]
180-
----
181-
from neo4j_viz.gql_create import from_gql_create
182-
183-
query = """
184-
CREATE
185-
(a:User {name: 'Alice', age: 23}),
186-
(b:User {name: 'Bridget', age: 34}),
187-
(c:User {name: 'Charles', age: 45}),
188-
(d:User {name: 'Dana', age: 56}),
189-
(e:User {name: 'Eve', age: 67}),
190-
(f:User {name: 'Fawad', age: 78}),
191-
(a)-[:LINK {weight: 0.5}]->(b),
192-
(a)-[:LINK {weight: 4}]->(c),
193-
(e)-[:LINK {weight: 1.1}]->(d),
194-
(e)-[:LINK {weight: -2}]->(f);
195-
"""
196-
197-
VG = from_gql_create(query)
198-
----
199-
200-
== Snowflake Tables
201-
202-
The `neo4j-viz` library provides a convenience method for importing data from Snowflake tables.
203-
It requires and additional dependency to be installed, which you can do by running:
204-
205-
[source, console]
206-
----
207-
pip install neo4j-viz[snowflake]
208-
----
209-
210-
Once you have installed the additional dependency, you can use the link:{api-docs-uri}/from_snowflake[`from_snowflake`] method to import Snowflake tables into a `VisualizationGraph`.
211-
212-
The `from_snowflake` method takes two mandatory positional parameters:
213-
214-
* A `snowflake.snowpark.Session` object for the connection to Snowflake, and
215-
216-
* A link:https://neo4j.com/docs/snowflake-graph-analytics/current/jobs/#jobs-project[project configuration] as a dictionary, that specifies how you want your tables to be projected as a graph.
217-
This configuration is the same as the project configuration of the link:https://neo4j.com/docs/snowflake-graph-analytics/current/[Neo4j Snowflake Graph Analytics application].
218-
219-
You can further customize the visualization after the _VisualizationGraph_ has been created, by using the methods described in the link:{api-docs-uri}/customizing/[Customizing the visualization] section.
220-
221-
=== Default behavior
222-
223-
The node and relationship captions will be set to the names of the corresponding tables.
224-
The nodes will be colored so that nodes from the same table have the same color, and different tables have different colors.
225-
226-
=== Example
227-
228-
In this small example, we import a toy graph representing a social network from two tables in Snowflake.
229-
230-
[source, python]
231-
----
232-
from snowflake.snowpark import Session
233-
from neo4j_viz.snowflake import from_dfs
234-
235-
# Configure according to your own setup
236-
connection_parameters = {
237-
"account": os.environ.get("SNOWFLAKE_ACCOUNT"),
238-
"user": os.environ.get("SNOWFLAKE_USER"),
239-
"password": os.environ.get("SNOWFLAKE_PASSWORD"),
240-
"role": os.environ.get("SNOWFLAKE_ROLE"),
241-
"warehouse": os.environ.get("SNOWFLAKE_WAREHOUSE"),
242-
}
243-
244-
session.sql(
245-
"CREATE OR REPLACE TABLE EXAMPLE_DB.DATA_SCHEMA.PERSONS (NODEID VARCHAR);"
246-
).collect()
247-
248-
session.sql("""
249-
INSERT INTO EXAMPLE_DB.DATA_SCHEMA.PERSONS VALUES
250-
('Alice'),
251-
('Bob'),
252-
('Carol'),
253-
('Dave'),
254-
('Eve');
255-
""").collect()
256-
257-
session.sql(
258-
"CREATE OR REPLACE TABLE EXAMPLE_DB.DATA_SCHEMA.KNOWS (SOURCENODEID VARCHAR, TARGETNODEID VARCHAR);"
259-
).collect()
260-
261-
session.sql("""
262-
INSERT INTO EXAMPLE_DB.DATA_SCHEMA.KNOWS VALUES
263-
('Alice', 'Dave'),
264-
('Alice', 'Carol'),
265-
('Bob', 'Carol'),
266-
('Dave', 'Eve'),
267-
""").collect()
268-
269-
VG = from_snowflake(
270-
session,
271-
{
272-
"nodeTables": [
273-
"EXAMPLE_DB.DATA_SCHEMA.PERSONS",
274-
],
275-
"relationshipTables": {
276-
"EXAMPLE_DB.DATA_SCHEMA.KNOWS": {
277-
"sourceTable": "EXAMPLE_DB.DATA_SCHEMA.PERSONS",
278-
"targetTable": "EXAMPLE_DB.DATA_SCHEMA.PERSONS",
279-
"orientation": "UNDIRECTED",
280-
}
281-
},
282-
},
283-
)
284-
----
285-
286-
For a full example of the `from_snowflake` importer in action, please see the link:http://localhost:9000/tutorials/snowflake-example/[Visualizing Snowflake Tables tutorial].
6+
* xref:integration/pandas.adoc[]
7+
* xref:integration/gds.adoc[]
8+
* xref:integration/neo4j.adoc[]
9+
* xref:integration/gql.adoc[]
10+
* xref:integration/snowflake.adoc[]

0 commit comments

Comments
 (0)