******************
Publishing a Graph
******************

This guide shows how to publish a graph so it can be referenced by other sessions. Similarly, the snapshots of a graph can also be made available to other sessions.

Recap: Loading a graph
----------------------

At first you need to load a graph.

.. code-block:: python
    :linenos:

    session = pypgx.get_session(session_name="new_session")
    graph = session.read_graph_with_properties(
        self.graph_path,
        graph_name="mygraph"
    )

The chosen graph name needs to be unique within the session.

Publishing a graph with snapshots
---------------------------------

Now that you have a loaded graph, you can publish it and all its current and future snapshots via the :meth:`read_graph_with_properties()` method, which makes all the graph snapshots available to all sessions under the same name, regardless of how snapshots are added to the graph.
When a graph is published with snapshots, the ``GraphMetaData`` information of each snapshot is also made available to the other sessions, with the exception of the graph configuration, which is ``None``.

With publishing, all persistent properties of all snapshots are also published and made visible to the other sessions, while transient properties are session-private and thus should be published explicitly for an explanation of properties types). Once published, all properties become read-only.
Hence, **transient properties are not published** when calling :meth:`read_graph_with_properties()` without arguments.

Publishing a graph will move the graph name from the session-private namespace to the public namespace; for more information about namespaces. If a graph with the same name has been published already, the :meth:`publish_with_snapshots()` method will fail with an exception.

.. code-block:: python
    :linenos:

    graph.publish_with_snapshots()

Publishing a single graph snapshot
----------------------------------

PGX offers a separate :meth:`publish()` API to only publish one specific snapshot of a graph.
This method will only make the current snapshot of that graph visible to other sessions.

As with :meth:`publish_with_snapshots()`, calling :meth:`publish()` without arguments publishes the snapshot with its persistent properties but **does not publish transient properties**.

Similarly to publishing with snapshots, this operation will move the graph name from the session-private namespace to the public namespace.
If a graph with the same name has been already published, the :meth:`publish()` method will fail with an exception.
Note that graphs published with snapshots and single published snapshots share the same namespace.

.. code-block:: python
    :linenos:

    graph.publish()

If you want to publish specific transient properties, you should list them within the :meth:`publish()` call.

.. code-block:: python
    :linenos:

    prop = graph.create_vertex_property("integer", "prop1")
    prop.fill(0)
    cost = graph.create_edge_property("double", "cost")
    cost.fill(0.0)
    vertex_props = [prop]
    edge_props = [cost]
    graph.publish(vertex_props, edge_props)

Referencing a published graph from another session
--------------------------------------------------

Other sessions can reference a published graph by its name via the :meth:`get_graph()` method of the session object.

.. code-block:: python
    :linenos:

    session2 = pypgx.get_session(session_name="session2")
    graph2 = session2.get_graph("my_graph")

``session2`` now has a reference to the published graph of ``session1`` called ``my_graph``.
If the graph has been published without snapshots, ``session2`` can see only the published snapshot.

Instead, if also the snapshots have been published, the call to :meth:`get_graph()` returns the most recent snapshot available.

As for every graph you reference, you should remember to release it when you do not need it anymore, as explained in the :ref:`Graph Deletion <graph-deletion>` section.

Publishing a property
---------------------

After publishing (a single snapshot or all of them), you can still publish transient properties individually:

.. code-block:: python
    :linenos:

    graph.get_vertex_property("prop1").publish()
    graph.get_edge_property("cost").publish()

Note that, as before, the published properties are associated to the specific snapshot they have been created on and thus visible only on that snapshot.

Getting a published property in another session
-----------------------------------------------

Sessions referencing a published graph (with or without snapshots) can reference a published property via the usual :meth:`getVertexProperty` / :meth:`get_edge_property` calls of :class:`PgxGraph`.

.. code-block:: python
    :linenos:

    session2 = pypgx.get_session(session_name="session2")
    graph2 = session2.get_graph("my_graph")
    vertex_property = graph2.get_vertex_property("prop1")
    edge_property = graph2.get_edge_property("cost")

``session2`` now has a reference to the published graph of ``session1`` called ``my_graph`` and can reference its published properties via ``my_graph`` itself.