Improve notebook documentation

Co-authored-by: Mats Rydberg <mats@neo4j.org>

Author: DarthMax

examples/graph-analytics-serverless-spark.ipynb

@@ -26,12 +26,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This Jupyter notebook is hosted [here](https://github.com/neo4j/graph-data-science-client/blob/main/examples/graph-analytics-serverless.ipynb) in the Neo4j Graph Data Science Client Github repository.\n",
+    "This Jupyter notebook is hosted [here](https://github.com/neo4j/graph-data-science-client/blob/main/examples/graph-analytics-serverless-spark.ipynb) in the Neo4j Graph Data Science Client Github repository.\n",
     "\n",
-    "The notebook shows how to use the `graphdatascience` Python library to create, manage, and use a GDS Session.\n",
+    "The notebook shows how to use the `graphdatascience` Python library to create, manage, and use a GDS Session from within an Apache Spark cluster.\n",
     "\n",
-    "We consider a graph of bicycle rentals, which we're using as a simple example to show how project data from Spark to a GDS Session, run algorithms, and eventually retrieving the results back to Spark.\n",
-    "We will cover all management operations: creation, listing, and deletion."
+    "We consider a graph of bicycle rentals, which we're using as a simple example to show how to project data from Spark to a GDS Session, run algorithms, and eventually return results back to Spark.\n",
+    "In this notebook we will focus on the interaction with Apache Spark, and will not cover all possible actions using GDS sessions. We refer to other Tutorials for additional details."
    ]
   },
   {
@@ -74,7 +74,7 @@
    "source": [
     "### Connecting to a Spark Session\n",
     "\n",
-    "To interact with the Spark Cluster we need to first instantiate a Spark session. In this example we will use a local Spark session, which will run Spark on the same machine.\n",
+    "To interact with the Spark cluster we need to first instantiate a Spark session. In this example we will use a local Spark session, which will run Spark on the same machine.\n",
     "Working with a remote Spark cluster will work similarly."
    ]
   },
@@ -115,7 +115,7 @@
     "api_credentials = AuraAPICredentials(\n",
     "    client_id=os.environ[\"CLIENT_ID\"],\n",
     "    client_secret=os.environ[\"CLIENT_SECRET\"],\n",
-    "    # If your account is a member of several project, you must also specify the project ID to use\n",
+    "    # If your account is a member of several projects, you must also specify the project ID to use\n",
     "    project_id=os.environ.get(\"PROJECT_ID\", None),\n",
     ")\n",
     "\n",
@@ -164,7 +164,8 @@
    "source": [
     "## Adding a dataset\n",
     "\n",
-    "As the next step we will setup a dataset in Spark. In this example we will use the New York Bike trips dataset (https://www.kaggle.com/datasets/gabrielramos87/bike-trips)."
+    "As the next step we will setup a dataset in Spark. In this example we will use the New York Bike trips dataset (https://www.kaggle.com/datasets/gabrielramos87/bike-trips).",
+    "The bike trips form a graph where nodes represent bike renting stations and relationships represent start and end points for a bike rental trip."
    ]
   },
   {
@@ -209,8 +210,8 @@
     "\n",
     "1. Send an action `v2/graph.project.fromTriplets`\n",
     "   This will initialize the import process and allows us to specify the graph name, and settings like `undirected_relationship_types`. It returns a job id, that we need to reference the import job in the following steps.\n",
-    "2. Send the data in batches to the arrow server.\n",
-    "3. Send another action called `v2/graph.project.fromTriplets.done` to tell the import process that no more data will be send. This will trigger the final graph creation inside the session.\n",
+    "2. Send the data in batches to the Arrow server.\n",
+    "3. Send another action called `v2/graph.project.fromTriplets.done` to tell the import process that no more data will be sent. This will trigger the final graph creation inside the GDS session.\n",
     "4. Wait for the import process to reach the `DONE` state.\n",
     "\n",
     "While the overall process is straight forward, we need to somehow tell Spark to"
@@ -234,7 +235,7 @@
     "job_id = arrow_client.create_graph_from_triplets(graph_name, concurrency=4)\n",
     "\n",
     "\n",
-    "# Define a function that receives an arrow batch and uploads it to the session\n",
+    "# Define a function that receives an arrow batch and uploads it to the GDS session\n",
     "def upload_batch(iterator):\n",
     "    for batch in iterator:\n",
     "        arrow_client.upload_triplets(job_id, [batch])\n",
@@ -247,7 +248,7 @@
     "  FROM bike_trips\n",
     "\"\"\")\n",
     "\n",
-    "# 2. Use the `mapInArrow` function to upload the data to the sessions. Returns a dataframe with a single column with the batch sizes.\n",
+    "# 2. Use the `mapInArrow` function to upload the data to the GDS session. Returns a DataFrame with a single column containing the batch sizes.\n",
     "uploaded_batches = source_target_pairs.mapInArrow(upload_batch, \"batch_rows_imported long\")\n",
     "\n",
     "# Aggregate the batch sizes to receive the row count.\n",
@@ -291,7 +292,7 @@
     "\n",
     "Once the computation is done, we might want to further use the result in Spark.\n",
     "We can do this in a similar way to the projection, by streaming batches of data into each of the Spark workers.\n",
-    "Retrieving the data is a bit more complicated since we need some input data frame in order to trigger computations on the Spark workers.\n",
+    "Retrieving the data is a bit more complicated since we need some input DataFrame in order to trigger computations on the Spark workers.\n",
     "We use a data range equal to the size of workers we have in our cluster as our driving table.\n",
     "On the workers we will disregard the input and instead stream the computation data from the GDS Session."
    ]
@@ -302,7 +303,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# 1. Start the node property export on the session\n",
+    "# 1. Start the node property export on the GDS session\n",
     "job_id = arrow_client.get_node_properties(G.name(), [\"pagerank\"])\n",
     "\n",
     "\n",
@@ -330,9 +331,9 @@
    "source": [
     "## Cleanup\n",
     "\n",
-    "Now that we have finished our analysis, we can delete the session and stop the spark connection.\n",
+    "Now that we have finished our analysis, we can delete the GDS session and stop the Spark session.\n",
     "\n",
-    "Deleting the session will release all resources associated with it, and stop incurring costs."
+    "Deleting the GDS session will release all resources associated with it, and stop incurring costs."
    ]
   },
   {

src/graphdatascience/session/aura_graph_data_science.py

@@ -184,7 +184,7 @@ def __getattr__(self, attr: str) -> IndirectCallBuilder:
     def arrow_client(self) -> GdsArrowClient:
         """
         Returns a GdsArrowClient that is authenticated to communicate with the Aura Graph Analytics Session.
-        This client can be used to get direct access to the sessions Arrow Flight server.
+        This client can be used to get direct access to the specific session's Arrow Flight server.
 
         Returns:
             A GdsArrowClient