Configuring data-sources: Alternative IDs

Note: alternative IDs are only supported with Neo4j

When you save a visualization in Linkurious Enterprise, only the node and edge identifier are persisted in the user-data store, along with position and style information. When a visualization is loaded, the node and edge identifiers are used to reload the actual node and edge data from the graph database.

If you need to re-generate your graph database from scratch, the graph database will probably generate new identifiers for all nodes and edges, breaking all references to nodes and edges in existing visualizations.

Using a property as a stable identifier

You can configure Linkurious Enterprise to use a node or edge property as stable identifiers. Once set-up, Linkurious Enterprise will use the given property as identifier instead of using the identifiers generated by the database.

Thanks to this strategy, visualizations will be robust to graph re-generation.

Notice that the properties used as identifier should be indexed by the database to allow for a fast lookup by value.

Alternative identifiers configuration

To use alternative node and edge identifiers, edit your data-source database configuration in the configuration file (linkurious/data/config/production.json):

Example of alternative identifier configuration with Neo4j:

{
  "dataSources": [
    {
      "graphdb": {
        "vendor": "neo4j",
        "url": "http://127.0.0.1:7474/",
        "alternativeNodeId": "STABLE_NODE_PROPERTY_NAME",
        "alternativeEdgeId": "STABLE_EDGE_PROPERTY_NAME"
      }
      // [...]
    }
  ]
}

If you plan on using a compatible Neo4J version and alternative IDs, we recommend configuring alternative IDs indices.

To achieve better performance with alternative IDs is recommended to configure indices for alternative node and edge IDs.

Please note that the node or edge property used as an alternative ID must have string values. Other types (typically integers) are not supported. This is needed because the alternative IDs indices are FULLTEXT ones and can thus only index string values.

Refer to the documentation specific to Neo4j on how to configure these indices.

Enabling or disabling alternative IDs without breaking references

Enabling or disabling alternative IDs will change the nodes and edges IDs, and thus break references in Linkurious Enterprise's user-data store. As a consequence, enabling or disabling alternative IDs without following the proper steps will cause all existing visualizations and alert cases to become either empty or filled with the wrong nodes and edges.

ℹ️ If you don't have any saved visualization or case, you can safely skip this section as your system does not store any reference yet.

To enable or disable alternative IDs without breaking references in Linkurious Enterprise, the alternativeIdsMigration script is available to migrate the content of Linkurious Enterprise's user-data store.

The alternativeIdsMigration script has two commands:

• enable, to enable alternative IDs and migrate the content of Linkurious Enterprise's user-data store to use the alternative IDs instead of the internal Neo4j IDs. This command expect the name of the alternative ID node and edge properties in its command line arguments. If alternative IDs are configured before running the enable command, it's going to print a warning and abort.
• disable, to disable alternative IDs and migrate the content of Linkurious Enterprise's user-data store to use the internal Neo4j IDs. The disable command can always be run, no matter if alternative IDs are configured or not. This can be handy to clean-up the Linkurious user-data-store if the migration goes wrong.

You should be able to see the documentation of the alternativeIdsMigration script by running it without any argument:

• On Docker

  docker run --rm --mount type=bind,src=/path/to/my/data/folder,dst=/data linkurious:4.3.2 node /usr/src/linkurious/system/scripts/alternativeIdsMigration` (don't forget to replace `/path/to/my/data/folder` to your data folder, or you can use any other volume configuration that mounts the data folder)
  

• On Linux

  • From the Linkurious Enterprise installation directory ./alternativeIdsMigration.sh

• On macOS

  • From the Linkurious Enterprise installation directory ./alternativeIdsMigration.sh.command

• On Windows

  • From the Linkurious Enterprise installation directory ./alternativeIdsMigration.bat

• You should see: "Usage: alternativeIdsMigration [command] [options] (...)" and more documentation about the script.

• You can get more help with a command by running ./alternativeIdsMigration.sh [command] --help (e.g. ./alternativeIdsMigration.sh enable --help)

⚠️ For big databases, the execution time of the scripts could be very long.

Please follow these steps to enable alternative IDs:

1. Stop Linkurious Enterprise

2. Run the alternativeIdsMigration script with the enable command and the right arguments:

   • run (adapt this according to your OS) ./alternativeIdsMigration.sh enable --help to understand which arguments to set
   • example: ./alternativeIdsMigration.sh enable --alternative-node-id myAlternativeNodeId --alternative-edge-id myAlternativeEdgeId
   • ⚠️ You should see this message: "Alternative IDs have been enabled successfully". If you do not see this message, please make sure you ran the command properly and contact support if needed.

3. Start Linkurious Enterprise

Please follow these steps to disable alternative IDs:

1. Stop Linkurious Enterprise

2. Run the alternativeIdsMigration script with the disable command (add disable as the end of the alternativeIdsMigration script documented above).

   • ⚠️ You should see this message: "Alternative IDs have been disabled successfully". If you do not see this message, please make sure you ran the command properly and contact support if needed.

3. Start Linkurious Enterprise