# `Adbc.Column`
[🔗](https://github.com/elixir-explorer/adbc/blob/v0.9.0/lib/adbc_column.ex#L1)

Documentation for `Adbc.Column`.

`Adbc.Column` corresponds to a column in the table. It contains the column's name, type, and
data. The data is a list of values of the column's data type.

# `data_type`

```elixir
@type data_type() ::
  :boolean
  | signed_integer()
  | unsigned_integer()
  | floating()
  | :list
  | :large_list
  | :list_view
  | :large_list_view
  | {:fixed_size_list, s32()}
  | :binary
  | :large_binary
  | :binary_view
  | :string
  | :large_string
  | :string_view
  | decimal()
  | {:fixed_size_binary, non_neg_integer()}
  | {:struct, t()}
  | :date32
  | :date64
  | time()
  | timestamp()
  | duration()
  | interval()
  | :run_end_encoded
  | :dictionary
```

# `decimal128`

```elixir
@type decimal128() :: {:decimal, 128, precision128(), integer()}
```

# `decimal256`

```elixir
@type decimal256() :: {:decimal, 256, precision256(), integer()}
```

# `decimal`

```elixir
@type decimal() :: decimal128() | decimal256()
```

# `dictionary_data`

```elixir
@type dictionary_data() :: %{key: t(), value: t()}
```

# `duration`

```elixir
@type duration() ::
  {:duration, :seconds}
  | {:duration, :milliseconds}
  | {:duration, :microseconds}
  | {:duration, :nanoseconds}
```

# `floating`

```elixir
@type floating() :: :f32 | :f64
```

# `interval`

```elixir
@type interval() ::
  {:interval, :month} | {:interval, :day_time} | {:interval, :month_day_nano}
```

# `interval_day_xime`

```elixir
@type interval_day_xime() :: {s32(), s32()}
```

# `interval_month`

```elixir
@type interval_month() :: s32()
```

# `interval_month_day_nano`

```elixir
@type interval_month_day_nano() :: {s32(), s32(), s64()}
```

# `interval_unit`

```elixir
@type interval_unit() :: :month | :day_time | :month_day_nano
```

# `list_view_data`

```elixir
@type list_view_data() :: %{
  validity: [boolean()],
  offsets: [non_neg_integer()],
  sizes: [non_neg_integer()],
  values: t()
}
```

# `precision128`

```elixir
@type precision128() :: 1..38
```

# `precision256`

```elixir
@type precision256() :: 1..76
```

# `s8`

```elixir
@type s8() :: -128..127
```

# `s16`

```elixir
@type s16() :: -32768..32767
```

# `s32`

```elixir
@type s32() :: -2_147_483_648..2_147_483_647
```

# `s64`

```elixir
@type s64() :: -9_223_372_036_854_775_808..9_223_372_036_854_775_807
```

# `signed_integer`

```elixir
@type signed_integer() :: :s8 | :s16 | :s32 | :s64
```

# `t`

```elixir
@type t() :: %Adbc.Column{
  data: term(),
  length: term(),
  metadata: term(),
  name: term(),
  nullable: term(),
  offset: term(),
  type: term()
}
```

# `time32`

```elixir
@type time32() :: {:time32, :seconds} | {:time32, :milliseconds}
```

# `time64`

```elixir
@type time64() :: {:time64, :microseconds} | {:time64, :nanoseconds}
```

# `time`

```elixir
@type time() :: time32() | time64()
```

# `time_unit`

```elixir
@type time_unit() :: :seconds | :milliseconds | :microseconds | :nanoseconds
```

# `timestamp`

```elixir
@type timestamp() ::
  {:timestamp, :seconds, String.t()}
  | {:timestamp, :milliseconds, String.t()}
  | {:timestamp, :microseconds, String.t()}
  | {:timestamp, :nanoseconds, String.t()}
```

# `u8`

```elixir
@type u8() :: 0..255
```

# `u16`

```elixir
@type u16() :: 0..65535
```

# `u32`

```elixir
@type u32() :: 0..4_294_967_295
```

# `u64`

```elixir
@type u64() :: 0..18_446_744_073_709_551_615
```

# `unsigned_integer`

```elixir
@type unsigned_integer() :: :u8 | :u16 | :u32 | :u64
```

# `binary`

```elixir
@spec binary([iodata() | nil], Keyword.t()) :: t()
```

A column that contains binary values.

## Arguments

* `data`: A list of binary values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.binary([<<0>>, <<1>>, <<2>>])
    %Adbc.Column{
      name: nil,
      type: :binary,
      nullable: false,
      metadata: nil,
      data: [<<0>>, <<1>>, <<2>>]
    }

# `boolean`

```elixir
@spec boolean([boolean()], Keyword.t()) :: t()
```

A column that contains booleans.

## Arguments

* `data`: A list of booleans
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.boolean([true, false, true])
    %Adbc.Column{
      name: nil,
      type: :boolean,
      nullable: false,
      metadata: nil,
      data: [true, false, true]
    }

# `date32`

```elixir
@spec date32([Date.t() | s32() | nil], Keyword.t()) :: t()
```

A column that contains date represented as 32-bit signed integers in UTC.
## Arguments

* `data`: a list, each element of which can be one of the following:
  * a `Date.t()`
  * a 32-bit signed integer representing the number of days since the Unix epoch.
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `date64`

```elixir
@spec date64([Date.t() | s64() | nil], Keyword.t()) :: t()
```

A column that contains date represented as 64-bit signed integers in UTC.
## Arguments

* `data`: a list, each element of which can be one of the following:
  * a `Date.t()`
  * a 64-bit signed integer representing the number of milliseconds since the Unix epoch.
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `decimal128`

```elixir
@spec decimal128(
  [Decimal.t() | integer() | nil],
  precision128(),
  integer(),
  Keyword.t()
) :: t()
```

A column that contains 128-bit decimals.

## Arguments

* `data`: a list, each element can be either
  * a `Decimal.t()`
  * an `integer()`
* `precision`: The precision of the decimal values; precision should be between 1 and 38
* `scale`: The scale of the decimal values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `decimal256`

```elixir
@spec decimal256(
  [Decimal.t() | integer() | nil],
  precision256(),
  integer(),
  Keyword.t()
) :: t()
```

A column that contains 256-bit decimals.

## Arguments

* `data`: a list, each element can be either
  * a `Decimal.t()`
  * an `integer()`
* `precision`: The precision of the decimal values; precision should be between 1 and 76
* `scale`: The scale of the decimal values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `delete_all_metadata`

```elixir
@spec delete_all_metadata(t()) :: t()
```

# `delete_metadata`

```elixir
@spec delete_metadata(t(), String.t()) :: t()
```

# `dictionary`

```elixir
@spec dictionary(t(), t(), Keyword.t()) :: t()
```

Construct an array using dictionary encoding.

Dictionary encoding is a data representation technique to represent values by integers
referencing a dictionary usually consisting of unique values. It can be effective when
you have data with many repeated values.

Any array can be dictionary-encoded. The dictionary is stored as an optional property
of an array. When a field is dictionary encoded, the values are represented by an array
of non-negative integers representing the index of the value in the dictionary. The memory
layout for a dictionary-encoded array is the same as that of a primitive integer layout.
The dictionary is handled as a separate columnar array with its own respective layout.

As an example, you could have the following data:

```elixir
Adbc.Column.string(["foo", "bar", "foo", "bar", nil, "baz"], nullable: true)
```

In dictionary-encoded form, this could appear as:

```elixir
Adbc.Column.dictionary(
  Adbc.Column.string(["foo", "bar", "baz"], nullable: true),
  Adbc.Column.s32([0, 1, 0, 1, nil, 2], nullable: true)
)
```

## Arguments

* `data`: a list, each element of which can be one of the following:
  - `nil`
  - `Adbc.Column`

  Note that each `Adbc.Column` in the list should have the same type.

* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `duration`

```elixir
@spec duration([s64() | nil], time_unit(), Keyword.t()) :: t()
```

A column that contains durations represented as 64-bit signed integers.

## Arguments

* `data`: a list of integer values representing the time in the specified unit

* `unit`: specify the unit of the time value, one of the following:
  * `:seconds`
  * `:milliseconds`
  * `:microseconds`
  * `:nanoseconds`

* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `f16`

```elixir
@spec f16([float() | nil | :infinity | :neg_infinity | :nan], Keyword.t()) :: t()
```

A column that contains 16-bit half-precision floats.

## Arguments

* `data`: A list of 32-bit single-precision float values (will be converted to 16-bit floats in C)
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.f16([1.0, 2.0, 3.0])
    %Adbc.Column{
      name: nil,
      type: :f16,
      nullable: false,
      metadata: nil,
      data: [1.0, 2.0, 3.0]
    }

# `f32`

```elixir
@spec f32([float() | nil | :infinity | :neg_infinity | :nan], Keyword.t()) :: t()
```

A column that contains 32-bit single-precision floats.

## Arguments

* `data`: A list of 32-bit single-precision float values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.f32([1.0, 2.0, 3.0])
    %Adbc.Column{
      name: nil,
      type: :f32,
      nullable: false,
      metadata: nil,
      data: [1.0, 2.0, 3.0]
    }

# `f64`

```elixir
@spec f64([float() | nil | :infinity | :neg_infinity | :nan], Keyword.t()) :: t()
```

A column that contains 64-bit double-precision floats.

## Arguments

* `data`: A list of 64-bit double-precision float values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.f64([1.0, 2.0, 3.0])
    %Adbc.Column{
      name: nil,
      type: :f64,
      nullable: false,
      metadata: nil,
      data: [1.0, 2.0, 3.0]
    }

# `fixed_size_binary`

```elixir
@spec fixed_size_binary([iodata() | nil], non_neg_integer(), Keyword.t()) :: t()
```

A column that contains fixed size binaries.

Similar to `binary/2`, but each binary value has the same fixed size in bytes.

## Arguments

* `data`: A list of binary values
* `nbytes`: The fixed size of the binary values in bytes
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.fixed_size_binary([<<0>>, <<1>>, <<2>>], 1)
    %Adbc.Column{
      name: nil,
      type: {:fixed_size_binary, 1},
      nullable: false,
      metadata: nil,
      data: [<<0>>, <<1>>, <<2>>]
    }

# `fixed_size_list`

```elixir
@spec fixed_size_list([t() | nil], s32(), Keyword.t()) :: t()
```

Similar to `list/2`, but the length of the list is the same.

## Arguments

* `data`: a list, each element of which can be one of the following:
  - `nil`
  - `Adbc.Column`

  Note that each `Adbc.Column` in the list should have the same type and length.

* `fixed_size`: The fixed size of the list.

* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `get_metadata`

```elixir
@spec get_metadata(t(), String.t(), String.t() | nil) :: String.t() | nil
```

# `interval`

```elixir
@spec interval(
  [interval_month() | interval_day_xime() | interval_month_day_nano() | nil],
  interval_unit(),
  Keyword.t()
) :: t()
```

A column that contains durations represented as signed integers.

## Arguments

* `data`: a list, each element of which can be one of the following:
  - if `unit` is `:month`:
    * a 32-bit signed integer representing the number of months.

  - if `unit` is `:day_time`:
    * a 2-tuple, both the number of days and the number of milliseconds are in 32-bit signed integers.

  - if `unit` is `:month_day_nano`:
    * a 3-tuple, the number of months, days, and nanoseconds;
      the number of months and days are in 32-bit signed integers,
      and the number of nanoseconds is in 64-bit signed integers

* `unit`: specify the unit of the time value, one of the following:
  * `:month`
  * `:day_time`
  * `:month_day_nano`

* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `large_binary`

```elixir
@spec large_binary([iodata() | nil], Keyword.t()) :: t()
```

A column that contains large binary values.

Similar to `binary/2`, but for binary values larger than 2GB.

## Arguments

* `data`: A list of binary values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.large_binary([<<0>>, <<1>>, <<2>>])
    %Adbc.Column{
      name: nil,
      type: :large_binary,
      nullable: false,
      metadata: nil,
      data: [<<0>>, <<1>>, <<2>>]
    }

# `large_list`

```elixir
@spec large_list([t() | nil], Keyword.t()) :: t()
```

Similar to `list/2`, but for large lists.

## Arguments

* `data`: a list, each element of which can be one of the following:
  - `nil`
  - `Adbc.Column`

  Note that each `Adbc.Column` in the list should have the same type.

* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `large_string`

```elixir
@spec large_string([String.t() | nil], Keyword.t()) :: t()
```

A column that contains UTF-8 encoded large strings.

Similar to `string/2`, but for strings larger than 2GB.

## Arguments

* `data`: A list of UTF-8 encoded string values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.large_string(["a", "ab", "abc"])
    %Adbc.Column{
      name: nil,
      type: :large_string,
      nullable: false,
      metadata: nil,
      data: ["a", "ab", "abc"]
    }

# `list`

```elixir
@spec list([t() | nil], Keyword.t()) :: t()
```

A column that each row is a list of some type or nil.

## Arguments

* `data`: a list, each element of which can be one of the following:
  - `nil`
  - `Adbc.Column`

  Note that each `Adbc.Column` in the list should have the same type.

* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `materialize`

```elixir
@spec materialize(t()) :: t() | {:error, String.t()}
```

`materialize/1` converts a column's data from reference type to regular Elixir terms.

# `put_metadata`

```elixir
@spec put_metadata(t(), String.t(), String.t()) :: t()
```

# `s8`

```elixir
@spec s8([s8() | nil], Keyword.t()) :: t()
```

A column that contains signed 8-bit integers.

## Arguments

* `data`: A list of signed 8-bit integer values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.s8([1, 2, 3])
    %Adbc.Column{
      name: nil,
      type: :s8,
      nullable: false,
      metadata: nil,
      data: [1, 2, 3]
    }

# `s16`

```elixir
@spec s16([s16() | nil], Keyword.t()) :: t()
```

A column that contains signed 16-bit integers.

## Arguments

* `data`: A list of signed 16-bit integer values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.s16([1, 2, 3])
    %Adbc.Column{
      name: nil,
      type: :s16,
      nullable: false,
      metadata: nil,
      data: [1, 2, 3]
    }

# `s32`

```elixir
@spec s32([s32() | nil], Keyword.t()) :: t()
```

A column that contains 32-bit signed integers.

## Arguments

* `data`: A list of 32-bit signed integer values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.s32([1, 2, 3])
    %Adbc.Column{
      name: nil,
      type: :s32,
      nullable: false,
      metadata: nil,
      data: [1, 2, 3]
    }

# `s64`

```elixir
@spec s64([s64() | nil], Keyword.t()) :: t()
```

A column that contains 64-bit signed integers.

## Arguments

* `data`: A list of 64-bit signed integer values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.s64([1, 2, 3])
    %Adbc.Column{
      name: nil,
      type: :s64,
      nullable: false,
      metadata: nil,
      data: [1, 2, 3]
    }

# `string`

```elixir
@spec string([String.t() | nil], Keyword.t()) :: t()
```

A column that contains UTF-8 encoded strings.

## Arguments

* `data`: A list of UTF-8 encoded string values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.string(["a", "ab", "abc"])
    %Adbc.Column{
      name: nil,
      type: :string,
      nullable: false,
      metadata: nil,
      data: ["a", "ab", "abc"]
    }

# `time`

```elixir
@spec time([Time.t() | nil] | [s64() | nil], time_unit(), Keyword.t()) :: t()
```

A column that contains time represented as signed integers in UTC.
## Arguments

* `data`:
  * a list of `Time.t()` value
  * a list of integer values representing the time in the specified unit

    Note that when using `:seconds` or `:milliseconds` as the unit,
    the time value is limited to the range of 32-bit signed integers.

    For `:microseconds` and `:nanoseconds`, the time value is limited to the range of 64-bit signed integers.

* `unit`: specify the unit of the time value, one of the following:
  * `:seconds`
  * `:milliseconds`
  * `:microseconds`
  * `:nanoseconds`

* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `timestamp`

```elixir
@spec timestamp(
  [NaiveDateTime.t() | nil] | [s64() | nil],
  time_unit(),
  String.t(),
  Keyword.t()
) :: t()
```

A column that contains timestamps represented as signed integers in the given timezone.

## Arguments

* `data`:
  * a list of `NaiveDateTime.t()` value
  * a list of 64-bit signed integer values representing the time in the specified unit

* `unit`: specify the unit of the time value, one of the following:
  * `:seconds`
  * `:milliseconds`
  * `:microseconds`
  * `:nanoseconds`

* `timezone`: the timezone of the timestamp

* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

# `to_list`

```elixir
@spec to_list(t()) :: [term()]
```

Convert a list view, run-end encoding array or a dictionary to a list.

## Examples

    iex> list_view = %Adbc.Column{
    ...>   name: nil,
    ...>   type: :list_view,
    ...>   nullable: true,
    ...>   metadata: nil,
    ...>   data: %{
    ...>     values: %Adbc.Column{
    ...>       name: "item",
    ...>       type: :s32,
    ...>       nullable: false,
    ...>       metadata: nil,
    ...>       data: [0, -127, 127, 50, 12, -7, 25]
    ...>     },
    ...>     validity: [true, false, true, true, true],
    ...>     offsets: [4, 7, 0, 0, 3],
    ...>     sizes: [3, 0, 4, 0, 2]
    ...>   }
    ...> }
    iex> Adbc.Column.to_list(list_view)
    [[12, -7, 25], nil, [0, -127, 127, 50], [], ~c"2"]

# `u8`

```elixir
@spec u8([u8() | nil], Keyword.t()) :: t()
```

A column that contains unsigned 8-bit integers.

## Arguments

* `data`: A list of unsigned 8-bit integer values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.u8([1, 2, 3])
    %Adbc.Column{
      name: nil,
      type: :u8,
      nullable: false,
      metadata: nil,
      data: [1, 2, 3]
    }

# `u16`

```elixir
@spec u16([u16() | nil], Keyword.t()) :: t()
```

A column that contains unsigned 16-bit integers.

## Arguments

* `data`: A list of unsigned 16-bit integer values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.u16([1, 2, 3])
    %Adbc.Column{
      name: nil,
      type: :u16,
      nullable: false,
      metadata: nil,
      data: [1, 2, 3]
    }

# `u32`

```elixir
@spec u32([u32() | nil], Keyword.t()) :: t()
```

A column that contains un32-bit signed integers.

## Arguments

* `data`: A list of un32-bit signed integer values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.u32([1, 2, 3])
    %Adbc.Column{
      name: nil,
      type: :u32,
      nullable: false,
      metadata: nil,
      data: [1, 2, 3]
    }

# `u64`

```elixir
@spec u64([u64() | nil], Keyword.t()) :: t()
```

A column that contains un64-bit signed integers.

## Arguments

* `data`: A list of un64-bit signed integer values
* `opts`: A keyword list of options

## Options

* `:name` - The name of the column
* `:nullable` - A boolean value indicating whether the column is nullable
* `:metadata` - A map of metadata

## Examples

    iex> Adbc.Column.u32([1, 2, 3])
    %Adbc.Column{
      name: nil,
      type: :u32,
      nullable: false,
      metadata: nil,
      data: [1, 2, 3]
    }

---

*Consult [api-reference.md](api-reference.md) for complete listing*