ORC源码阅读(2) - OrcProto

读了mapreduce module之后，对orc的代码有了大概的了解，其实顺着RecordReader、Write和OrcFile、OrcStruct往下读就会有很多和protocol buffers有关的东西。其实如果对orc没有基本了解的话，应该先结合orc的文档读一下proto文件，这个文件在orc源码的proto目录下，文件名为orc_proto.proto。

orc使用protocol buffers来定义一个orc file中元数据的结构。在编译orc源码的时候，会根据proto文件中的message定义生成相应的类，以及类序列化、反序列化的java代码。生成的代码默认在java/core/target/generated_sources/org/apache/orc/OrcProto.java中。但是在实际读写orc file的时候，序列化和反序列化并不完全依赖与生成的代码，比如写FileTail的时候，按照proto中的定义，应该是先写postscript再写footer，而实际上在orc的org.apache.orc.impl.WriterImpl中，是先写footer再写postscript的。

Documentation

首先看一下文档中的文件格式相关的重点：

Type

https://orc.apache.org/docs/types.html
All ORC file are logically sequences of identically typed objects. Hive always uses a struct with a field for each of the top-level columns as the root object type, but that is not required. All types in ORC can take null values including the compound types.

Index

https://orc.apache.org/docs/indexes.html
https://orc.apache.org/docs/spec-index.html
这两个全程重点

Introduction

https://orc.apache.org/docs/spec-intro.html
全程重点

FileTail

https://orc.apache.org/docs/file-tail.html
全程重点

Compression

https://orc.apache.org/docs/compression.html
随便看看

Stripe

https://orc.apache.org/docs/stripes.html
全程重点

ColumnEncoding

https://orc.apache.org/docs/encodings.html
全程重点，这个对理解proto定义很关键
https://orc.apache.org/docs/run-length.html
随便看看，介绍了数值型的列怎么做RLE。

然后开始读proto文件。
这个文件可以从前往后大概读一遍，然后从后往前细细的读。我们就从后往前读。

FileTail

FileTail是一个Orc文件的尾部。对应于Introduction的图中文件结构最后的那一小块。定义如下：

message FileTail {
  optional PostScript postscript = 1;
  optional Footer footer = 2;
  optional uint64 fileLength = 3;
  optional uint64 postscriptLength = 4;
}

这个FileTail的定义其实是有问题的，和文档不一致（https://orc.apache.org/docs/spec-intro.html、https://orc.apache.org/docs/file-tail.html），而文档中的部分内容又和以及实际的orc file中的内容不一致。感觉这是有意的，不知道为啥要这样，可能就是因为懒得弄或者作者的某种癖好吧。一切以实际的orc file中写入的内容为准，在WriterImpl中可以看到：

  private long writeFooter() throws IOException {
    writeMetadata();
    OrcProto.Footer.Builder builder = OrcProto.Footer.newBuilder();
    builder.setNumberOfRows(rowCount);
    builder.setRowIndexStride(rowIndexStride);
    rawDataSize = computeRawDataSize();
    // serialize the types
    writeTypes(builder, schema);
    // add the stripe information
    for(OrcProto.StripeInformation stripe: stripes) {
      builder.addStripes(stripe);
    }
    // add the column statistics
    writeFileStatistics(builder, treeWriter);
    // add all of the user metadata
    for(Map.Entry<String, ByteString> entry: userMetadata.entrySet()) {
      builder.addMetadata(OrcProto.UserMetadataItem.newBuilder()
        .setName(entry.getKey()).setValue(entry.getValue()));
    }
    builder.setWriter(OrcFile.WriterImplementation.ORC_JAVA.getId());
    physicalWriter.writeFileFooter(builder);
    return writePostScript();
  }

在写文件的footer的writeFooter方法中，最开始就写入了metadata，最后写入了postscript。
可见：
1. FileTail里面实际上是有Metadata的；
2. 虽然postscript的id是1，但是实际上在序列化的时候，会先序列化footer再序列化postscript
实际上，在读取一个orc file的时候，会先从文件的末尾读取16KB，并从最后一个字节中取出postscript的长度（虽然postscriptLength是64位，但是实际上postscript长度不超过255个字节，所以只用了一个字节）。

PostScript

定义如下：

message PostScript {
  optional uint64 footerLength = 1;
  optional CompressionKind compression = 2;
  optional uint64 compressionBlockSize = 3;
  repeated uint32 version = 4 [packed = true];
  optional uint64 metadataLength = 5;
  optional uint32 writerVersion = 6;
  optional string magic = 8000;
}

从postscript中就知道footer的长度、压缩算法、元数据长度，然后就可以计算出footer和metadata所在的偏移。

File Footer

定义如下：

message Footer {
  optional uint64 headerLength = 1;
  optional uint64 contentLength = 2;
  repeated StripeInformation stripes = 3;
  repeated Type types = 4;
  repeated UserMetadataItem metadata = 5;
  optional uint64 numberOfRows = 6;
  repeated ColumnStatistics statistics = 7;
  optional uint32 rowIndexStride = 8;

  // Each implementation that writes ORC files should register for a code
  // 0 = ORC Java
  // 1 = ORC C++
  // 2 = Presto
  optional uint32 writer = 9;
}

headerLength永远是3，orc file会在文件开头存’ORC’3个字符，占用3个字节，这个叫做header，用来告诉其他不明所以的file reader这是个ORC文件，不要乱读。其他字段的解释看文档https://orc.apache.org/docs/file-tail.html.

其中stripes就是各个stripe的元数据，types是文件的schema。rowIndexStride是个配置参数，指一个index entry中最大的行数。这个index entry就是指proto中的RowIndexEntry，一个stripe中有很多column，每个column上的每10000行为一个row group，一个row group上面有一个RowIndexEntry。

stripes就是存了各个stripe的偏移和stripe中index、data、footer等部分的length。定义如下：

message StripeInformation {
  optional uint64 offset = 1;
  optional uint64 indexLength = 2;
  optional uint64 dataLength = 3;
  optional uint64 footerLength = 4;
  optional uint64 numberOfRows = 5;
}

types是个很有意思的结构，目测（我也不是非常确定）types对应于https://orc.apache.org/docs/types.html 最后那个图里面的那棵树上的各个节点，节点上的id就是在types数组中的下标。可以看一下Type的定义：

message Type {
  enum Kind {
    BOOLEAN = 0;
    BYTE = 1;
    SHORT = 2;
    INT = 3;
    LONG = 4;
    FLOAT = 5;
    DOUBLE = 6;
    STRING = 7;
    BINARY = 8;
    TIMESTAMP = 9;
    LIST = 10;
    MAP = 11;
    STRUCT = 12;
    UNION = 13;
    DECIMAL = 14;
    DATE = 15;
    VARCHAR = 16;
    CHAR = 17;
  }
  optional Kind kind = 1;
  repeated uint32 subtypes = 2 [packed=true];
  repeated string fieldNames = 3;
  optional uint32 maximumLength = 4;
  optional uint32 precision = 5;
  optional uint32 scale = 6;
}

其中的subtypes和fieldNames应该分别是该节点的孩子节点在types的下标和名称。如果是这样，那么types就是一颗以数组形式存储的树，这样存确实非常方便也比较省空间。

Metadata

Metadata分为UserMetadata和Metadata。UserMetadata是作为footer一部分存储的，在上面的footer定义中可以看到。定义如下：

message UserMetadataItem {
  optional string name = 1;
  optional bytes value = 2;
}

就是一个key-value的形式，没啥好说的，用来让用户自定义些什么东西放在footer里面。
Metadata的定义如下：

message Metadata {
  repeated StripeStatistics stripeStats = 1;
}

message StripeStatistics {
  repeated ColumnStatistics colStats = 1;
}

message ColumnStatistics {
  optional uint64 numberOfValues = 1;
  optional IntegerStatistics intStatistics = 2;
  optional DoubleStatistics doubleStatistics = 3;
  optional StringStatistics stringStatistics = 4;
  optional BucketStatistics bucketStatistics = 5;
  optional DecimalStatistics decimalStatistics = 6;
  optional DateStatistics dateStatistics = 7;
  optional BinaryStatistics binaryStatistics = 8;
  optional TimestampStatistics timestampStatistics = 9;
  optional bool hasNull = 10;
}

message IntegerStatistics  {
  optional sint64 minimum = 1;
  optional sint64 maximum = 2;
  optional sint64 sum = 3;
}

message DoubleStatistics {
  optional double minimum = 1;
  optional double maximum = 2;
  optional double sum = 3;
}

message StringStatistics {
  optional string minimum = 1;
  optional string maximum = 2;
  // sum will store the total length of all strings in a stripe
  optional sint64 sum = 3;
}

message BucketStatistics {
  repeated uint64 count = 1 [packed=true];
}

message DecimalStatistics {
  optional string minimum = 1;
  optional string maximum = 2;
  optional string sum = 3;
}

message DateStatistics {
  // min,max values saved as days since epoch
  optional sint32 minimum = 1;
  optional sint32 maximum = 2;
}

message TimestampStatistics {
  // min,max values saved as milliseconds since epoch
  optional sint64 minimum = 1;
  optional sint64 maximum = 2;
  optional sint64 minimumUtc = 3;
  optional sint64 maximumUtc = 4;
}

message BinaryStatistics {
  // sum will store the total binary blob length in a stripe
  optional sint64 sum = 1;
}

虽然长了点，但是很清晰，就是存了一个orc file中各个stripe中的各个column上的统计信息，如最大值、最小值等等。

FileTail这样就算是基本捋清楚了。

Stripe

一个Orc file除了末尾的file tail和开头的三字节header这两部分，就是file tail和header之间的各个stripe。
如https://orc.apache.org/docs/spec-intro.html 所述，每个stripe有index、data、footer三个部分。注意这里的footer是stripe footer，不是file footer。

Stripe Footer

首先看footer定义如下：

message StripeFooter {
  repeated Stream streams = 1;
  repeated ColumnEncoding columns = 2;
  optional string writerTimezone = 3;
}

message Stream {
  // if you add new index stream kinds, you need to make sure to update
  // StreamName to ensure it is added to the stripe in the right area
  enum Kind {
    PRESENT = 0;
    DATA = 1;
    LENGTH = 2;
    DICTIONARY_DATA = 3;
    DICTIONARY_COUNT = 4;
    SECONDARY = 5;
    ROW_INDEX = 6;
    BLOOM_FILTER = 7;
    BLOOM_FILTER_UTF8 = 8;
  }
  optional Kind kind = 1;
  optional uint32 column = 2;
  optional uint64 length = 3;
}

message ColumnEncoding {
  enum Kind {
    DIRECT = 0;
    DICTIONARY = 1;
    DIRECT_V2 = 2;
    DICTIONARY_V2 = 3;
  }
  optional Kind kind = 1;
  optional uint32 dictionarySize = 2;

  // The encoding of the bloom filters for this column:
  //   0 or missing = none or original
  //   1            = ORC-135 (utc for timestamps)
  optional uint32 bloomEncoding = 3;
}

这个有点复杂，一个footer中有若干个stream和若干个column encoding，参见https://orc.apache.org/docs/encodings.html，这里面讲了stream和column encoding到底是啥关系。这块太复杂了，后面慢慢补充。

Index

Stripe的data部分就不用定义了，反正就是二进制数据。Index部分的定义如下：

message RowIndexEntry {
  repeated uint64 positions = 1 [packed=true];
  optional ColumnStatistics statistics = 2;
}

message RowIndex {
  repeated RowIndexEntry entry = 1;
}

message BloomFilter {
  optional uint32 numHashFunctions = 1;
  repeated fixed64 bitset = 2;
  optional bytes utf8bitset = 3;
}

message BloomFilterIndex {
  repeated BloomFilter bloomFilter = 1;
}

详细的参见：
https://orc.apache.org/docs/indexes.html
https://orc.apache.org/docs/spec-index.html