README.md
1# zap file format
2
3Advanced ZAP File Format Documentation is [here](zap.md).
4
5The file is written in the reverse order that we typically access data. This helps us write in one pass since later sections of the file require file offsets of things we've already written.
6
7Current usage:
8
9- mmap the entire file
10- crc-32 bytes and version are in fixed position at end of the file
11- reading remainder of footer could be version specific
12- remainder of footer gives us:
13 - 3 important offsets (docValue , fields index and stored data index)
14 - 2 important values (number of docs and chunk factor)
15- field data is processed once and memoized onto the heap so that we never have to go back to disk for it
16- access to stored data by doc number means first navigating to the stored data index, then accessing a fixed position offset into that slice, which gives us the actual address of the data. the first bytes of that section tell us the size of data so that we know where it ends.
17- access to all other indexed data follows the following pattern:
18 - first know the field name -> convert to id
19 - next navigate to term dictionary for that field
20 - some operations stop here and do dictionary ops
21 - next use dictionary to navigate to posting list for a specific term
22 - walk posting list
23 - if necessary, walk posting details as we go
24 - if location info is desired, consult location bitmap to see if it is there
25
26## stored fields section
27
28- for each document
29 - preparation phase:
30 - produce a slice of metadata bytes and data bytes
31 - produce these slices in field id order
32 - field value is appended to the data slice
33 - metadata slice is varint encoded with the following values for each field value
34 - field id (uint16)
35 - field type (byte)
36 - field value start offset in uncompressed data slice (uint64)
37 - field value length (uint64)
38 - field number of array positions (uint64)
39 - one additional value for each array position (uint64)
40 - compress the data slice using snappy
41 - file writing phase:
42 - remember the start offset for this document
43 - write out meta data length (varint uint64)
44 - write out compressed data length (varint uint64)
45 - write out the metadata bytes
46 - write out the compressed data bytes
47
48## stored fields idx
49
50- for each document
51 - write start offset (remembered from previous section) of stored data (big endian uint64)
52
53With this index and a known document number, we have direct access to all the stored field data.
54
55## posting details (freq/norm) section
56
57- for each posting list
58 - produce a slice containing multiple consecutive chunks (each chunk is varint stream)
59 - produce a slice remembering offsets of where each chunk starts
60 - preparation phase:
61 - for each hit in the posting list
62 - if this hit is in next chunk close out encoding of last chunk and record offset start of next
63 - encode term frequency (uint64)
64 - encode norm factor (float32)
65 - file writing phase:
66 - remember start position for this posting list details
67 - write out number of chunks that follow (varint uint64)
68 - write out length of each chunk (each a varint uint64)
69 - write out the byte slice containing all the chunk data
70
71If you know the doc number you're interested in, this format lets you jump to the correct chunk (docNum/chunkFactor) directly and then seek within that chunk until you find it.
72
73## posting details (location) section
74
75- for each posting list
76 - produce a slice containing multiple consecutive chunks (each chunk is varint stream)
77 - produce a slice remembering offsets of where each chunk starts
78 - preparation phase:
79 - for each hit in the posting list
80 - if this hit is in next chunk close out encoding of last chunk and record offset start of next
81 - encode field (uint16)
82 - encode field pos (uint64)
83 - encode field start (uint64)
84 - encode field end (uint64)
85 - encode number of array positions to follow (uint64)
86 - encode each array position (each uint64)
87 - file writing phase:
88 - remember start position for this posting list details
89 - write out number of chunks that follow (varint uint64)
90 - write out length of each chunk (each a varint uint64)
91 - write out the byte slice containing all the chunk data
92
93If you know the doc number you're interested in, this format lets you jump to the correct chunk (docNum/chunkFactor) directly and then seek within that chunk until you find it.
94
95## postings list section
96
97- for each posting list
98 - preparation phase:
99 - encode roaring bitmap posting list to bytes (so we know the length)
100 - file writing phase:
101 - remember the start position for this posting list
102 - write freq/norm details offset (remembered from previous, as varint uint64)
103 - write location details offset (remembered from previous, as varint uint64)
104 - write length of encoded roaring bitmap
105 - write the serialized roaring bitmap data
106
107## dictionary
108
109- for each field
110 - preparation phase:
111 - encode vellum FST with dictionary data pointing to file offset of posting list (remembered from previous)
112 - file writing phase:
113 - remember the start position of this persistDictionary
114 - write length of vellum data (varint uint64)
115 - write out vellum data
116
117## fields section
118
119- for each field
120 - file writing phase:
121 - remember start offset for each field
122 - write dictionary address (remembered from previous) (varint uint64)
123 - write length of field name (varint uint64)
124 - write field name bytes
125
126## fields idx
127
128- for each field
129 - file writing phase:
130 - write big endian uint64 of start offset for each field
131
132NOTE: currently we don't know or record the length of this fields index. Instead we rely on the fact that we know it immediately precedes a footer of known size.
133
134## fields DocValue
135
136- for each field
137 - preparation phase:
138 - produce a slice containing multiple consecutive chunks, where each chunk is composed of a meta section followed by compressed columnar field data
139 - produce a slice remembering the length of each chunk
140 - file writing phase:
141 - remember the start position of this first field DocValue offset in the footer
142 - write out number of chunks that follow (varint uint64)
143 - write out length of each chunk (each a varint uint64)
144 - write out the byte slice containing all the chunk data
145
146NOTE: currently the meta header inside each chunk gives clue to the location offsets and size of the data pertaining to a given docID and any
147read operation leverage that meta information to extract the document specific data from the file.
148
149## footer
150
151- file writing phase
152 - write number of docs (big endian uint64)
153 - write stored field index location (big endian uint64)
154 - write field index location (big endian uint64)
155 - write field docValue location (big endian uint64)
156 - write out chunk factor (big endian uint32)
157 - write out version (big endian uint32)
158 - write out file CRC of everything preceding this (big endian uint32)
159