Namespace Lucene.Net.Codecs.Lucene40

Classes

Lucene40Codec

Implements the Lucene 4.0 index format, with configurable per-field postings formats.

If you want to reuse functionality of this codec in another codec, extend FilterCodec.

See Lucene.Net.Codecs.Lucene40 package documentation for file format details.

Lucene40DocValuesFormat

Lucene 4.0 DocValues format.

Files:

Entries within the compound file:
  • <segment><fieldNumber>.dat: data values
  • <segment><fieldNumber>.idx: index into the .dat for DEREF types

There are several many types of DocValues with different encodings. From the perspective of filenames, all types store their values in .dat entries within the compound file. In the case of dereferenced/sorted types, the .dat actually contains only the unique values, and an additional .idx file contains pointers to these unique values.

Formats:
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.VAR_INTS .dat --> Header, PackedType, MinValue, DefaultValue, PackedStream
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FIXED_INTS_8 .dat --> Header, ValueSize, Byte (WriteByte(Byte)) maxdoc
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FIXED_INTS_16 .dat --> Header, ValueSize, Short (WriteInt16(Int16)) maxdoc
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FIXED_INTS_32 .dat --> Header, ValueSize, Int32 (WriteInt32(Int32)) maxdoc
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FIXED_INTS_64 .dat --> Header, ValueSize, Int64 (WriteInt64(Int64)) maxdoc
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FLOAT_32 .dat --> Header, ValueSize, Float32maxdoc
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FLOAT_64 .dat --> Header, ValueSize, Float64maxdoc
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_FIXED_STRAIGHT .dat --> Header, ValueSize, (Byte (WriteByte(Byte)) * ValueSize)maxdoc
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_STRAIGHT .idx --> Header, TotalBytes, Addresses
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_STRAIGHT .dat --> Header, (Byte (WriteByte(Byte)) * variable ValueSize)maxdoc
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_FIXED_DEREF .idx --> Header, NumValues, Addresses
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_FIXED_DEREF .dat --> Header, ValueSize, (Byte (WriteByte(Byte)) * ValueSize)NumValues
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_DEREF .idx --> Header, TotalVarBytes, Addresses
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_DEREF .dat --> Header, (LengthPrefix + Byte (WriteByte(Byte)) * variable ValueSize)NumValues
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_FIXED_SORTED .idx --> Header, NumValues, Ordinals
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_FIXED_SORTED .dat --> Header, ValueSize, (Byte (WriteByte(Byte)) * ValueSize)NumValues
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_SORTED .idx --> Header, TotalVarBytes, Addresses, Ordinals
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_SORTED .dat --> Header, (Byte (WriteByte(Byte)) * variable ValueSize)NumValues
Data Types: Notes:
  • PackedType is a 0 when compressed, 1 when the stream is written as 64-bit integers.
  • Addresses stores pointers to the actual byte location (indexed by docid). In the VAR_STRAIGHT case, each entry can have a different length, so to determine the length, docid+1 is retrieved. A sentinel address is written at the end for the VAR_STRAIGHT case, so the Addresses stream contains maxdoc+1 indices. For the deduplicated VAR_DEREF case, each length is encoded as a prefix to the data itself as a VInt (WriteVInt32(Int32)) (maximum of 2 bytes).
  • Ordinals stores the term ID in sorted order (indexed by docid). In the FIXED_SORTED case, the address into the .dat can be computed from the ordinal as Header+ValueSize+(ordinal*ValueSize) because the byte length is fixed. In the VAR_SORTED case, there is double indirection (docid -> ordinal -> address), but an additional sentinel ordinal+address is always written (so there are NumValues+1 ordinals). To determine the length, ord+1's address is looked up as well.
  • Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_STRAIGHT in contrast to other straight variants uses a .idx file to improve lookup perfromance. In contrast to Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_DEREF it doesn't apply deduplication of the document values.

Limitations:

Lucene40FieldInfosFormat

Lucene 4.0 Field Infos format.

Field names are stored in the field info file, with suffix .fnm.

FieldInfos (.fnm) --> Header,FieldsCount, <FieldName,FieldNumber, FieldBits,DocValuesBits,Attributes> FieldsCount

Data types:

Field Descriptions:
  • FieldsCount: the number of fields in this file.
  • FieldName: name of the field as a UTF-8 String.
  • FieldNumber: the field's number. Note that unlike previous versions of Lucene, the fields are not numbered implicitly by their order in the file, instead explicitly.
  • FieldBits: a byte containing field options.
    • The low-order bit is one for indexed fields, and zero for non-indexed fields.
    • The second lowest-order bit is one for fields that have term vectors stored, and zero for fields without term vectors.
    • If the third lowest order-bit is set (0x4), offsets are stored into the postings list in addition to positions.
    • Fourth bit is unused.
    • If the fifth lowest-order bit is set (0x10), norms are omitted for the indexed field.
    • If the sixth lowest-order bit is set (0x20), payloads are stored for the indexed field.
    • If the seventh lowest-order bit is set (0x40), term frequencies and positions omitted for the indexed field.
    • If the eighth lowest-order bit is set (0x80), positions are omitted for the indexed field.
  • DocValuesBits: a byte containing per-document value types. The type recorded as two four-bit integers, with the high-order bits representing norms options, and the low-order bits representing DocValues options. Each four-bit integer can be decoded as such:
    • 0: no DocValues for this field.
    • 1: variable-width signed integers. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.VAR_INTS)
    • 2: 32-bit floating point values. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FLOAT_32)
    • 3: 64-bit floating point values. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FLOAT_64)
    • 4: fixed-length byte array values. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_FIXED_STRAIGHT)
    • 5: fixed-length dereferenced byte array values. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_FIXED_DEREF)
    • 6: variable-length byte array values. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_STRAIGHT)
    • 7: variable-length dereferenced byte array values. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_DEREF)
    • 8: 16-bit signed integers. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FIXED_INTS_16)
    • 9: 32-bit signed integers. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FIXED_INTS_32)
    • 10: 64-bit signed integers. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FIXED_INTS_64)
    • 11: 8-bit signed integers. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.FIXED_INTS_8)
    • 12: fixed-length sorted byte array values. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_FIXED_SORTED)
    • 13: variable-length sorted byte array values. (Lucene.Net.Codecs.Lucene40.LegacyDocValuesType.BYTES_VAR_SORTED)
  • Attributes: a key-value map of codec-private attributes.

@lucene.experimental

Lucene40FieldInfosWriter

Lucene 4.0 FieldInfos writer.

Lucene40LiveDocsFormat

Lucene 4.0 Live Documents Format.

The .del file is optional, and only exists when a segment contains deletions.

Although per-segment, this file is maintained exterior to compound segment files.

Deletions (.del) --> Format,Header,ByteCount,BitCount, Bits | DGaps (depending on Format)

Format is 1: indicates cleared DGaps.

ByteCount indicates the number of bytes in Bits. It is typically (SegSize/8)+1.

BitCount indicates the number of bits that are currently set in Bits.

Bits contains one bit for each document indexed. When the bit corresponding to a document number is cleared, that document is marked as deleted. Bit ordering is from least to most significant. Thus, if Bits contains two bytes, 0x00 and 0x02, then document 9 is marked as alive (not deleted).

DGaps represents sparse bit-vectors more efficiently than Bits. It is made of DGaps on indexes of nonOnes bytes in Bits, and the nonOnes bytes themselves. The number of nonOnes bytes in Bits (NonOnesBytesCount) is not stored.

For example, if there are 8000 bits and only bits 10,12,32 are cleared, DGaps would be used:

(VInt) 1 , (byte) 20 , (VInt) 3 , (Byte) 1

Lucene40NormsFormat

Lucene 4.0 Norms Format.

Files:

Norms are implemented as DocValues, so other than file extension, norms are written exactly the same way as Lucene40DocValuesFormat.

@lucene.experimental

Lucene40PostingsBaseFormat

Provides a PostingsReaderBase and PostingsWriterBase.

Lucene40PostingsFormat

Lucene 4.0 Postings format.

Files:

Term Dictionary

The .tim file contains the list of terms in each field along with per-term statistics (such as docfreq) and pointers to the frequencies, positions and skip data in the .frq and .prx files. See BlockTreeTermsWriter for more details on the format.

NOTE: The term dictionary can plug into different postings implementations: the postings writer/reader are actually responsible for encoding and decoding the Postings Metadata and Term Metadata sections described here:

Notes:

  • Header is a CodecHeader (WriteHeader(DataOutput, String, Int32)) storing the version information for the postings.
  • SkipInterval is the fraction of TermDocs stored in skip tables. It is used to accelerate Advance(Int32). Larger values result in smaller indexes, greater acceleration, but fewer accelerable cases, while smaller values result in bigger indexes, less acceleration (in case of a small value for MaxSkipLevels) and more accelerable cases.
  • MaxSkipLevels is the max. number of skip levels stored for each term in the .frq file. A low value results in smaller indexes but less acceleration, a larger value results in slightly larger indexes but greater acceleration. See format of .frq file for more information about skip levels.
  • SkipMinimum is the minimum document frequency a term must have in order to write any skip data at all.
  • FreqDelta determines the position of this term's TermFreqs within the .frq file. In particular, it is the difference between the position of this term's data in that file and the position of the previous term's data (or zero, for the first term in the block).
  • ProxDelta determines the position of this term's TermPositions within the .prx file. In particular, it is the difference between the position of this term's data in that file and the position of the previous term's data (or zero, for the first term in the block. For fields that omit position data, this will be 0 since prox information is not stored.
  • SkipDelta determines the position of this term's SkipData within the .frq file. In particular, it is the number of bytes after TermFreqs that the SkipData starts. In other words, it is the length of the TermFreq data. SkipDelta is only stored if DocFreq is not smaller than SkipMinimum.

Term Index

The .tip file contains an index into the term dictionary, so that it can be accessed randomly. See BlockTreeTermsWriter for more details on the format.

Frequencies

The .frq file contains the lists of documents which contain each term, along with the frequency of the term in that document (except when frequencies are omitted: DOCS_ONLY).

  • FreqFile (.frq) --> Header, <TermFreqs, SkipData?> TermCount
  • Header --> CodecHeader (WriteHeader(DataOutput, String, Int32))
  • TermFreqs --> <TermFreq> DocFreq
  • TermFreq --> DocDelta[, Freq?]
  • SkipData --> <<SkipLevelLength, SkipLevel> NumSkipLevels-1, SkipLevel> <SkipDatum>
  • SkipLevel --> <SkipDatum> DocFreq/(SkipInterval^(Level + 1))
  • SkipDatum --> DocSkip,PayloadLength?,OffsetLength?,FreqSkip,ProxSkip,SkipChildLevelPointer?
  • DocDelta,Freq,DocSkip,PayloadLength,OffsetLength,FreqSkip,ProxSkip --> VInt (WriteVInt32(Int32))
  • SkipChildLevelPointer --> VLong (WriteVInt64(Int64))

TermFreqs are ordered by term (the term is implicit, from the term dictionary).

TermFreq entries are ordered by increasing document number.

DocDelta: if frequencies are indexed, this determines both the document number and the frequency. In particular, DocDelta/2 is the difference between this document number and the previous document number (or zero when this is the first document in a TermFreqs). When DocDelta is odd, the frequency is one. When DocDelta is even, the frequency is read as another VInt. If frequencies are omitted, DocDelta contains the gap (not multiplied by 2) between document numbers and no frequency information is stored.

For example, the TermFreqs for a term which occurs once in document seven and three times in document eleven, with frequencies indexed, would be the following sequence of VInts:

15, 8, 3

If frequencies were omitted (DOCS_ONLY) it would be this sequence of VInts instead:

7,4

DocSkip records the document number before every SkipInterval th document in TermFreqs. If payloads and offsets are disabled for the term's field, then DocSkip represents the difference from the previous value in the sequence. If payloads and/or offsets are enabled for the term's field, then DocSkip/2 represents the difference from the previous value in the sequence. In this case when DocSkip is odd, then PayloadLength and/or OffsetLength are stored indicating the length of the last payload/offset before the SkipIntervalth document in TermPositions.

PayloadLength indicates the length of the last payload.

OffsetLength indicates the length of the last offset (endOffset-startOffset).

FreqSkip and ProxSkip record the position of every SkipInterval th entry in FreqFile and ProxFile, respectively. File positions are relative to the start of TermFreqs and Positions, to the previous SkipDatum in the sequence.

For example, if DocFreq=35 and SkipInterval=16, then there are two SkipData entries, containing the 15 th and 31 st document numbers in TermFreqs. The first FreqSkip names the number of bytes after the beginning of TermFreqs that the 16 th SkipDatum starts, and the second the number of bytes after that that the 32 nd starts. The first ProxSkip names the number of bytes after the beginning of Positions that the 16 th SkipDatum starts, and the second the number of bytes after that that the 32 nd starts.

Each term can have multiple skip levels. The amount of skip levels for a term is NumSkipLevels = Min(MaxSkipLevels, floor(log(DocFreq/log(SkipInterval)))). The number of SkipData entries for a skip level is DocFreq/(SkipInterval^(Level + 1)), whereas the lowest skip level is Level=0.

Example: SkipInterval = 4, MaxSkipLevels = 2, DocFreq = 35. Then skip level 0 has 8 SkipData entries, containing the 3rd, 7th, 11th, 15th, 19th, 23rd, 27th, and 31st document numbers in TermFreqs. Skip level 1 has 2 SkipData entries, containing the 15th and 31st document numbers in TermFreqs.

The SkipData entries on all upper levels > 0 contain a SkipChildLevelPointer referencing the corresponding SkipData entry in level-1. In the example has entry 15 on level 1 a pointer to entry 15 on level 0 and entry 31 on level 1 a pointer to entry 31 on level 0.

Positions

The .prx file contains the lists of positions that each term occurs at within documents. Note that fields omitting positional data do not store anything into this file, and if all fields in the index omit positional data then the .prx file will not exist.

  • ProxFile (.prx) --> Header, <TermPositions> TermCount
  • Header --> CodecHeader (WriteHeader(DataOutput, String, Int32))
  • TermPositions --> <Positions> DocFreq
  • Positions --> <PositionDelta,PayloadLength?,OffsetDelta?,OffsetLength?,PayloadData?> Freq
  • PositionDelta,OffsetDelta,OffsetLength,PayloadLength --> VInt (WriteVInt32(Int32))
  • PayloadData --> byte (WriteByte(Byte)) PayloadLength

TermPositions are ordered by term (the term is implicit, from the term dictionary).

Positions entries are ordered by increasing document number (the document number is implicit from the .frq file).

PositionDelta is, if payloads are disabled for the term's field, the difference between the position of the current occurrence in the document and the previous occurrence (or zero, if this is the first occurrence in this document). If payloads are enabled for the term's field, then PositionDelta/2 is the difference between the current and the previous position. If payloads are enabled and PositionDelta is odd, then PayloadLength is stored, indicating the length of the payload at the current term position.

For example, the TermPositions for a term which occurs as the fourth term in one document, and as the fifth and ninth term in a subsequent document, would be the following sequence of VInts (payloads disabled):

4, 5, 4

PayloadData is metadata associated with the current term position. If PayloadLength is stored at the current position, then it indicates the length of this payload. If PayloadLength is not stored, then this payload has the same length as the payload at the previous position.

OffsetDelta/2 is the difference between this position's startOffset from the previous occurrence (or zero, if this is the first occurrence in this document). If OffsetDelta is odd, then the length (endOffset-startOffset) differs from the previous occurrence and an OffsetLength follows. Offset data is only written for DOCS_AND_FREQS_AND_POSITIONS_AND_OFFSETS.

Lucene40PostingsReader

Concrete class that reads the 4.0 frq/prox postings format.

Lucene40PostingsWriter

Concrete class that writes the 4.0 frq/prx postings format.

Lucene40RWCodec

Read-write version of Lucene40Codec for testing

Lucene40RWDocValuesFormat

Read-write version of for testing

Lucene40RWNormsFormat

Read-write version of for testing

Lucene40RWPostingsFormat

Read-write version of for testing.

Lucene40SegmentInfoFormat

Lucene 4.0 Segment info format.

Files:

  • .si: Header, SegVersion, SegSize, IsCompoundFile, Diagnostics, Attributes, Files

Data types:

Field Descriptions:

  • SegVersion is the code version that created the segment.
  • SegSize is the number of documents contained in the segment index.
  • IsCompoundFile records whether the segment is written as a compound file or not. If this is -1, the segment is not a compound file. If it is 1, the segment is a compound file.
  • Checksum contains the CRC32 checksum of all bytes in the segments_N file up until the checksum. This is used to verify integrity of the file on opening the index.
  • The Diagnostics Map is privately written by IndexWriter, as a debugging aid, for each segment it creates. It includes metadata like the current Lucene version, OS, .NET/Java version, why the segment was created (merge, flush, addIndexes), etc.
  • Attributes: a key-value map of codec-private attributes.
  • Files is a list of files referred to by this segment.

@lucene.experimental

Lucene40SegmentInfoReader

Lucene 4.0 implementation of SegmentInfoReader.

@lucene.experimental

Lucene40SegmentInfoWriter

Lucene 4.0 implementation of SegmentInfoWriter.

@lucene.experimental

Lucene40SkipListReader

Implements the skip list reader for the 4.0 posting list format that stores positions and payloads.

Lucene40SkipListWriter

Implements the skip list writer for the 4.0 posting list format that stores positions and payloads.

Lucene40StoredFieldsFormat

Lucene 4.0 Stored Fields Format.

Stored fields are represented by two files:

  1. The field index, or .fdx file.

    This is used to find the location within the field data file of the fields of a particular document. Because it contains fixed-length data, this file may be easily randomly accessed. The position of document n 's field data is the Uint64 (WriteInt64(Int64)) at n*8 in this file.

    This contains, for each document, a pointer to its field data, as follows:

  2. The field data, or .fdt file.

    This contains the stored fields of each document, as follows:

    • FieldData (.fdt) --> <Header>, <DocFieldData> SegSize
    • Header --> CodecHeader (WriteHeader(DataOutput, String, Int32))
    • DocFieldData --> FieldCount, <FieldNum, Bits, Value> FieldCount
    • FieldCount --> VInt (WriteVInt32(Int32))
    • FieldNum --> VInt (WriteVInt32(Int32))
    • Bits --> Byte (WriteByte(Byte))
      • low order bit reserved.
      • second bit is one for fields containing binary data
      • third bit reserved.
      • 4th to 6th bit (mask: 0x7<<3) define the type of a numeric field:
        • all bits in mask are cleared if no numeric field at all
        • 1<<3: Value is Int
        • 2<<3: Value is Long
        • 3<<3: Value is Int as Float (as of Int32BitsToSingle(Int32)
        • 4<<3: Value is Long as Double (as of
    • Value --> String | BinaryValue | Int | Long (depending on Bits)
    • BinaryValue --> ValueSize, < Byte (WriteByte(Byte)) >^ValueSize
    • ValueSize --> VInt (WriteVInt32(Int32))
@lucene.experimental

Lucene40StoredFieldsReader

Class responsible for access to stored document fields.

It uses <segment>.fdt and <segment>.fdx; files.

@lucene.internal

Lucene40StoredFieldsWriter

Class responsible for writing stored document fields.

It uses <segment>.fdt and <segment>.fdx; files.

@lucene.experimental

Lucene40TermVectorsFormat

Lucene 4.0 Term Vectors format.

Term Vector support is an optional on a field by field basis. It consists of 3 files.

  1. The Document Index or .tvx file.

    For each document, this stores the offset into the document data (.tvd) and field data (.tvf) files.

    DocumentIndex (.tvx) --> Header,<DocumentPosition,FieldPosition> NumDocs

  2. The Document or .tvd file.

    This contains, for each document, the number of fields, a list of the fields with term vector info and finally a list of pointers to the field information in the .tvf (Term Vector Fields) file.

    The .tvd file is used to map out the fields that have term vectors stored and where the field information is in the .tvf file.

    Document (.tvd) --> Header,<NumFields, FieldNums, FieldPositions> NumDocs

  3. The Field or .tvf file.

    This file contains, for each field that has a term vector stored, a list of the terms, their frequencies and, optionally, position, offset, and payload information.

    Field (.tvf) --> Header,<NumTerms, Flags, TermFreqs> NumFields

    Notes:

    • Flags byte stores whether this term vector has position, offset, payload. information stored.
    • Term byte prefixes are shared. The PrefixLength is the number of initial bytes from the previous term which must be pre-pended to a term's suffix in order to form the term's bytes. Thus, if the previous term's text was "bone" and the term is "boy", the PrefixLength is two and the suffix is "y".
    • PositionDelta is, if payloads are disabled for the term's field, the difference between the position of the current occurrence in the document and the previous occurrence (or zero, if this is the first occurrence in this document). If payloads are enabled for the term's field, then PositionDelta/2 is the difference between the current and the previous position. If payloads are enabled and PositionDelta is odd, then PayloadLength is stored, indicating the length of the payload at the current term position.
    • PayloadData is metadata associated with a term position. If PayloadLength is stored at the current position, then it indicates the length of this payload. If PayloadLength is not stored, then this payload has the same length as the payload at the previous position. PayloadData encodes the concatenated bytes for all of a terms occurrences.
    • Offsets are stored as delta encoded VInts. The first VInt is the startOffset, the second is the endOffset.

Lucene40TermVectorsReader

Lucene 4.0 Term Vectors reader.

It reads .tvd, .tvf, and .tvx files.

Lucene40TermVectorsWriter

Lucene 4.0 Term Vectors writer.

It writes .tvd, .tvf, and .tvx files.