Skip to content

Commit 3253f07

Browse files
committed
Document the unfolding behaviour per #1964
1 parent 637bcdf commit 3253f07

File tree

1 file changed

+7
-2
lines changed
  • src/app/docs/schema-reference-guide

1 file changed

+7
-2
lines changed

src/app/docs/schema-reference-guide/page.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -976,10 +976,15 @@ The `@unfoldable` key is present with the value `[]` or it is not present.
976976

977977
In the document API, when retrieving documents, the default behavior is for any linked document to be returned as an IRI, while subdocuments are fully unfolded and returned as a nested document. With the `@unfoldable` option set, linked documents will behave just like subdocuments, and will also be unfolded on retrieval.
978978

979-
The `@unfoldable` option can only be set on a class which does not directly or indirectly link to itself. This prevents a self-referencing document from being unfolded infinitely.
980-
981979
The purpose of `@unfoldable` is to be able to treat linked (top-level) documents as subdocuments in representation. Subdocuments can only be linked by one document, its owner, whereas normal documents can be linked by any number of other documents. If the desired result is to have a document linked by several other documents, but still have it fully unfolded on retrieval like a subdocument, use this option.
982980

981+
#### Cycle detection
982+
The `@unfoldable` option can be set on any class. Fields with unfoldable class fields may even link back directly or indirectly, forming cycles.
983+
984+
Self-referencing documents are prevented from being unfolded infinitely by cycle detection. When a cycle is present, the recurring leaf will not be unfolded and instead be represented by its IRI. The same behavior is applied when a document has too many unfolds, going beyong the configurable default of 500.000 documents.
985+
986+
Read more about cycle detection in the [TerminusDB Internals](/docs/terminusdb-internals/), in the section [Document Unfolding Reference](/docs/document-unfolding-reference/).
987+
983988
#### Code: An example unfoldable
984989

985990
```json

0 commit comments

Comments
 (0)