Understand Jina Recursive Document Representation¶
In Jina, each Document is represented as a recursive representation (tree).
A rooted recursive representation has a root node and every node has X children. In Jina, the root node is the document itself, while the left & right children are referred to as chunks and matches respectively.
The above image illustrates a basic document structure: A document (root node) and the two possible child nodes: chunks and matches.
chunks are a sequence of documents which is attached to the root document with a higher
matches is a sequence of documents which are semantically related to the root document.
We’ll dive into these concepts in this chapter:
Each Jina Document (potentially) consists of a list of chunks. A
chunk is a small semantic unit of a Document, like a sentence or a 64x64 pixel image patch.
Think about these use cases: you want to search a document at a specific
granularity level, e.g. a sentence or a paragraph.
Or your query consists of multiple modalities, such as a piece of text together with an image.
chunk makes it feasible!
In Jina primitive data types,
chunk is defined as a
property of a Document:
from jina import Document with Document() as root: root.text = 'What is love? Oh baby do not hurt me.' # Initialised a document as root with 0 chunks. print(len(root.chunks)) >>> 0 # Initialise two documents and add as chunks to root. with Document() as chunk1: chunk1.text = 'What is love?' root.chunks.add(chunk1) with Document() as chunk2: chunk1.text = 'Oh baby do not hurt me.' root.chunks.add(chunk2) # Now the document has 2 chunks print(len(root.chunks)) >>> 2
What happened by adding
print(root.granularity) >>> 0 print(root.chunks.granularity) >>> 1 root.id == root.chunks.parent_id >>> True
This can be seen in the image below:
The code sample and graph above demonstrates the basic idea of a
chunk in a Document.
In the beginning, we initialized a Document with
granularity=0 (by default).
We then initialized two chunks and add them to the
Two things happened when adding the
The granularity of the chunk has been increased by 1 (default 0).
chunkhas been referenced to its parent:
This allows Jina (and you) to query chunks and reference back to its root document at any
In a neural search system (and traditional retrieval system), matches are the expected documents returned from the system given the user query.
matches could happen at the
root level or any
To fully understand the concept of
matches, we introduce a new term, named
adjacency (short for
a in the diagram), which reflects the level of the document it is connected to.
NOTE: granularity and adjacency apply to both chunks and matches.
from jina import Document with Document() as root: root.text = 'What is love? Oh baby do not hurt me.' print(root.adjacency) >>> 0 # Initialise two documents and add as chunks to root. with Document() as chunk1: chunk1.text = 'What is love?' root.chunks.add(chunk1) with Document() as chunk2: chunk1.text = 'Oh baby do not hurt me.' root.chunks.add(chunk2) # Add a match document. with Document() as match: # a match document semantically related to our root match.text = 'What is love? Oh please do not hurt me.' root.matches.add(match) print(len(root.matches)) >>> 1 print(root.matches.granularity) >>> 0 print(root.matches.adjacency) >>> 1
In the code snippet and diagram above, we initialized a Document as
root with the text: What is love? Oh, baby do not hurt me..
And a Document with text What is love? Oh please do not hurt me was added as a match to the
The matched document
match is a document without any parents, so it stays at the same level as
root with a granularity value of 0.
match is the retrieved result from
root, so the
adjacency increased to 1.
By default, the
root node has an
adjacency of 0, and the value increases by 1 when it hits a
Let’s go deeper: Recursive Document Representation¶
Till now, we’ve introduced chunks and
matches with a depth of 1.
While in a real-world scenario, things could be much more complicated than this.
For instance, a
chunk could be further divided into small chunks, and a chunk at any level might have it’s own
matches at that level.
Jina has defined a recursive structure with arbitrary width and depth instead of a trivial bi-level structure. Roughly speaking, chunks can have the next level chunks and the same level matches; and so do matches. This could go on and on. The following figure illustrates this structure Ref: New Features in Jina v0.5 You Should Know About.
This recursive structure provides Jina the flexibility to cover any complex use case that may require search at different semantic units.
Besides, the recursive structure enables Jina rankers to accumulate scores from lower granularities to upper granularities, such as
For example, in NLP a long document is composed of semantic chapters; each chapter consists of multiple paragraphs, which can be further segmented into sentences.
In CV, a video is composed of one or more scenes, including one or more shots (i.e. a sequence of frames taken by a single camera over a continuous period of time).
Each shot includes one or more frames. Such hierarchical structures can be very well represented with the recursive representation.
If we look from a tree view (with a depth of 3):
Document Traversal with traversal paths¶
As you already learned from Jina 101, you needs to apply transformation (i.e. a
callback) on a different level of documents.
Given the tree structure, how could we achieve that?
The answer is
Jina has defined a method called
traversal within the class of Document, which looks like this:
def traverse(self, traversal_path: str, callback_fn: Callable, *args, **kwargs) -> None """Traversal apply `:meth:callback_fn` on the recursive tree representation.""" ...
This allows you to apply
callback_fn based on
traversal_path is defined as below:
With these pre-defined node names, you’re able to apply any callbacks (defined as
_apply_all in the
driver) to a specific node.
In the below YAML configuration, the
VectorSearchDriver was applied to node
KVSearchDriver was applied to node
cm (matches of chunks).
!CompoundIndexer ... requests: on: SearchRequest: - !VectorSearchDriver with: traversal_path: ['c'] - !KVSearchDriver with: traversal_path: ['cm']