Merge pull request #5317 from DarthMax/client_arrow_documentation

Document graph construction in python client

Author: DarthMax

doc/asciidoc/management-ops/graph-catalog/graph-project-apache-arrow.adoc

@@ -100,7 +100,7 @@ Given an example node such as `(:Pokemon { weight: 8.5, height: 0.6, hp: 39 })`,
 [[arrow-node-schema]]
 [opts=header,cols="1,1,1,1,1"]
 |===
-| node_id   | label     | weight    | height    | hp
+| nodeId    | label     | weight    | height    | hp
 | 0         | "Pokemon" | 8.5       | 0.6       | 39
 |===
 
@@ -110,7 +110,7 @@ The following table describes the node columns with reserved names.
 [opts=header,cols="1m,1,1,1,1"]
 |===
 | Name      | Type              | Optional | Nullable   | Description
-| node_id   | Integer           | No       | No         | Unique 64-bit node identifiers for the in-memory graph. Must be positive values.
+| nodeId    | Integer           | No       | No         | Unique 64-bit node identifiers for the in-memory graph. Must be positive values.
 | label     | String or Integer | Yes      | No         | Single node label. Either a string literal or a dictionary encoded number.
 |===
 
@@ -159,7 +159,7 @@ For example, given the relationship `(a)-[:EVOLVES_TO { at_level: 16 }]->(b)` an
 [[arrow-relationship-schema]]
 [opts=header,cols="1,1,1,1"]
 |===
-| source_id | target_id | type          | at_level
+| sourceId  | targetId  | type          | at_level
 | 0         | 1         | "EVOLVES_TO"  | 16
 |===
 
@@ -169,8 +169,8 @@ The following table describes the node columns with reserved names.
 [opts=header,cols="1m,1,1,1,1"]
 |===
 | Name      | Type              | Optional | Nullable   | Description
-| source_id | Integer           | No       | No         | Unique 64-bit source node identifiers. Must be positive values and present in the imported nodes.
-| target_id | Integer           | No       | No         | Unique 64-bit target node identifiers. Must be positive values and present in the imported nodes.
+| sourceId  | Integer           | No       | No         | Unique 64-bit source node identifiers. Must be positive values and present in the imported nodes.
+| targetId  | Integer           | No       | No         | Unique 64-bit target node identifiers. Must be positive values and present in the imported nodes.
 | type      | String or Integer | Yes      | No         | Single relationship type. Either a string literal or a dictionary encoded number.
 |===
 

doc/asciidoc/pythonclient/python-client-graph-object.adoc

@@ -11,9 +11,9 @@ Additionally, the `Graph` objects have convenience methods allowing for inspecti
 include::python-client-gds-object.adoc[]
 
 
-== Constructing a graph object
+== Projecting a graph object
 
-There are several ways of constructing a graph object.
+There are several ways of projecting a graph object.
 The simplest way is to do a <<graph-project-native-syntax, native projection>>:
 
 [source,python]
@@ -41,14 +41,64 @@ To get a graph object that represents a graph that has already been projected in
 G = gds.graph.get("my-graph")
 ----
 
-In addition to those aforementioned there are three more methods that construct graph objects:
+In addition to those aforementioned there are three more methods that create graph objects:
 
 * `gds.graph.project.cypher`
 * `gds.beta.graph.subgraph`
 * `gds.beta.graph.generate`
 
 Their Cypher signatures map to Python in much the same way as `gds.graph.project` above.
 
+[.enterprise-edition]
+== Constructing a graph
+
+Instead of projecting a graph from the Neo4j database it is also possible to construct new graphs using pandas `DataFrames` from the client.
+
+NOTE: To use this feature the <<installation-apache-arrow, Arrow Flight Server>> needs to be enabled.
+
+[source,python]
+----
+nodes = pandas.DataFrame(
+    "nodeId": [0, 1, 2, 3],
+    "label":  ["A", "B", "C", "A"],
+    "prop1": [42, 1337, 8, 0],
+    "otherProperty": [0.1, 0.2, 0.3, 0.4]
+)
+
+relationships = pandas.DataFrame(
+    "sourceId": [0, 1, 2, 3],
+    "targetId": [1, 2, 3, 0],
+    "type": ["REL", "REL", "REL", "REL"],
+    "weight": [0.0, 0.0, 0.1, 42.0]
+)
+
+G = gds.alpha.graph.construct(
+    "my-graph",      # Graph name
+    nodes,           # One or more dataframes containing node data
+    relationships    # One or more dataframes containing relationship data
+)
+----
+
+The above example creates a simple graph using one node and one relationship `DataFrame`.
+The created graph is equivalent to a graph created by the following Cypher query:
+
+[source, cypher]
+----
+CREATE
+    (a:A {prop1: 42,    otherProperty: 0.1),
+    (b:B {prop1: 1337,  otherProperty: 0.2),
+    (c:C {prop1: 8,     otherProperty: 0.3),
+    (d:A {prop1: 0,     otherProperty: 0.4),
+    (a)-[:REL {weight: 0.0}]->(b),
+    (b)-[:REL {weight: 0.0}]->(c),
+    (c)-[:REL {weight: 0.1}]->(d),
+    (d)-[:REL {weight: 42.0}]->(a),
+----
+
+It is possible to supply more than one data frame, both for nodes and relationships.
+If multiple node dataframes are used, they need to contain distinct node ids across all node data frames.
+The supported format for the node data frames is described in <<arrow-node-columns, Arrow node schema>> and the format for the relationship data frames is described in <<arrow-relationship-columns, Arrow relationship schema>>.
+
 
 == Inspecting a graph object