GH-2537 - Improve documentation.

Author: michael-simons

src/main/asciidoc/appendix/custom-queries.adoc

@@ -359,7 +359,10 @@ All properties - and type of relationships - appear in those maps as they would
 have been written by SDN.
 Values will have the correct Cypher type and won't need further conversion.
 
-All relationships are lists of maps. Dynamic relationships will be resolved accordingly.
+TIP: All relationships are lists of maps. Dynamic relationships will be resolved accordingly.
+     One-to-one relationships will also be serialized as singleton lists. So to access a one-to-one mapping
+     between people, you would write this das `$person.\\__properties__.BEST_FRIEND[0].\\__target__.\\__id__`.
+
 If an entity has a relationship with the same type to different types of others nodes, they will all appear in the same list.
 If you need such a mapping and also have the need to work with those custom parameters, you have to unroll it accordingly.
 One way to do this are correlated subqueries (Neo4j 4.1+ required).

src/test/java/org/springframework/data/neo4j/integration/issues/IssuesIT.java

@@ -186,11 +186,15 @@ private static void setupGH2210(QueryRunner queryRunner) {
 	}
 
 	private static void setupGH2323(QueryRunner queryRunner) {
-		personId = queryRunner.run("CREATE (n:Person {id: randomUUID(), name: 'Helge'}) return n.id").single()
-				.get(0)
-				.asString();
 		queryRunner.run("unwind ['German', 'English'] as name create (n:Language {name: name}) return name")
 				.consume();
+		personId = queryRunner.run("""
+						MATCH (l:Language {name: 'German'})
+						CREATE (n:Person {id: randomUUID(), name: 'Helge'}) -[:HAS_MOTHER_TONGUE]-> (l)
+						return n.id"""
+				).single()
+				.get(0)
+				.asString();
 	}
 
 	private static void setupGH2459(QueryRunner queryRunner) {
@@ -439,6 +443,21 @@ void ensureRelationshipsAreSerialized(@Autowired PersonService personService) {
 		});
 	}
 
+	@Test
+	@Tag("GH-2537")
+	void ensure1To1RelationshipsAreSerialized(@Autowired PersonService personService) {
+
+		Optional<Person> optionalPerson = personService.updateRel3(personId);
+		assertThat(optionalPerson).isPresent().hasValueSatisfying(person -> {
+
+			assertThat(person.getKnownLanguages()).hasSize(1);
+			assertThat(person.getKnownLanguages()).first().satisfies(knows -> {
+				assertThat(knows.getDescription()).isEqualTo("Whatever");
+				assertThat(knows.getLanguage()).extracting(Language::getName).isEqualTo("German");
+			});
+		});
+	}
+
 	@Test
 	@Tag("GH-2326")
 	void saveShouldAddAllLabels(@Autowired AnimalRepository animalRepository,

src/test/java/org/springframework/data/neo4j/integration/issues/gh2323/Person.java

@@ -37,6 +37,9 @@ public class Person {
 	@Relationship("KNOWS")
 	private List<Knows> knownLanguages = new ArrayList<>();
 
+	@Relationship("HAS_MOTHER_TONGUE")
+	private Knows motherTongue;
+
 	public Person(String name) {
 		this.name = name;
 	}

src/test/java/org/springframework/data/neo4j/integration/issues/gh2323/PersonRepository.java

@@ -49,4 +49,15 @@ RETURN f, collect(r), collect(t)
 			"""
 	)
 	Person updateRel2(@Param("person") Person person);
+
+	@Query("""
+			MATCH (f:Person {id: $person.__id__})
+			MATCH (mt:Language {name: $person.__properties__.HAS_MOTHER_TONGUE[0].__target__.__id__})
+			MATCH (f)-[frl:HAS_MOTHER_TONGUE]->(mt) WITH f, frl, mt
+			UNWIND $person.__properties__.KNOWS As rel WITH f, frl, mt, rel
+			MATCH (t:Language {name: rel.__target__.__id__})
+			MERGE (f)- [r:KNOWS {description: rel.__properties__.description}] -> (t)
+			RETURN f, frl, mt, collect(r), collect(t)
+			""")
+	Person updateRelWith11(@Param("person") Person person);
 }

src/test/java/org/springframework/data/neo4j/integration/issues/gh2323/PersonService.java

@@ -55,4 +55,15 @@ public Optional<Person> updateRel2(String id, List<String> languageNames) {
 
 		return original;
 	}
+
+	public Optional<Person> updateRel3(String id) {
+		Optional<Person> original = personRepository.findById(id);
+		if (original.isPresent()) {
+			Person person = original.get();
+			person.setKnownLanguages(List.of(new Knows("Whatever", new Language("German"))));
+			return Optional.of(personRepository.updateRelWith11(person));
+		}
+
+		return original;
+	}
 }