Revamp of the LOAD CSV tutorial #470

lidiazuin · 2025-05-06T11:10:37Z

Review of the csv-import.adoc page and addition of the csv-file.adoc page for general reference.

AlexicaWright

This a review of the "Working with CSV files" section. I'll have to review the tutorial separately.

modules/ROOT/pages/data-import/csv-files.adoc

AlexicaWright · 2025-05-06T12:16:20Z

modules/ROOT/pages/data-import/csv-files.adoc

+
+=== Data format
+
+All data from the CSV file is read as a string, so you need to use `toInteger()`, `toFloat()`, `split()`, or similar functions to convert values, when needed.


Suggested change

All data from the CSV file is read as a string, so you need to use `toInteger()`, `toFloat()`, `split()`, or similar functions to convert values, when needed.

Neo4j reads all data from the CSV file as a string, for other data types, you need to use `toInteger()`, `toFloat()`, `toBoolean()`, or similar functions to convert data to the appropriate type.

split() doesn't change the data type from string, but splits it into separate entities, so it feels odd to group it with the functions that changes the data type. It's mentioned later though, so maybe it's ok?

AlexicaWright · 2025-05-06T13:09:05Z

modules/ROOT/pages/data-import/csv-files.adoc

+=== Field terminator
+
+Also known as delimiter, a field terminator is a character used to separate each field in a CSV file.
+In this example, a comma (`,`) is used, but other characters, such as a tab (`\`) or a pipe (`|`) also work and they can be blended:


Suggested change

In this example, a comma (`,`) is used, but other characters, such as a tab (`\`) or a pipe (`|`) also work and they can be blended:

In this example, a comma (`,`) is used, but other characters, such as a tab (`\t`) or a pipe (`|`) also work and they can be blended:

Not sure if we need to escape the tab to make it render?
If you use a tab, the format is called TSV.

No, the tab is working normally here, both building locally and in Surge. Regarding the TSV file format, do you think it's better to mention it or to remove the tab option as it would make the file a TSV instead of a CSV, which is the topic of this page?

CSV and TSV are both flat files and there is no other difference AFAIK. About the tab, it's not just a forward slash but a t also \t.

modules/ROOT/pages/data-import/csv-files.adoc

AlexicaWright · 2025-05-08T13:44:06Z

modules/ROOT/pages/data-import/csv-files.adoc

+For best performance, always `MATCH` and `MERGE` on a single label with the indexed primary-key property.
+====
+
+Suppose you use xref:#_converting_data_values[the preceding *companies.csv* file], and now you have a file that contains people and which companies they work for:


Suggested change

Suppose you use xref:#_converting_data_values[the preceding *companies.csv* file], and now you have a file that contains people and which companies they work for:

Suppose that you have another file that contains people and which companies they work for using a reference to the xref:#_converting_data_values[*companies.csv* file:

AlexicaWright · 2025-05-08T13:55:21Z

modules/ROOT/pages/data-import/csv-files.adoc

+4,Karen White,1
+----
+
+You should also separate node and relationship creation on a separate processing.


Suggested change

You should also separate node and relationship creation on a separate processing.

To load these two files and create the appropriate relationships between the people from the `people.csv` file with the companies they work for in the `companies.csv` file, you need to load them both and first create nodes from the files, and then create the relationships between them.

To make this process more efficient, it is recommended to separate these tasks, i.e. create the nodes in one clause per file, and then a separate clause to create the relationships.

modules/ROOT/pages/data-import/csv-files.adoc

AlexicaWright · 2025-05-08T13:57:06Z

modules/ROOT/pages/data-import/csv-files.adoc

+
+[source,cypher,role=noplay]
+----
+// clear data


Is this necessary?

AlexicaWright · 2025-05-08T13:58:50Z

modules/ROOT/pages/data-import/csv-files.adoc

+MATCH (e:Employee {employeeId: row.employeeId})
+MATCH (c:Company {companyId: row.Company})
+MERGE (e)-[:WORKS_FOR]->(c)
+RETURN *;


What is returned here?

Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

modules/ROOT/pages/data-import/csv-import.adoc

Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

…rt subpage and admonition for GraphAcademy

…d into csv-import

AlexicaWright

Some further comments, but we're getting there! Thank you @lidiazuin !

modules/ROOT/pages/data-import/csv-files.adoc

AlexicaWright · 2025-06-03T11:39:47Z

modules/ROOT/pages/data-import/csv-files.adoc

+--
+
+Here, the movie and person data (including the IDs) is repeated in different rows every time new information about a particular actor's role is featured.
+This sort of duplication compromises the structure of the data, which means you need to xref:#_preparing_the_csv_file[prepare your file] before importing.


Maybe this can be rephrased a little? The duplication doesn't really compromise the structure of the data in general, does it? Only if you want your data in a graph structure.
Also, the link doesn't work.

modules/ROOT/pages/data-import/csv-files.adoc

modules/ROOT/pages/data-import/csv-import.adoc

AlexicaWright · 2025-06-03T13:34:48Z

modules/ROOT/pages/data-import/csv-import.adoc

+* xref:data-import/csv-files.adoc[*Working with CSV files*]: read about the structure of a CSV file and understand how data is organized.
+* xref:data-import/csv-files.adoc#_cleaning_up[*Cleaning up CSV files*]: see how to use the `LOAD CSV` command to clean up the file while importing.
+* xref:data-import/csv-files.adoc#_optimization[*Optimization*]: improve performance when working with large amounts of data or complex loading.


These three are all on the same page. Wouldn't it suffice to say "See xref:data-import/csv-files.adoc[Working with CSV files] to learn more about the structure of data, how to clean it up, and optimize it."?

modules/ROOT/pages/data-import/index.adoc

AlexicaWright · 2025-06-03T13:37:53Z

modules/ROOT/pages/data-import/index.adoc

+
 == Methods comparison

 The following table shows all supported methods for importing data into Neo4j:


The plot grows thicker.. In Desktop2, "Import" is available, but only for CSV. It is built-in so it's not standalone Data Importer...

You mean the Open folder > Import option?

No, Desktop2 has Importer built in, just like the Aura console, but it only supports csv files.

Is it already released? Because then I need to update this, I think

modules/ROOT/pages/data-import/csv-import.adoc

Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

AlexicaWright

Some more comments ;)

AlexicaWright · 2025-06-11T19:11:56Z

modules/ROOT/pages/data-import/index.adoc

+
 == Methods comparison

 The following table shows all supported methods for importing data into Neo4j:


No, Desktop2 has Importer built in, just like the Aura console, but it only supports csv files.

modules/ROOT/pages/data-import/csv-import.adoc

AlexicaWright · 2025-06-13T12:39:34Z

modules/ROOT/pages/data-import/csv-import.adoc

+[source,cypher]
+--
+LOAD CSV [WITH HEADERS] FROM url [AS alias] [FIELDTERMINATOR char]
+--


Suggested change

--

--

If you include the optional `WITH HEADERS`, the first line of the CSV file is treated as a header and each row is treated as a map of key-value pairs rather than a list of values.

`FROM` lets you specify the location whether it is local or over the internet and it cannot be omitted.

`AS alias` names each row for reference.

The default field terminator in CSV files is the comma, but others are supported and can be specified using the parsing option `FIELDTERMINATOR`.

This is just a suggestion, but since it is a tutorial about this command, I think it's worthwhile to break down the basic command and inform what each part does.

AlexicaWright · 2025-06-13T12:40:51Z

modules/ROOT/pages/data-import/csv-import.adoc

-//Example 2 - file placed in subdirectory within import directory (import/northwind/customers.csv)
-LOAD CSV FROM "file:///northwind/customers.csv"
----
+This is the content of the example `people.csv` file:


Maybe use the result of running that command instead?

AlexicaWright · 2025-06-13T12:41:30Z

modules/ROOT/pages/data-import/csv-import.adoc

-MERGE (c:Company {companyId: row.companyId})
-MERGE (e)-[r:WORKS_FOR]->(c)
----
+Note that the `FIELDTERMINATOR` wasn’t specified in the `LOAD CSV` clause because the default value is a comma. 


If you explain it on first mention, you can omit this. I added a suggestion for that.

modules/ROOT/pages/data-import/csv-import.adoc

AlexicaWright · 2025-06-13T12:49:41Z

modules/ROOT/pages/data-import/csv-import.adoc

+. Make sure header names match those in the CSV file.

-The `neo4j-admin database import` command can be used for the initial graph population only. 
+. Search for typos in the data and in the queries.


This seems like something to do once you know something is inaccurate?

AlexicaWright · 2025-06-13T12:53:45Z

modules/ROOT/pages/data-import/csv-import.adoc

-* Type conversion is possible by suffixing the name with indicators like `:INT`, `:BOOLEAN`, etc.
-
-For more details on this header format and the tool, see the section in the link:https://neo4j.com/docs/operations-manual/current/tools/neo4j-admin/neo4j-admin-import/[Neo4j Operations Manual -> Neo4j Admin import^] and the accompanying link:https://neo4j.com/docs/operations-manual/current/tutorial/neo4j-admin-import/[tutorial^].
+== Model your data


This section is very confusing. I suggest to delete it and link to the chapter on data modeling instead.

Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

AlexicaWright

Second part reviewed! Looking great Lidia!!

AlexicaWright · 2025-06-13T12:57:32Z

modules/ROOT/pages/data-import/csv-files.adoc

+
+=== Field terminator
+
+Also known as delimiter, a field terminator is a character used to separate each field in a CSV file.


Just a thought, but how would the LOAD CSV command work with more than one field terminator?

modules/ROOT/pages/data-import/csv-files.adoc

AlexicaWright · 2025-06-13T14:54:58Z

modules/ROOT/pages/data-import/csv-files.adoc

+RETURN row
+--
+
+Or from a local folder, if you use an on-premise deployment.


So this doesn't work in Aura? Maybe test to see?

AlexicaWright · 2025-06-13T14:57:21Z

modules/ROOT/pages/data-import/csv-files.adoc

+If you want to open your CSV file from another location, you need to change the link:https://neo4j.com/docs/operations-manual/2025.03/configuration/configuration-settings/#config_server.directories.import[`server.directories.import`] settings.
+
+[IMPORTANT]
+====


This is a very long admonition. Could it be shortened or rewritten as a regular paragraph (i.e. not an admonition)?

modules/ROOT/pages/data-import/csv-files.adoc

AlexicaWright · 2025-06-13T15:03:24Z

modules/ROOT/pages/data-import/csv-files.adoc

+
+* `*toInteger()*`: converts a value to an integer.
+* `*toFloat()*`: converts a value to a float (e.g. for monetary amounts).
+* `*datetime()*`: converts a value to a `DateTime`.


For consistency, we should either use code block for all data types or none. I suggest to use it for all of them. So string, float etc.

modules/ROOT/pages/data-import/csv-files.adoc

Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

lidiazuin · 2025-06-13T14:32:45Z

modules/ROOT/pages/data-import/index.adoc

+
 == Methods comparison

 The following table shows all supported methods for importing data into Neo4j:


Is it already released? Because then I need to update this, I think

lidiazuin · 2025-06-16T08:51:15Z

modules/ROOT/pages/data-import/csv-files.adoc

+RETURN row
+--
+
+Or from a local folder, if you use an on-premise deployment.


modules/ROOT/pages/data-import/csv-files.adoc

neo4j-docops-agent · 2025-06-18T09:08:35Z

Thanks for the documentation updates.

The preview documentation has now been torn down - reopening this PR will republish it.

AlexicaWright

Alright! Massive! Looks good! Well done @lidiazuin !

* Revamp of the LOAD CSV tutorial * Replacing links to neo4j admin commands to tutorial * Update index.adoc * Apply suggestions from code review Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * removing redundant tutorial for neo4j desktop and finalizing pages * remove unused images * reverting changes in apackage-lock * adding more info about modeling * Delete package-lock.json * Removing links to the Neo4j Desktop tutorial, adding link to the import subpage and admonition for GraphAcademy * fixes after review * Apply suggestions from code review Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * fixes after review * Apply suggestions from code review Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * updates after review * adding neo4j desktop to methods comparison --------- Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

* Revamp of the LOAD CSV tutorial (#470) * Revamp of the LOAD CSV tutorial * Replacing links to neo4j admin commands to tutorial * Update index.adoc * Apply suggestions from code review Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * removing redundant tutorial for neo4j desktop and finalizing pages * remove unused images * reverting changes in apackage-lock * adding more info about modeling * Delete package-lock.json * Removing links to the Neo4j Desktop tutorial, adding link to the import subpage and admonition for GraphAcademy * fixes after review * Apply suggestions from code review Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * fixes after review * Apply suggestions from code review Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * updates after review * adding neo4j desktop to methods comparison --------- Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com> * fixing broken links and removing unused image --------- Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

Revamp of the LOAD CSV tutorial

53b40ea

lidiazuin added the cherry-pick-this-to-main label May 6, 2025

lidiazuin and others added 3 commits May 6, 2025 13:32

Replacing links to neo4j admin commands to tutorial

9222473

Merge branch 'dev' into csv-import

8893148

Update index.adoc

a66c3d5

AlexicaWright reviewed May 8, 2025

View reviewed changes

Apply suggestions from code review

b7e1c6b

Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

AlexicaWright reviewed May 12, 2025

View reviewed changes

modules/ROOT/pages/data-import/csv-import.adoc Outdated Show resolved Hide resolved

modules/ROOT/pages/data-import/csv-import.adoc Outdated Show resolved Hide resolved

lidiazuin and others added 9 commits May 12, 2025 16:09

Apply suggestions from code review

cc382cf

Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

removing redundant tutorial for neo4j desktop and finalizing pages

f2594ff

remove unused images

90ab936

reverting changes in apackage-lock

b9fb1ed

adding more info about modeling

d547d6a

Delete package-lock.json

a623bfb

Removing links to the Neo4j Desktop tutorial, adding link to the impo…

245de5e

…rt subpage and admonition for GraphAcademy

Merge branch 'csv-import' of github.com:lidiazuin/docs-getting-starte…

67fc1b1

…d into csv-import

fixes after review

8628e29

AlexicaWright reviewed Jun 3, 2025

View reviewed changes

lidiazuin and others added 2 commits June 4, 2025 11:14

Apply suggestions from code review

e240038

Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

fixes after review

f63d9c4

AlexicaWright reviewed Jun 13, 2025

View reviewed changes

Apply suggestions from code review

9bf5d8a

Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

AlexicaWright reviewed Jun 13, 2025

View reviewed changes

Apply suggestions from code review

c4628db

Co-authored-by: Jessica Wright <49636617+AlexicaWright@users.noreply.github.com>

lidiazuin commented Jun 16, 2025

View reviewed changes

lidiazuin added 2 commits June 18, 2025 11:02

updates after review

9380168

adding neo4j desktop to methods comparison

0fe36e3

AlexicaWright approved these changes Jun 18, 2025

View reviewed changes

lidiazuin merged commit 99268a7 into neo4j:dev Jun 18, 2025
5 checks passed

lidiazuin deleted the csv-import branch June 18, 2025 09:12

lidiazuin mentioned this pull request Jun 18, 2025

Revamp of the LOAD CSV tutorial #470 #479

Merged


		=== Data format

		All data from the CSV file is read as a string, so you need to use `toInteger()`, `toFloat()`, `split()`, or similar functions to convert values, when needed.

	All data from the CSV file is read as a string, so you need to use `toInteger()`, `toFloat()`, `split()`, or similar functions to convert values, when needed.
	Neo4j reads all data from the CSV file as a string, for other data types, you need to use `toInteger()`, `toFloat()`, `toBoolean()`, or similar functions to convert data to the appropriate type.

	In this example, a comma (`,`) is used, but other characters, such as a tab (`\`) or a pipe (`\|`) also work and they can be blended:
	In this example, a comma (`,`) is used, but other characters, such as a tab (`\t`) or a pipe (`\|`) also work and they can be blended:

	Suppose you use xref:#_converting_data_values[the preceding companies.csv file], and now you have a file that contains people and which companies they work for:
	Suppose that you have another file that contains people and which companies they work for using a reference to the xref:#_converting_data_values[companies.csv file:

	You should also separate node and relationship creation on a separate processing.
	To load these two files and create the appropriate relationships between the people from the `people.csv` file with the companies they work for in the `companies.csv` file, you need to load them both and first create nodes from the files, and then create the relationships between them.
	To make this process more efficient, it is recommended to separate these tasks, i.e. create the nodes in one clause per file, and then a separate clause to create the relationships.


		== Methods comparison

		The following table shows all supported methods for importing data into Neo4j:

---
+--
+If you include the optional `WITH HEADERS`, the first line of the CSV file is treated as a header and each row is treated as a map of key-value pairs rather than a list of values.
+`FROM` lets you specify the location whether it is local or over the internet and it cannot be omitted.
+`AS alias` names each row for reference.
+The default field terminator in CSV files is the comma, but others are supported and can be specified using the parsing option `FIELDTERMINATOR`.


		=== Field terminator

		Also known as delimiter, a field terminator is a character used to separate each field in a CSV file.

Revamp of the LOAD CSV tutorial #470

Revamp of the LOAD CSV tutorial #470

Uh oh!

Conversation

lidiazuin commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AlexicaWright left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

AlexicaWright left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AlexicaWright left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexicaWright left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lidiazuin commented May 6, 2025 •

edited

Loading

neo4j-docops-agent commented Jun 18, 2025 •

edited

Loading