Improve graph documentation for the core engine

Author: aboudreault

docs/graph_fluent.rst

@@ -27,7 +27,19 @@ hard to maintain. This fluent API allows you to build Gremlin traversals and wri
 queries directly in Python. These native traversal queries can be executed explicitly, with
 a `Session` object, or implicitly::
 
-    g = DseGraph.traversal_source(session=dse_session)
+    from cassandra.cluster import Cluster, EXEC_PROFILE_GRAPH_DEFAULT
+    from cassandra.datastax.graph import GraphProtocol
+    from cassandra.datastax.graph.fluent import DseGraph
+
+    # Create an execution profile, using GraphSON3 for Core graphs
+    ep_graphson3 = DseGraph.create_execution_profile(
+        'my_core_graph_name',
+        graph_protocol=GraphProtocol.GRAPHSON_3_0)
+    cluster = Cluster(execution_profiles={EXEC_PROFILE_GRAPH_DEFAULT: ep_graphson3})
+    session = cluster.connect()
+
+    # Execute a fluent graph query
+    g = DseGraph.traversal_source(session=session)
     g.addV('genre').property('genreId', 1).property('name', 'Action').next()
 
     # implicit execution caused by iterating over results
@@ -50,15 +62,24 @@ Configuring a Traversal Execution Profile
 The fluent api takes advantage of *configuration profiles* to allow
 different execution configurations for the various query handlers. Graph traversal
 execution requires a custom execution profile to enable Gremlin-bytecode as
-query language. Here is how to accomplish this configuration:
+query language. With Core graphs, it is important to use GraphSON3. Here is how
+to accomplish this configuration:
 
 .. code-block:: python
 
     from cassandra.cluster import Cluster, EXEC_PROFILE_GRAPH_DEFAULT
+    from cassandra.datastax.graph import GraphProtocol
     from cassandra.datastax.graph.fluent import DseGraph
 
-    ep = DseGraph.create_execution_profile('graph_name')
-    cluster = Cluster(execution_profiles={EXEC_PROFILE_GRAPH_DEFAULT: ep})
+    # Using GraphSON3 as graph protocol is a requirement with Core graphs.
+    ep = DseGraph.create_execution_profile(
+        'graph_name',
+        graph_protocol=GraphProtocol.GRAPHSON_3_0)
+
+    # For Classic graphs, GraphSON1, GraphSON2 and GraphSON3 (DSE 6.8+) are supported.
+    ep_classic = DseGraph.create_execution_profile('classic_graph_name')  # default is GraphSON2
+
+    cluster = Cluster(execution_profiles={EXEC_PROFILE_GRAPH_DEFAULT: ep, 'classic': ep_classic})
     session = cluster.connect()
 
     g = DseGraph.traversal_source(session)  # Build the GraphTraversalSource
@@ -71,27 +92,6 @@ If you want to change execution property defaults, please see the :doc:`Executio
 for a more generalized discussion of the API. Graph traversal queries use the same execution profile defined for DSE graph. If you
 need to change the default properties, please refer to the :doc:`DSE Graph query documentation page <graph>`
 
-Configuring a Traversal Execution Profile for the Core graph engine
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To execute a traversal query with graphs that use the core engine, you need to configure
-a graphson3 execution profile:
-
-.. code-block:: python
-    from cassandra.cluster import Cluster, EXEC_PROFILE_GRAPH_DEFAULT
-    from cassandra.datastax.graph import GraphProtocol
-    from cassandra.datastax.graph.fluent import DseGraph
-
-    ep_graphson3 = DseGraph.create_execution_profile(
-        'my_core_graph_name',
-        graph_protocol=GraphProtocol.GRAPHSON_3_0
-    )
-    cluster = Cluster(execution_profiles={EXEC_PROFILE_GRAPH_DEFAULT: ep_graphson3})
-
-    g = DseGraph.traversal_source(session)
-    print g.V().toList()
-
-
 Explicit Graph Traversal Execution with a DSE Session
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -101,19 +101,28 @@ Below is an example of explicit execution. For this example, assume the schema h
 
 .. code-block:: python
 
+    from cassandra.cluster import Cluster, EXEC_PROFILE_GRAPH_DEFAULT
+    from cassandra.datastax.graph import GraphProtocol
     from cassandra.datastax.graph.fluent import DseGraph
     from pprint import pprint
 
-    # create a tinkerpop graphson2 ExecutionProfile
-    ep = DseGraph.create_execution_profile('graph_name')
+    ep = DseGraph.create_execution_profile(
+        'graph_name',
+        graph_protocol=GraphProtocol.GRAPHSON_3_0)
     cluster = Cluster(execution_profiles={EXEC_PROFILE_GRAPH_DEFAULT: ep})
     session = cluster.connect()
 
     g = DseGraph.traversal_source(session=session)
+
+Convert a traversal to a bytecode query for classic graphs::
+
     addV_query = DseGraph.query_from_traversal(
-        g.addV('genre').property('genreId', 1).property('name', 'Action')
+        g.addV('genre').property('genreId', 1).property('name', 'Action'),
+        graph_protocol=GraphProtocol.GRAPHSON_3_0
     )
-    v_query = DseGraph.query_from_traversal(g.V())
+    v_query = DseGraph.query_from_traversal(
+        g.V(),
+        graph_protocol=GraphProtocol.GRAPHSON_3_0)
 
     for result in session.execute_graph(addV_query):
         pprint(result.value)
@@ -124,7 +133,6 @@ Converting a traversal to a bytecode query for core graphs require some more wor
 need the cluster context for UDT and tuple types:
 
 .. code-block:: python
-    g = DseGraph.traversal_source(session=session)
     context = {
         'cluster': cluster,
         'graph_name': 'the_graph_for_the_query'
@@ -135,6 +143,9 @@ need the cluster context for UDT and tuple types:
         context=context
     )
 
+    for result in session.execute_graph(addV_query):
+        pprint(result.value)
+
 Implicit Graph Traversal Execution with TinkerPop
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -185,19 +196,18 @@ python `Future <https://docs.python.org/3/library/concurrent.futures.html#concur
     # do other stuff...
 
 Specify the Execution Profile explicitly
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you don't want to change the default graph execution profile (`EXEC_PROFILE_GRAPH_DEFAULT`), you can register a new
 one as usual and use it explicitly. Here is an example:
 
-
 .. code-block:: python
 
     from cassandra.cluster import Cluster
     from cassandra.datastax.graph.fluent import DseGraph
 
     cluster = Cluster()
-    ep = DseGraph.create_execution_profile('graph_name')
+    ep = DseGraph.create_execution_profile('graph_name', graph_protocol=GraphProtocol.GRAPHSON_3_0)
     cluster.add_execution_profile('graph_traversal', ep)
     session = cluster.connect()
 
@@ -213,8 +223,8 @@ the same execution profile (for different graphs):
     g_movies = DseGraph.traversal_source(session, graph_name='movies', ep)
     g_series = DseGraph.traversal_source(session, graph_name='series', ep)
 
-    print g_movies.V().toList()  # Traverse the movies Graph
-    print g_series.V().toList()  # Traverse the series Graph
+    print(g_movies.V().toList())  # Traverse the movies Graph
+    print(g_series.V().toList())  # Traverse the series Graph
 
 Batch Queries
 ~~~~~~~~~~~~~
@@ -231,8 +241,10 @@ the execution profile accordingly. Here is a example::
     from cassandra.cluster import Cluster
     from cassandra.datastax.graph.fluent import DseGraph
 
-    ep = DseGraph.create_execution_profile('graph_name')
-    cluster = Cluster(execution_profiles={'graphson2': ep})
+    ep = DseGraph.create_execution_profile(
+        'graph_name',
+        graph_protocol=GraphProtocol.GRAPHSON_3_0)
+    cluster = Cluster(execution_profiles={'graphson3': ep})
     session = cluster.connect()
 
     g = DseGraph.traversal_source()
@@ -247,13 +259,13 @@ the batch to a GraphStatement::
     batch.add(
         g.addV('genre').property('genreId', 2).property('name', 'Drama'))  # Don't use `.next()` with a batch
 
-    graph_statement = batch.as_graph_statement()
+    graph_statement = batch.as_graph_statement(graph_protocol=GraphProtocol.GRAPHSON_3_0)
     graph_statement.is_idempotent = True  # configure any Statement parameters if needed...
-    session.execute_graph(graph_statement, execution_profile='graphson2')
+    session.execute_graph(graph_statement, execution_profile='graphson3')
 
 To execute the batch using :meth:`TraversalBatch.execute <.datastax.graph.fluent.query.TraversalBatch.execute>`, you need to bound the batch to a DSE session::
 
-    batch = DseGraph.batch(session, 'graphson2')  # bound the session and execution profile
+    batch = DseGraph.batch(session, 'graphson3')  # bound the session and execution profile
 
     batch.add(
         g.addV('genre').property('genreId', 1).property('name', 'Action'))