.. Licensed to the Apache Software Foundation (ASF) under one .. or more contributor license agreements. See the NOTICE file .. distributed with this work for additional information .. regarding copyright ownership. The ASF licenses this file .. to you under the Apache License, Version 2.0 (the .. "License"); you may not use this file except in compliance .. with the License. You may obtain a copy of the License at

.. http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing, .. software distributed under the License is distributed on an .. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY .. KIND, either express or implied. See the License for the .. specific language governing permissions and limitations .. under the License.

.. _glossary:

======== Glossary

.. glossary:: :sorted:

array vector A contiguous, one-dimensional sequence of values with known length where all values have the same type. An array consists of zero or more :term:buffers <buffer>, a non-negative length, and a :term:data type. The buffers of an array are laid out according to the data type as defined by the columnar format.

   Arrays are contiguous in the sense that iterating the values of
   an array will iterate through a single set of buffers, even
   though an array may consist of multiple disjoint buffers, or
   may consist of child arrays that themselves span multiple
   buffers.

   Arrays are one-dimensional in that they are a sequence of
   :term:`slots <slot>` or singular values, even though for some
   data types (like structs or unions), a slot may represent
   multiple values.

   Defined by the :doc:`./Columnar`.

buffer A contiguous region of memory with a given length. Buffers are used to store data for arrays.

   Buffers may be in CPU memory, memory-mapped from a file, in
   device (e.g. GPU) memory, etc., though not all Arrow
   implementations support all of these possibilities.

canonical extension type An :term:extension type that has been standardized by the Arrow community so as to improve interoperability between implementations.

   .. seealso::
      :ref:`format_canonical_extensions`.

child array parent array In an array of a :term:nested type, the parent array corresponds to the :term:parent type and the child array(s) correspond to the :term:child type(s) <child type>. For example, a List[Int32]-type parent array has an Int32-type child array.

child type parent type In a :term:nested type, the nested type is the parent type, and the child type(s) are its parameters. For example, in List[Int32], List is the parent type and Int32 is the child type.

chunked array A discontiguous, one-dimensional sequence of values with known length where all values have the same type. Consists of zero or more :term:arrays <array>, the "chunks".

   Chunked arrays are discontiguous in the sense that iterating
   the values of a chunked array may require iterating through
   different buffers for different indices.

   Not part of the columnar format; this term is specific to
   certain language implementations of Arrow (primarily C++ and
   its bindings).

   .. seealso:: :term:`record batch`, :term:`table`

complex type nested type A :term:data type whose structure depends on one or more other :term:child data types <child type>. For instance, List is a nested type that has one child.

   Two nested types are equal if and only if their child types are
   also equal.

data type type A type that a value can take, such as Int8 or List[Utf8]. The type of an array determines how its values are laid out in memory according to :doc:./Columnar.

   .. seealso:: :term:`nested type`, :term:`primitive type`

dictionary An array of values that accompany a :term:dictionary-encoded <dictionary-encoding> array.

dictionary-encoding An array that stores its values as indices into a :term:dictionary array instead of storing the values directly.

   .. seealso:: :ref:`dictionary-encoded-layout`

extension type storage type An extension type is an user-defined :term:data type that adds additional semantics to an existing data type. This allows implementations that do not support a particular extension type to still handle the underlying data type (the "storage type").

   For example, a UUID can be represented as a 16-byte fixed-size
   binary type.

   .. seealso:: :ref:`format_metadata_extension_types`

field A column in a :term:schema. Consists of a field name, a :term:data type, a flag indicating whether the field is nullable or not, and optional key-value metadata.

IPC format A specification for how to serialize Arrow data, so it can be sent between processes/machines, or persisted on disk.

   .. seealso:: :term:`IPC file format`,
                :term:`IPC streaming format`

IPC file format file format random-access format An extension of the :term:IPC streaming format that can be used to serialize Arrow data to disk, then read it back with random access to individual record batches.

IPC message message The IPC representation of a particular in-memory structure, like a :term:record batch or :term:schema. Will always be one of the members of MessageHeader in the Flatbuffers protocol file <https://github.com/apache/arrow/blob/main/format/Message.fbs>_.

IPC streaming format streaming format A protocol for streaming Arrow data or for serializing data to a file, consisting of a stream of :term:IPC messages <IPC message>.

physical layout A specification for how to arrange values in memory.

   .. seealso:: :ref:`format_layout`

primitive type A data type that does not have any child types.

   .. seealso:: :term:`data type`

record batch In the :ref:IPC format <format-ipc>: the primitive unit of data. A record batch consists of an ordered list of :term:buffers <buffer> corresponding to a :term:schema.

   **In some implementations** (primarily C++ and its bindings): a
   *contiguous*, *two-dimensional* chunk of data.  A record batch
   consists of an ordered collection of :term:`arrays <array>` of
   the same length.

   Like arrays, record batches are contiguous in the sense that
   iterating the rows of a record batch will iterate through a
   single set of buffers.

schema A collection of :term:fields <field> with optional metadata that determines all the :term:data types <data type> of an object like a :term:record batch or :term:table.

slot A single logical value within an array, i.e. a "row".

table A discontiguous, two-dimensional chunk of data consisting of an ordered collection of :term:chunked arrays <chunked array>. All chunked arrays have the same length, but may have different types. Different columns may be chunked differently.

   Like chunked arrays, tables are discontiguous in the sense that
   iterating the rows of a table may require iterating through
   different buffers for different indices.

   Not part of the columnar format; this term is specific to
   certain language implementations of Arrow (for example C++ and
   its bindings, and Go).

   .. image:: ../cpp/tables-versus-record-batches.svg
      :alt: A graphical representation of an Arrow Table and a
            Record Batch, with structure as described in text above.

   .. seealso:: :term:`chunked array`, :term:`record batch`