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
publishWithSnapshots() or the
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.
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
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.
There are two ways to retrieve a graph by name: with or without explicitly mentioning the namespace.
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.
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.
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
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
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.