Lucene源码系列：正排索引文件构建

背景

Lucene中根据term字典和倒排可以快速查找到相关文档的id，那怎么获取文档中的字段内容呢，这就是我们今天要讲的正排数据。

Lucene中对于某个文档的各个字段，可以通过配置来控制是否要存储进正排索引文件中，只有存储到正排索引文件中，查询的时候，有需要才能返回相应的字段。

如果理解了之前介绍过的词向量的索引文件构建，可以发现其实正排索引文件和词向量索引文件构建非常类似。

最终生成的正排索引文件有3个：

• 
  
• fdt：按chunk存储doc的开启了store的字段
  
• fdx：chunk的索引文件，记录的是每个chunk的起始docID，以及每个chunk的起始位置，方便根据docID快速定位到chunk。
  
• fdm：正排索引文件的元信息，用来读取正排索引文件使用的。
  

前置知识

• 
  
• 在对字段数据的存储时，对不同的数据类型，有不同的压缩算法，详见《单值编码压缩算法》。
  
• 构建chunk索引文件的时候会用到工具类FieldsIndexWriter，具体我们已经在《词向量索引文件构建》中详细介绍过了。
  

索引文件格式

fdm

fdm是正排索引文件的元信息，用来读取的时候使用。

字段详解

Header

文件头部信息，主要是包括：

• 
  
• 文件头魔数（同一lucene版本所有文件相同）
  
• 该文件使用的codec名称：Lucene90FieldsIndexMeta
  
• codec版本
  
• segment id（也是Segment_N文件中的N）
  
• segment后缀名（一般为空）
  

ChunkSize

用来判断是否满足一个chunk的一种条件，如果chunk的大小超过了ChunkSize的限制，则可以构建一个chunk

NumDocs

doc总数

BlockShift

DirectMonotonicWriter需要的参数，DirectMonotonicWriter压缩存储会生成多个block，BlockShift决定了block的大小。

TotalChunks + 1

chunk总数 + 1，在生成fdx索引文件中ChunkStartDocIDs和ChunkOffsets两个字段时，使用DirectMonotonicWriter写入的值的总数。

fdxDocStartFP

fdx索引文件中ChunkStartDocIDs的起始位置

DocBlockMetas

fdx索引文件中ChunkStartDocIDs使用DirectMonotonicWriter编码存储，会生成多个block，这些block的元信息。

tvxOffsetStartFP

fdx中ChunkOffsets的起始位置

OffsetBlockMetas

fdx索引文件中ChunkOffsets使用DirectMonotonicWriter编码存储，会生成多个block，这些block的元信息。

SPEndPoint

fdx文件的结束位置，后面是fdx的footer信息。

MaxPointer

fdt文件的结束位置，后面fdt的footer信息。

NumChunks

chunk总数

NumDirtyChunks

dirtyChunk总数

NumDirtyDocs

dirtyChunk中的doc总数

Footer

文件尾，主要包括

• 
  
• 文件尾魔数（同一个lucene版本所有文件一样）
  
• 0
  
• 校验码
  

fdt

fdt中按chunk存储各个doc所有的字段数据。

字段详解

Header

文件头部信息，主要是包括：

• 
  
• 
  

  文件头魔数（同一lucene版本所有文件相同）

  
  
  
• 
  

  该文件使用的codec名称

  
  

  根据压缩模式的不同有两种：

  
  
  • 
    
  • Lucene90StoredFieldsFastData
    
  • Lucene90StoredFieldsHighData
    
  
  
  
• 
  

  codec版本

  
  
  
• 
  

  segment id（也是Segment_N文件中的N）

  
  
  
• 
  

  segment后缀名（一般为空）

  
  
  

chunk

• 
  
• DocBase：Chunk中Doc的起始编号，Chunk中所有doc的真实编号需要加上这个DocBase
  
• NumDocsCode：是NumDocs和IsDirty，IsSlice的int组合体
  
  • 
    
  • NumDocs：chunk中的doc总数
    
  • IsDirty：chunk是否是dirtyChunk
    
  • IsSlice：chunk是否被分成多个slice
    
  
  
  
• DocNumFields：chunk中每个文档的字段个数。
  
• DocDataLengths：chunk中每个doc占用的存储空间大小。
  
• Doc：doc中每个store字段的信息
  
  • 
    
  • Field：store的字段
    
    • 
      
    • FieldNumAndTypeCode：FieldNumber和type的long组合体
      
      • 
        
      • FieldNumber：字段的编号
        
      • type：字段的类型
        
      
      
      
    • FieldValue：根据不同的数值类型，有不同的存储方式
      
      • 
        
      • 二进制/string：先存length，再存数据
        
      • byte/short/int：zint存储
        
      • long：tlong存储
        
      • float：zfloat存储
        
      • double：zdouble存储
        
      
      
      
    
    
    
  
  
  

Footer

文件尾，主要包括

• 
  
• 文件尾魔数（同一个lucene版本所有文件一样）
  
• 0
  
• 校验码
  

fdx

fdt中所有chunk的索引信息，可以快速根据docID定位到chunk的位置。

字段详解

Header

文件头部信息，主要是包括：

• 
  
• 文件头魔数（同一lucene版本所有文件相同）
  
• 该文件使用的codec名称：Lucene90FieldsIndexIdx
  
• codec版本
  
• segment id（也是Segment_N文件中的N）
  
• segment后缀名（一般为空）
  

ChunkStartDocIDs

所有chunk的起始docID，使用DirectMonotonicWriter编码存储，会生成多个block。

ChunkOffsets

所有chunk在fdt索引文件中的起始位置，使用DirectMonotonicWriter编码存储，会生成多个block。

Footer

文件尾，主要包括

• 
  
• 文件尾魔数（同一个lucene版本所有文件一样）
  
• 0
  
• 校验码
  

构建源码

本文源码解析基于lucene-core-9.1.0。

• 
  
• StoredFieldsConsumer负责调度正排索引文件的构建主要有：启动一个doc的处理，处理doc中的field，结束一个doc的处理，结束正排索引的构建。
  
• Lucene90CompressingStoredFieldsWriter负责持久化生成正排索引文件
  

构建涉及到的StoredFieldsConsumer和Lucene90CompressingStoredFieldsWriter逻辑其实非常简单，下面我们一起来看下。

StoredFieldsConsumer

class StoredFieldsConsumer {

  final Codec codec;

  // 索引文件的目录  

  final Directory directory;

  final SegmentInfo info;

  // 实现类是  Lucene90CompressingStoredFieldsWriter，负责正排索引文件的持久化

  StoredFieldsWriter writer;

  Accountable accountable = Accountable.NULL_ACCOUNTABLE;

  // 前一个处理的docID  

  private int lastDoc;


  StoredFieldsConsumer(Codec codec, Directory directory, SegmentInfo info) {

    this.codec = codec;

    this.directory = directory;

    this.info = info;

    this.lastDoc = -1;

  }


  // 创建 Lucene90CompressingStoredFieldsWriter  

  protected void initStoredFieldsWriter() throws IOException {

    if (writer == null) { 

      this.writer = codec.storedFieldsFormat().fieldsWriter(directory, info, IOContext.DEFAULT);

      accountable = writer;

    }

  }


  // 开始处理一个doc

  void startDocument(int docID) throws IOException {

    assert lastDoc < docID;

    initStoredFieldsWriter();

    while (++lastDoc < docID) { // 确保doc是连续的

      writer.startDocument();

      writer.finishDocument();

    }

    //  Lucene90CompressingStoredFieldsWriter中开始处理doc 

    writer.startDocument();

  }


  // 每个需要构建的正排字段都会被处理

  void writeField(FieldInfo info, IndexableField field) throws IOException {

    writer.writeField(info, field);

  }


  // 结束doc的处理  

  void finishDocument() throws IOException {

    writer.finishDocument();

  }


  // 结束正排的构建  

  void finish(int maxDoc) throws IOException {

    while (lastDoc < maxDoc - 1) {

      startDocument(lastDoc);

      finishDocument();

      ++lastDoc;

    }

  }


  // 持久化正排索引文件  

  void flush(SegmentWriteState state, Sorter.DocMap sortMap) throws IOException {

    try {

      writer.finish(state.segmentInfo.maxDoc());

    } finally {

      IOUtils.close(writer);

    }

  }


  void abort() {

    IOUtils.closeWhileHandlingException(writer);

  }

}

Lucene90CompressingStoredFieldsWriter

成员变量

  // 数据文件

  public static final String FIELDS_EXTENSION = "fdt";

  // 索引文件

  public static final String INDEX_EXTENSION = "fdx";

  // 元信息文件

  public static final String META_EXTENSION = "fdm";

  /** Codec name for the index. */

  public static final String INDEX_CODEC_NAME = "Lucene90FieldsIndex";


  // 不同数据类型编码  

  static final int STRING = 0x00;

  static final int BYTE_ARR = 0x01;

  static final int NUMERIC_INT = 0x02;

  static final int NUMERIC_FLOAT = 0x03;

  static final int NUMERIC_LONG = 0x04;

  static final int NUMERIC_DOUBLE = 0x05;

  // 数据类型编码的bit数量

  static final int TYPE_BITS = PackedInts.bitsRequired(NUMERIC_DOUBLE);

  // 提取类型的掩码  

  static final int TYPE_MASK = (int) PackedInts.maxValue(TYPE_BITS);


  static final int VERSION_START = 1;

  static final int VERSION_CURRENT = VERSION_START;

  static final int META_VERSION_START = 0;


  private final String segment;

  // 索引生成工具  

  private FieldsIndexWriter indexWriter;

  private IndexOutput metaStream, fieldsStream;


  private Compressor compressor;

  private final CompressionMode compressionMode;

  // chunk的大小  

  private final int chunkSize;

  // 每个chunk最多可以存储多少个doc  

  private final int maxDocsPerChunk;


  // 缓存所有的字段的值

  private final ByteBuffersDataOutput bufferedDocs;

  // 下标是当前chunk中的docID的偏移量，值是对应doc的字段个数

  private int[] numStoredFields; 

  // 下标是当前chunk中的docID的偏移量，值是对应doc的所有需要store的数据在bufferedDocs中的结束位置

  private int[] endOffsets; 

  // chunk中的起始docID

  private int docBase;

  // chunk中的doc个数

  private int numBufferedDocs; 

  // chunk总数

  private long numChunks;

  // dirtyChunk总数，未满足生成chunk的条件时，强制生成的chunk是dirtyChunk

  private long numDirtyChunks; 

  // dirtyDoc总数，dirtyChunk中的doc是dirtyDoc

  private long numDirtyDocs; 


  // 在处理一个doc的时候，统计已经处理的field个数

  private int numStoredFieldsInDoc;

核心方法

开始处理一个doc

当前实现中是空操作。

  @Override

  public void startDocument() throws IOException {}

处理一个field

处理一个field，就是读取field的值，根据值的类型按对应的值的存储方式存入bufferedDocs缓存中。

  public void writeField(FieldInfo info, IndexableField field) throws IOException {


    ++numStoredFieldsInDoc;


    int bits = 0;

    final BytesRef bytes;

    final String string;


    Number number = field.numericValue();

    if (number != null) { // 如果是数值类型

      if (number instanceof Byte || number instanceof Short || number instanceof Integer) {

        // byte，short，int都标记为int  

        bits = NUMERIC_INT;

      } else if (number instanceof Long) {

        // long  

        bits = NUMERIC_LONG;

      } else if (number instanceof Float) {

        // float  

        bits = NUMERIC_FLOAT;

      } else if (number instanceof Double) {

        // double  

        bits = NUMERIC_DOUBLE;

      } else {

        throw new IllegalArgumentException("cannot store numeric type " + number.getClass());

      }

      string = null;

      bytes = null;

    } else {

      bytes = field.binaryValue();

      if (bytes != null) { // 是二进制

        bits = BYTE_ARR;

        string = null;

      } else { // 是字符串

        bits = STRING;

        string = field.stringValue();

        if (string == null) {

          throw new IllegalArgumentException(

              "field "

                  + field.name()

                  + " is stored but does not have binaryValue, stringValue nor numericValue");

        }

      }

    }

    // 字段的编号和类型组合体

    final long infoAndBits = (((long) info.number) << TYPE_BITS) | bits;

    bufferedDocs.writeVLong(infoAndBits);


    if (bytes != null) {

      bufferedDocs.writeVInt(bytes.length);

      bufferedDocs.writeBytes(bytes.bytes, bytes.offset, bytes.length);

    } else if (string != null) {

      bufferedDocs.writeString(string);

    } else {

      if (number instanceof Byte || number instanceof Short || number instanceof Integer) {

        bufferedDocs.writeZInt(number.intValue());

      } else if (number instanceof Long) {

        writeTLong(bufferedDocs, number.longValue());

      } else if (number instanceof Float) {

        writeZFloat(bufferedDocs, number.floatValue());

      } else if (number instanceof Double) {

        writeZDouble(bufferedDocs, number.doubleValue());

      } else {

        throw new AssertionError("Cannot get here");

      }

    }

  }

结束处理一个doc

结束doc的处理，需要做4件事：

• 
  
• 如果numBufferedDocs空间不足了，需要扩容
  
• 记录doc对应的field个数
  
• 记录doc数据在bufferedDocs中的结束位置
  
• 判断如果满足一个chunk的生成，则生成chunk
  

  public void finishDocument() throws IOException {

    if (numBufferedDocs == this.numStoredFields.length) {

      final int newLength = ArrayUtil.oversize(numBufferedDocs + 1, 4);

      this.numStoredFields = ArrayUtil.growExact(this.numStoredFields, newLength);

      endOffsets = ArrayUtil.growExact(endOffsets, newLength);

    }

    // 记录doc对应的field个数  

    this.numStoredFields[numBufferedDocs] = numStoredFieldsInDoc;

    numStoredFieldsInDoc = 0;

    // 记录当前doc在bufferedDocs中的结束位置

    endOffsets[numBufferedDocs] = Math.toIntExact(bufferedDocs.size());

    ++numBufferedDocs;

    if (triggerFlush()) {

      flush(false);

    }

  }

生成一个chunk

生成一个chunk的条件：

• 
  
• bufferDocs缓存超出了chunkSize
  
• chunk中收集的doc数量超出了maxDocsPerChunk
  
• 强制生成
  

  // 生成一个chunk的条件

  // 1.bufferDocs缓存超出了chunkSize

  // 2.chunk中收集的doc数量超出了maxDocsPerChunk

  private boolean triggerFlush() {

    return bufferedDocs.size() >= chunkSize || numBufferedDocs >= maxDocsPerChunk;

  } 


  private void flush(boolean force) throws IOException {

    // chunk数+1  

    numChunks++;

    if (force) { // 如果是强制构建chunk，可能是不满足chunk条件的，这种chunk被定义为dirtyChunk

      numDirtyChunks++;

      numDirtyDocs += numBufferedDocs;

    }

    // 生成chunk的索引  

    indexWriter.writeIndex(numBufferedDocs, fieldsStream.getFilePointer());


    // 把各个doc在bufferedDocs中的endOffsets转成length

    final int[] lengths = endOffsets;

    for (int i = numBufferedDocs - 1; i > 0; --i) {

      lengths[i] = endOffsets[i] - endOffsets[i - 1];

    }

    // 如果当前chunk的大小超出了2倍chunkSize，则需要分片  

    final boolean sliced = bufferedDocs.size() >= 2 * chunkSize;

    final boolean dirtyChunk = force;

    writeHeader(docBase, numBufferedDocs, numStoredFields, lengths, sliced, dirtyChunk);


    // 下面是压缩处理

    byte[] content = bufferedDocs.toArrayCopy();

    bufferedDocs.reset();


    if (sliced) {

      // big chunk, slice it

      for (int compressed = 0; compressed < content.length; compressed += chunkSize) {

        compressor.compress(

            content, compressed, Math.min(chunkSize, content.length - compressed), fieldsStream);

      }

    } else {

      compressor.compress(content, 0, content.length, fieldsStream);

    }


    // 更新下一个chunk的起始docID

    docBase += numBufferedDocs;

    // 重置doc数统计  

    numBufferedDocs = 0;

    bufferedDocs.reset();

  }


  private static void saveInts(int[] values, int length, DataOutput out) throws IOException {

    if (length == 1) {

      out.writeVInt(values[0]);

    } else {

      StoredFieldsInts.writeInts(values, 0, length, out);

    }

  }


  private void writeHeader(

      int docBase,

      int numBufferedDocs,

      int[] numStoredFields,

      int[] lengths,

      boolean sliced,

      boolean dirtyChunk)

      throws IOException {

    final int slicedBit = sliced ? 1 : 0;

    final int dirtyBit = dirtyChunk ? 2 : 0;

    // save docBase and numBufferedDocs

    fieldsStream.writeVInt(docBase);

    fieldsStream.writeVInt((numBufferedDocs << 2) | dirtyBit | slicedBit);


    // save numStoredFields

    saveInts(numStoredFields, numBufferedDocs, fieldsStream);


    // save lengths

    saveInts(lengths, numBufferedDocs, fieldsStream);

  }

结束构建

结束构建的时候最重要的就是生成fdx索引文件。

  public void finish(int numDocs) throws IOException {

    if (numBufferedDocs > 0) { // 如果还有未处理的doc，强制生成一个chunk

      flush(true);

    } else {

      assert bufferedDocs.size() == 0;

    }

    if (docBase != numDocs) {

      throw new RuntimeException(

          "Wrote " + docBase + " docs, finish called with numDocs=" + numDocs);

    }

    // 构建fdx文件  

    indexWriter.finish(numDocs, fieldsStream.getFilePointer(), metaStream);

    // 记录一些元信息  

    metaStream.writeVLong(numChunks);

    metaStream.writeVLong(numDirtyChunks);

    metaStream.writeVLong(numDirtyDocs);

    CodecUtil.writeFooter(metaStream);

    CodecUtil.writeFooter(fieldsStream);

    assert bufferedDocs.size() == 0;

  }

}