PGX 21.1.1

Namespaces and Sharing

PGX supports referring to entities (e.g., graphs, properties) by name. Since multiple sessions can refer to entities by name, there could be cases in which different sessions want to use the same name for different entities. Since version 19.4.0, PGX supports separate namespaces: the name of an entity lives in a certain namespace where it must be unique, but different namespaces can contain entities with the same name.

For example, for graph names each session has its own session-private namespace and can choose any name without affecting other sessions, nor can see the content of other private namespaces. In addition to the session-private namespace there is a public namespace for published graphs (e.g., published via the publishWithSnapshots() or the publish() methods).

Similarly, each published graph defines a public namespace for published properties as well as per-session, private namespaces, so that different sessions can create properties with the same name on a published graph. Private graphs only have a private namespace.

We illustrate more details focusing on graphs and then provide some additional details regarding properties; the same behavior applies to named entities as well.

Defining Graph Names

Graphs that are created in a session either through loading (e.g., readGraphWithProperties(), with the graph builder or through mutations will take up a name in the session-private namespace. A graph will be placed in the public namespace only through publishing (i.e., when calling the publishWithSnapshots() or the publish() methods). Publishing a graph will move its name from the session-private namespace to the public namespace.

There can only be one graph with a given name in a given namespace, but a name can be used in different namespaces to refer to different graphs. An operation that creates a new graph (e.g., readGraphWithProperties() will fail if the chosen name of the new graph already exists in the session-private namespace. Publishing a graph fails if there is already a graph in the public namespace with the same name.

Retrieving Graphs by Name

There are two ways to retrieve a graph by name: with or without explicitly mentioning the namespace.

With getGraph(Namespace, String), you need to provide the namespace (either session private or public); the graph then will be looked up in the given namespace only.

With getGraph(String), the provided name will be first looked up in the private namespace and, if no graph with the given name is found there, in the public one. In other words, if a graph with the same name is defined in both the public and the private namespaces, getGraph(String) will return the private graph and you need to use getGraph(Namespace, String) to get hold of the public graph with that name.

Checking Used Names

To see the currently used names in a namespace you can use the PgxSession.getGraphs(Namespace) method, which will list all the names in the given namespace. The names in the returned collection can be used in a getGraph(Namespace, String) call to retrieve the corresponding PgxGraph.

Property Name Resolution and Graph Mutations

Property names behave in a similar way as graph names. All property names of a non-published graph are in the session-private namespace. Once a graph is published with PgxGraph.publishWithSnapshots() or the PgxGraph.publish() methods), its properties are published as well and their names move into the public namespace.

Once a graph is published, newly created properties will still be private to the session and their names will be in the private namespace. Those properties can be published individually with the Property.publish() method, as long as no other property with the same name is already published for that graph.

Additionally, new private properties can be created with the same name of an already-published properties (since the names are part of separate namespaces). To handle such situations and retrieve the correct property, the PGX API offers the getVertexProperty(Namespace, String) and the getEdgeProperty(Namespace, String) methods, which allow specifying the namespace where the property name should be looked up. Similarly to graphs, if you search a property without specifying the namespace, the private namespace is searched first and the search proceeds to the public namespace only if the former fails; this is the case, for example, for the getVertexProperty(String) or the getEdgeProperty(String) methods and for PGQL queries).

Likewise, when a mutation on a graph reads or writes a property referred to by name and two properties exist with the same name, the property in the private namespace is selected. To override the default selection, some mutation mechanisms accept a collection of specific Property objects to be copied into the mutated graph. For example, such mechanism is supported for filter expressions; see the Creating Subgraphs page for more details.