docs: updated documentation

documentation/user/en/use/api/example/imperative-schema-definition.java

@@ -1,6 +1,11 @@
 evita.updateCatalog(
 	"testCatalog",
 	session -> {
+
+		/* first create stubs of the entity schemas that the product will reference */
+		session.defineEntitySchema("Brand");
+		session.defineEntitySchema("Category");
+
 		session.defineEntitySchema("Product")
 			/* all is strictly verified but associated data
 			   and references can be added on the fly */

documentation/user/en/use/api/example/parent-class.java

@@ -0,0 +1,20 @@
+@Data
+public class MyEntity {
+
+	// contains id of parent entity, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable private final Integer parentId(),
+
+	// contains parent entity, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable private final SealedEntity parentEntity(),
+
+	// contains reference to a parent entity, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable private final EntityReference parentEntityReference(),
+
+	// contains reference to a parent wrapped in this interface, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable private final MyEntity parentMyEntity()
+
+}

documentation/user/en/use/api/example/parent-interface.java

@@ -0,0 +1,35 @@
+public interface MyEntity {
+
+	// return id of parent entity, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable Integer getParentId();
+
+	// return optional id of parent entity, or empty if this entity is a root entity
+	@ParentEntity
+	@Nonnull OptionalInt getParentIdIfNotRoot();
+
+	// return parent entity, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable SealedEntity getParentEntity();
+
+	// return optional parent entity, or empty if this entity is a root entity
+	@ParentEntity
+	@Nonnull Optional<SealedEntity> getParentEntityIfNotRoot();
+
+	// return reference to a parent entity, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable EntityReference getParentEntityReference();
+
+	// return optional reference to a parent entity, or empty if this entity is a root entity
+	@ParentEntity
+	@Nonnull Optional<EntityReference> getParentEntityReferenceIfPresent();
+
+	// return reference to a parent wrapped in this interface, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable MyEntity getParentMyEntity();
+
+	// return optional reference to a parent wrapped in this interface, or empty if this entity is a root entity
+	@ParentEntity
+	@Nonnull Optional<MyEntity> getParentMyEntityIfPresent();
+
+}

documentation/user/en/use/api/example/parent-record.java

@@ -0,0 +1,18 @@
+public record MyEntity(
+	// contains id of parent entity, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable Integer parentId(),
+
+	// contains parent entity, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable SealedEntity parentEntity(),
+
+	// contains reference to a parent entity, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable EntityReference parentEntityReference(),
+
+	// contains reference to a parent wrapped in this interface, or null if this entity is a root entity
+	@ParentEntity
+	@Nullable MyEntity parentMyEntity()
+) {
+}

documentation/user/en/use/api/query-data.md

@@ -366,7 +366,22 @@ TODO JNO - Work in progress
 
 #### Hierarchy
 
-TODO JNO - Work in progress
+To access the placement information of the entity or hierarchy (i.e., its parent), you must use either the numeric data 
+type, your own custom interface type, <SourceClass>evita_api/src/main/java/io/evitadb/api/requestResponse/data/SealedEntity.java</SourceClass> 
+or <SourceClass>evita_api/src/main/java/io/evitadb/api/requestResponse/data/structure/EntityReference.java</SourceClass> 
+data type and annotate it with the `@ParentEntity` annotation. The datatype can be wrapped in 
+[Optional](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Optional.html) 
+(or its counterparts [OptionalInt](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/OptionalInt.html) 
+or [OptionalLong](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/OptionalLong.html)).
+
+<SourceAlternativeTabs variants="interface|record|class">
+
+[Example interface with parent access](/documentation/user/en/use/api/example/parent-interface.java)
+
+</SourceAlternativeTabs>
+
+The method may return null if the entity is a root entity. Therefore, it's not recommended to use primitive data types, 
+because the method call may fail with a `NullPointerException` in such a case.
 
 #### References
 

evita_functional_tests/src/test/java/io/evitadb/documentation/UserDocumentationTest.java

@@ -359,7 +359,7 @@ Stream<DynamicNode> testDocumentation() throws IOException {
 	Stream<DynamicTest> testSingleFileDocumentation() {
 		return this.createTests(
 			DocumentationProfile.DEFAULT,
-			getRootDirectory().resolve("documentation/user/en/operate/monitor.md"),
+			getRootDirectory().resolve("documentation/user/en/use/api/schema-api.md"),
 			ExampleFilter.values()
 		).stream();
 	}