14.8.1 Configuring the Snapshots Source

Snapshots can be created from two sources: Refreshing and ChangeSet.

Refreshing is available for graphs that are read from a persistent data source, that is, a file. When the data source has changed with respect to the version stored in the graph server (PGX), it can be read again manually by calling the PgxSession.readGraphWithProperties() method. Similarly, if auto-refresh is set for the graph, the graph server (PGX) automatically reads the data source and creates new snapshots when the data source has changed.

Instead, a ChangeSet is a set of changes to a graph that the user creates and populates via the PGX ChangeSet API. Once a ChangeSet is created and populated with the desired changes, the user can simply call GraphChangeSet.buildNewSnapshot() to create a new snapshot for the graph. In this way, you are empowered to integrate changes coming from any source into the graph and build snapshots out of them.

Only one source of snapshots is allowed for a single graph and is chosen during graph configuration via the snapshots_source option, which can be set to either REFRESH or CHANGE_SET. In case the snapshots_source option is not explicitly set by the user, the following default settings apply:

• If the graph is from a persistent data source, the default value is REFRESH, so that snapshots can be created only by calling PgxSession.readGraphWithProperties() (or via auto-refresh, if configured).
• If the graph is transient, that is, built from a graph builder, the default value is CHANGE_SET, since the graph is not backed by a persistent data source from which changes can be read. It is for this reason, CHANGE_SET is the only admissible value for transient graphs.

Additionally, the following restrictions apply:

• If auto-refresh is enabled, then snapshots come from reading the backing data source and hence only REFRESH is admissible for the snapshots_source option.
• If the user attempts to create snapshots in a way that is different from the configuration (for example, by calling GraphChangeSet.buildNewSnapshot() when the graph's snapshots_source is REFRESH), the operation is invalid and an exception is thrown.