Skip to content

Add tabbed examples for multiple node IDs #2512

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: dev
Choose a base branch
from
Open

Add tabbed examples for multiple node IDs #2512

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2b7a92c
Add tabbed examples for multiple node IDs
NataliaIvakina Jul 30, 2025
7e67dee
Fix syntax mistake
NataliaIvakina Jul 30, 2025
62e4c48
Update import.adoc
NataliaIvakina Jul 30, 2025
37596e2
Apply suggestions from code review
NataliaIvakina Jul 30, 2025
b08d0f8
Update modules/ROOT/pages/import.adoc
NataliaIvakina Jul 30, 2025
f412d23
Update modules/ROOT/pages/import.adoc
NataliaIvakina Jul 30, 2025
0519f55
Update import.adoc
NataliaIvakina Jul 30, 2025
cfddffc
Update import.adoc
NataliaIvakina Aug 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 65 additions & 15 deletions modules/ROOT/pages/import.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1464,39 +1464,64 @@ Now use the previously defined ID spaces when connecting the actors to movies.
== Using multiple node IDs

A node header can contain multiple `ID` columns.
The relationship data must then use a matching number of `START_ID` / `END_ID` columns as references to the composite value of those ID columns.

Starting from 2025.07, the relationship data must then use a matching number of `START_ID` / `END_ID` columns as references to the composite value of those ID columns.
Copy link
Collaborator Author

@NataliaIvakina NataliaIvakina Jul 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this true? If I read the comments for the https://github.com/neo-technology/neo4j/pull/31617 correctly, it is still allowed to use a single :START_ID/:END_ID to refer to a composite ID.

But it is not allowed to mix how to refer to composite IDs. Either all references must use a single :START_ID/:END_ID columns, or a matching amount.

I think this should be reflected on this page too.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While you're right that it is still allowed to use a single :START_ID/:END_ID to refer to a composite ID, we don't want to document that behavior necessarily. It was never really meant to work that way and it is only still possible to not break potential usages of this behavior.

We want to encourage using a matching number of START_ID / END_ID columns and the other possibility was not meant to exist and should therefor IMO not be documented.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good. I understand your intention, but the trick here is that the Operations manual covers also earlier versions of Neo4j (2025.01-2025.06), in which you cannot use matching number of START_ID / END_ID columns. If a user is on 2025.02 and tries to follow the current example, he will get an error. Am I right?

Therefore we have to say that this functionality is available starting from 2025.07 and provide tabbed examples for earlier versions and for 2025.07.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I guess that makes sense.

This implies using `string` as `id-type`.

For each `ID` column, you can specify to store its values as different node properties.
However, the composite value cannot be stored as a node property.

[NOTE]
[IMPORTANT]
====
Incremental import doesn't support the use of multiple node identifiers.
This functionality is only available with a full import.
====


.Define multiple IDs as node properties
====
You can define multiple `ID` columns in the node header.
For example, you can define a node header with two `ID` columns.
=== Define multiple IDs as node properties

. Define multiple `ID` columns in the node header.
+
.nodes_header.csv
[source, csv]
----
:ID,:ID,name
----

+
.nodes.csv
[source, csv]
----
aa,11,John
bb,22,Paul
----

. Define the relationship between two established nodes.
+
[.tabbed-example]
=====
[role=include-with-single-ID-column]
======

Now use both IDs when defining the relationship:

.relationships_header.csv
[source, csv]
----
:START_ID,:TYPE,:END_ID
----

.relationships.csv
[source, csv]
----
aa11,WORKS_WITH,bb22
----

======
[role=include-with-multiple-ID-columns label--new-2025.07]
======

Starting from 2025.07, you have to use a matching number of `START_ID` / `END_ID` columns when defining the relationship:
Copy link
Collaborator Author

@NataliaIvakina NataliaIvakina Jul 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Starting from 2025.07, you have to use a matching number of `START_ID` / `END_ID` columns when defining the relationship:
Starting from 2025.07, you can use a matching number of `START_ID` / `END_ID` columns when defining the relationship.
However, do not mix how to refer to composite IDs.
Either all references must use a single `START_ID` / `END_ID` column or a matching number of them.


.relationships_header.csv
[source, csv]
----
Expand All @@ -1508,28 +1533,51 @@ Now use both IDs when defining the relationship:
----
aa,11,WORKS_WITH,bb,22
----
====
======
=====

[[multiple-IDs-Id-spaces]]
.Define multiple IDs stored in ID spaces
====

Define a `MyGroup` ID space in the _nodes_header.csv_ file.
=== Define multiple IDs stored in ID spaces

. Define a `MyGroup` ID space in the _nodes_header.csv_ file.
+
.nodes_header.csv
[source, csv]
----
personId:ID(MyGroup),memberId:ID(MyGroup),name
----

+
.nodes.csv
[source, csv]
----
aa,11,John
bb,22,Paul
----

Now use the defined ID space when connecting John with Paul, and use both IDs in the relationship.
. Now use the defined ID space when connecting John with Paul, and use both IDs in the relationship.
+
[.tabbed-example]
=====
[role=include-with-single-ID-column]
======

.relationships_header.csv
[source, csv]
----
:START_ID(MyGroup),:TYPE,:END_ID(MyGroup)
----

.relationships.csv
[source, csv]
----
aa11,WORKS_WITH,bb22
----

======
[role=include-with-multiple-ID-columns label--new-2025.07]
======

Starting from 2025.07, you have to use a matching number of `START_ID` / `END_ID` columns when defining the relationship:

.relationships_header.csv
[source, csv]
Expand All @@ -1542,7 +1590,9 @@ Now use the defined ID space when connecting John with Paul, and use both IDs in
----
aa,11,WORKS_WITH,bb,22
----
====
======
=====


[[import-tool-id-types-header]]
== Storing a different value type for IDs in a group
Expand Down