Apache Arrow官方文档-元数据

cwx

元数据：逻辑类型，模式，数据头
　　这是Arrow元数据规范的文档，它使系统能够通信

• 逻辑数组类型（使用Layout.md中指定的物理内存布局实现）
  
• Arrow数据结构的表格集合的模式
  
• “数据头”指明内存缓冲区的物理位置，内存缓冲区不复制内存而足以重建Arrow数据结构。
  规范实现
  　　我们正在使用Flatbuffers进行低开销读写Arrow元数据。请参阅Message.fbs。
  
  架构
  　　  Schema类型描述了由任意数量的Arrow数组组成的表状结构，每个Arrow数组可以被解释为表中的一列。模式本身不描述任何特定数据集的物理结构。
  
  　　模式由一系列字段组成，这些字段是描述列的元数据。Flatbuffers>　　
  
  table Field {　　
  // Name is not required, in i.e. a List
  　　
  name: string;
  　　
  nullable: bool;
  　　
  type: Type;
  　　
  // present only if the field is dictionary encoded
  　　
  // will point to a dictionary provided by a DictionaryBatch message
  　　
  dictionary: long;
  　　
  // children apply only to Nested data types like Struct, List and Union
  　　
  children: [Field];
  　　
  /// layout of buffers produced for this type (as derived from the Type)
  　　
  /// does not include children
  　　
  /// each recordbatch will return instances of those Buffers.
  　　
  layout: [ VectorLayout ];
  　　
  // User-defined metadata
  　　
  custom_metadata: [ KeyValue ];
  　　
  }
  　　
  
  　　type是字段的逻辑类型。嵌套类型（如List，Struct和Union）具有一系列子字段。
  　　还提供了该模式的JSON表示形式：字段：
  　　
  
  {　　
  "name" : "name_of_the_field",
  　　
  "nullable" : false,
  　　
  "type" : /* Type */,
  　　
  "children" : [ /* Field */ ],
  　　
  "typeLayout" : {
  　　
  "vectors" : [ /* VectorLayout */ ]
  　　
  }
  　　
  }
  　　
  
  　　VectorLayout：
  
  

　　

{　　"type" : "DATA|OFFSET|VALIDITY|TYPE",
　　"typeBitWidth" : /* int */
　　
}
　　

　　
Type:
　　
{
　　"name" :"null|struct|list|union|int|floatingpoint|utf8|binary|fixedsizebinary|bool|decimal|date|time|timestamp|interval"
　　// fields as defined in the Flatbuffer depending on the type name
　　
}
　　

　　
Union:
　　
{
　　"name" : "union",
　　"mode" : "Sparse|Dense",
　　"typeIds" : [ /* integer */ ]
　　
}
　　

　　在Union中的typeIds字段是用于表示每种类型的编码，其可以与从子数组的索引不同。这样就可以使用联合类型ids不需要从0开始枚举。
　　Int：
　　

{　　"name" : "int",
　　"bitWidth" : /* integer */,
　　"isSigned" : /* boolean */
　　
}
　　

　　FloatingPoint：
　　

{　　"name" : "floatingpoint",
　　"precision" : "HALF|SINGLE|DOUBLE"
　　
}
　　

　　Decimal：
　　

{　　"name" : "decimal",
　　"precision" : /* integer */,
　　"scale" : /* integer */
　　
}
　　

　　Timestamp：
　　

{　　"name" : "timestamp",
　　"unit" : "SECOND|MILLISECOND|MICROSECOND|NANOSECOND"
　　
}
　　

　　Date：
　　

{　　"name" : "date",
　　"unit" : "DAY|MILLISECOND"
　　
}
　　

　　Time：
　　

{　　"name" : "time",
　　"unit" : "SECOND|MILLISECOND|MICROSECOND|NANOSECOND",
　　"bitWidth": /* integer: 32 or 64 */
　　
}
　　

　　Interval：
　　

{　　"name" : "interval",
　　"unit" : "YEAR_MONTH|DAY_TIME"
　　
}
　　

　　
Schema：
　　
{
　　"fields" : [
　　/* Field */
　　]
　　
}
　　

记录数据头
　　  RecordBatch是顶级命名的等长Arrow数组（或向量）的集合。如果其中一个数组包含嵌套数据，则其子数组不需要与顶级数组的长度相同。
　　  可以被认为是特定模式的实现。描述特定RecordBatch的元数据称为“数据头”。这是用于RecordBatch数据头的Flatbuffers的IDL
　　

table RecordBatch {　　length: long;
　　nodes: [FieldNode];
　　buffers: [Buffer];
　　
}
　　

　　  所述RecordBatch元数据提供与长度超过2^31- 1的记录批次，但Arrow实现不要求实现支持超出这一大小。
　　  通过对给定的内存中数据集的模式（可能包含嵌套类型）进行深度优先遍历/扁平化，生成nodes和buffers字段。

缓冲区
　　  缓冲区是描述相对于某些虚拟地址空间的连续内存区域的元数据。这可能包括：

• 共享内存，例如内存映射文件
  
• 在内存中接收到RPC消息
  
• 　　文件中的数据
  　　缓冲区类型的键形式是：
  　　
  
  struct Buffer {　　
  offset: long;
  　　
  length: long;
  　　
  }
  　　
  
  　　  在record batch的上下文中，每个字段具有与其相关联的一些数量的缓冲区，它们源于其物理内存布局。
  　　  每个逻辑类型（与其子节点分开，如果它是一个嵌套类型）具有与之相关联的确定性数量的缓冲区。这些将在逻辑类型部分中指定。
  
  字段元数据
  　　  所述FieldNode值包含关于在嵌套类型层次每个等级的元数据。
  　　
  
  struct FieldNode {　　
  /// The number of value slots in the Arrow array at this level of a nested
  　　
  /// tree
  　　
  length: long;
  　　
  
  　　
  /// The number of observed nulls.
  　　
  null_count: lohng;
  　　
  }
  　　
  
  　　  所述FieldNode元数据提供长度超过2^31- 1的字段，但是Arrow不要求实现支持大型数组。
  
  

平铺嵌套数据
　　  嵌套类型以深度优先顺序在record batch中扁平化。当访问嵌套类型树中的每个字段时，元数据将附加到顶级fields数组，并将与该字段相关联的缓冲区（但不是其子级）附加到buffers数组。
　　  例如，让我们考虑模式：
　　

col1: Struct　　
col2: Utf8
　　

　　其扁平化版本是：
　　

FieldNode 0: Struct name='col1'　　
FieldNode 1: Int32 name=a'
　　
FieldNode 2: List name='b'
　　
FieldNode 3: Int64 name='item'  # arbitrary
　　
FieldNode 4: Float64 name='c'
　　
FieldNode 5: Utf8 name='col2'
　　

　　  对于生成的缓冲区，将具有以下内容（如下面对于每种类型的更详细描述）：
　　

buffer 0: field 0 validity bitmap　　

　　
buffer 1: field 1 validity bitmap
　　
buffer 2: field 1 values
　　

　　
buffer 3: field 2 validity bitmap
　　
buffer 4: field 2 list offsets
　　

　　
buffer 5: field 3 validity bitmap
　　
buffer 6: field 3 values
　　

　　
buffer 7: field 4 validity bitmap
　　
buffer 8: field 4 values
　　

　　
buffer 9: field 5 validity bitmap
　　
buffer 10: field 5 offsets
　　
buffer 11: field 5 data
　　

逻辑类型
　　  逻辑类型由类型名称和元数据以及对物理内存表示的显式映射组成。这些可能分为不同的类别：

• 表示为固定宽度基本类型数组（例如：C风格的整数和浮点数）
  
• 具有与物理嵌套类型相等的内存布局的类型（例如，字符串使用列表（List）表示，但逻辑上不是嵌套类型）
  整型
  　　  在Arrow的第一个版本中，我们提供标准的8位到64位大小的标准C整数类型，包括有符号和无符号：
  　　● 有符号类型：Int8，Int16，Int32，Int64
  　　● 无符号类型：UInt8，UInt16，UInt32，UInt64
  　　  IDL看起来像：
  　　
  
  table Int {　　
  bitWidth: int;
  　　
  is_signed: bool;
  　　
  }
  
  

　　  整数字节顺序当前在模式级别全局设置。如果一个模式设置为little-endian（低位编址），那么出现在其中的所有整数类型都必须是little-endian。整数作为其他数据表示的一部分（如列表偏移量和联合类型）必须与整个Record Batch具有相同的字节顺序。

浮点数字
　　  我们提供3种类型的浮点数作为固定位宽的基本数组

• 半精度，16位宽
  
• 单精度，32位宽
  
• 双精度，64位宽　　IDL与下述类似：
  
  

　　

enum Precision:int {HALF, SINGLE, DOUBLE}　　

　　
table FloatingPoint {
　　precision: Precision;
　　
}
　　

Boolean
　　  布尔逻辑类型表示为1位宽的基本(原语)物理类型。这些位使用最低有效位（LSB）排序进行编号。
　　  像其他固定的位宽基本类型一样，布尔数据在数据头中显示为2个缓冲区（一个位图为有效向量，另一个为值）。

List
　　  List逻辑类型是（和相同名称）列表物理类型的逻辑对应。
　　  在数据头格式中，List字段节点包含2个缓冲区：

• 有效位图
  
• 列表偏移量　　  与List的子字段相关联的缓冲区根据子逻辑类型（例如，List对List）递归地处理。
  
  Utf8和Binary
  　　  我们为可变长度字节指定两种逻辑类型：
  
  
• Utf8 数据是具有UTF-8编码的unicode值
  
• Binary 是任何其他可变长度字节　　  这些类型都与嵌套类型List具有相同的内存布局，其约束是内部字节不能包含空值。从逻辑类型的角度来看，它们是原始的，而不是嵌套类型。
  　　  在数据头格式中，虽然List会显示为2个字段节点（List 和UInt8）和4个缓冲区（每个节点为2个，如上所述），这些类型也有简单的表示单字段节点（Utf8或Binary 逻辑类型，没有子节点）和3个缓冲区：
  
  
• 有效位图
  
• 列表偏移量
  
• 字节数据
  
• 
  Decimal
  　　  TBD
  
  

Timestamp
　　  所有时间戳都以64位整数存储，有四个单位：秒，毫秒，微秒和纳秒。

Date
　　  支持两种不同的日期类型：

• 自UNIX epoch以来的天数为32位整数
  
• 从UNIX epoch开始的毫秒数为64位整数
  

Time
　　  时间支持相同的单位：秒，毫秒，微秒和纳秒。我们将时间表示为容纳指定单位的最小整数。对于秒和毫秒：32位，其他64位。

字典编码