Deprecation of legacy numeric IDs by Neo4j 5

[johannessen]

Neo4j 5 deprecates the numeric IDs used as entity table key by Neo4p.

Regrettably, Jolt v2 has already removed the numeric IDs entirely (unlike Bolt v5, which provides both the legacy numeric ID and the new element ID). While it isn’t hard to determine the numeric ID from an element ID in Neo4j 5.3, doing so relies on undocumented behaviour that explicitly is subject to change in future Neo4j versions. This puts me in a bit of a bind, because I have no control over if or when the id() method will start to fail for users of the driver.

I’d like to add a deprecation warning to id() sooner rather than later to get people to change their code to use element_id() instead. However, I’m not sure how feasible it would be to change Neo4p to use string-based IDs.

Continuing use of the legacy numeric ID and just slapping no warnings qw(deprecated); all over Neo4p’s Neo4j::Driver agent should be an easy short term fix, but might well cause issues later on when/if a future Neo4j version changes in a way that prevents the driver from determining the legacy ID.

@majensen How would you like to handle this for Neo4p?

[majensen]

Hey @johannessen - thanks for this heads-up. For any work on Neo4p going forward, I'm going to depend on what Neo4j::Driver does. (I pretty much think of Neo4p as resting in peace - although as long as tests pass using Neo4j::Driver, it can linger on.) Thinking back, I guess that the object model depends on the IDs under the hood - the Neo4p objects are blessed scalars whose value is the id. I'm thinking that string IDs might just pass through and work, but I will have a look. In this case, I can probably kludge in the use of element_id in this context when Neo4j::Driver is the "agent".

BTW- where is the Bolt 5+ specification nowadays? I discovered that 7687.org went away.

[johannessen]

Right. I imagine Neo4p itself might handle it fine. Users who retrieve numeric IDs from e. g. as_simple->{_node} could be in trouble though: If they currently feed those IDs back into Cypher queries using id(), the string element ID wouldn’t do them much good.

The Bolt spec is now available at https://neo4j.com/docs/bolt/current/bolt/.

[johannessen]

A quick update: I think id() only warning when a Neo4j 5 connection does in fact provide the new element ID is the right choice. This behaviour differs from that of the official Neo4j drivers. But they don’t target earlier Neo4j versions. We do.

Neo4j-Driver-0.37-TRIAL implements just that. id() doesn’t warn on Neo4j 4 and earlier.

---

@majensen Given what you said earlier about Neo4p “resting in peace,“ my suggestion would be to consider the following course of action:

• Add a caution that Neo4p is designed for Neo4j 4.x and below, and that there is no guarantee of support for Neo4j 5.whatever and above to the POD documentation; perhaps in a “Bugs and Limitations” section.
• Add { no warnings 'deprecated'; ... } to the following places to silence warnings that may be issued by id(), start_id(), end_id() in Neo4j::Driver 0.37+ on Neo4j 5:
  • new_from_json_response() in REST::Neo4p::Entity
  • simple_from_json_response() in REST::Neo4p::Node
  • simple_from_json_response() in REST::Neo4p::Relationship
  • new_from_driver_obj() in REST::Neo4p::Path
  • REST/Neo4p/Agent/Neo4j/ResultProcessor.pm
  • possibly others that I missed

This should be a relatively simple way to keep the most basic functionality of Neo4p working fine on Neo4j 5 for a while. I could offer a patch if you like.

That said, when running the Neo4p test suite against a live Neo4j 5 server, I also noticed a bunch of failures related to Cypher syntax changes related to indexes. See the list of removed Neo4j procedures for details about those.

[majensen]

@johannessen thanks for this analysis - this shouldn't be too hard to update.
FWIW, I'm working on the libneo4j_client fork to add in parsing for all the structure-based types (dates, times, points). I will also see about dealing with entity_id in that code as well (for >=5)