*********************************************
Managing Transient Properties and Collections
*********************************************

PGX allows each client to maintain its own isolated workspace, called
``session``. Clients may create additional data objects in their own session, which they can then use for analysis.

Transient Properties
--------------------

PGX adopts the Property Graph data model. Once a graph is loaded into PGX, the graph instance itself and its original properties are set as immutable. However, the client can create and attach additional properties to the graph dynamically. These extra properties are referred to as ``transient`` properties and are mutable by the client.

The methods for creating transient properties are available in :class:`PgxGraph`:

.. code-block:: python
    :linenos:

    graph.create_vertex_property(data_type="string", name=None)

The ``data_type`` argument is an enum for the data type of the property, which must be one of the primitive types
supported by PGX.

``name`` is an optional argument to assign a unique name to the newly created property. If no name is specified, PGX will assign one to the client. Note that names must be unique. There cannot be two different vertex/edge properties for the same graph and with the same name.

All methods return a :class:`PgxProperty` object, which represent the newly created transient property. Both of the underlying classes, :class:`VertexProperty` and :class:`EdgeProperty`, are parametrized with the value type ``V`` the property holds.
``V`` matches the given :class:`PgxProperty`. :class:`VertexProperty` is additionally parametrized with the vertex ID type. This is due to PGX support of several types of vertex identifiers.
:class:`EdgeProperty` is not parameterized with the edge ID type, because PGX only supports edge identifiers of type ``long``.

Example:

.. code-block:: python
    :linenos:

    graph = session.read_graph_with_properties(self.cfg)
    p1 = graph.create_vertex_property("string", name=None)
    p2 = graph.create_edge_property("double")

To delete a transient property from the session, call :meth:`destroy()` on the property object.

Collections and Scalars
-----------------------

The client can create graph-bound vertex and edge collections to use during the analysis with the following methods in :class:`PgxGraph`:

.. code-block:: python
    :linenos:

    vertices = [graph.get_random_vertex()]
    edges = [graph.get_random_edge()]

    vertex_sequence = graph.create_vertex_sequence('vertexSequence')
    vertex_sequence.add_all(vertices)

    vertex_set = graph.create_vertex_set('vertexSet')
    vertex_set.add_all(vertices)

    edge_sequence = graph.create_edge_sequence('edgeSequence')
    edge_sequence.add_all(edges)

    edge_set = graph.create_edge_set('edgeSet')
    edge_set.add_all(edges)

PGX also supports scalar collections such as ``set`` and ``sequence``. Each of these collections can hold elements of various primitive data types like `INTEGER`, `FLOAT` or `BOOLEAN`. Scalar collections are session-bound and can be created with the following methods in :class:`PgxSession`:

.. code-block:: python
    :linenos:

    content_type = "integer"
    session.create_set(content_type, name=None)
    session.create_sequence(content_type, name=None)

The optional argument (``name``) specifies the name of the newly created collection.
If omitted, PGX chooses a name for the client. As with properties, the collections holding vertices are parametrized with the ID type of the vertices.

The return value is the collection object which points to the newly created empty collection.

To drop a collection from the session, call :meth:`destroy()` on the collection object.

To check which collections are currently allocated for a graph you can use the following method:

.. code-block:: python
    :linenos:

    collections = graph.get_collections()

The returned map contains the names of the collections as keys and the collections as values. The collections can be casted to the matching collection subclass.

PGX supports special ``Map`` collection types and allows users to map between different data types.
Maps can be created using :class:`PgxGraph` or :class:`PgxSession` APIs, the difference is that the latter supports only non graph-related types, and that the created maps directly depend on the session:

.. code-block:: python
    :linenos:

    key_type = "integer"
    value_type = "integer"
    data_type = "integer"
    graph.create_map(key_type, value_type, name=None)

Similarly, scalar variables can be created in the client session using the following methods:

.. code-block:: python
    :linenos:

    graph.create_scalar(data_type, name=None)

These collections and scalar variables can then be passed as arguments to graph algorithms.