> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentation for the Vortex format

# Vortex

| Input | Output | Alias |
| ----- | ------ | ----- |
| ✔     | ✔      |       |

<h2 id="description">
  Description
</h2>

[Vortex](https://vortex.dev/) is an extensible columnar file format for compressed Apache Arrow-compatible data,
designed for fast scans and random access. ClickHouse supports reading and writing Vortex files.

<h2 id="data-types-matching-vortex">
  Data types matching
</h2>

The table below shows the Vortex data types and the corresponding ClickHouse [data types](/reference/data-types/index)
in `INSERT` and `SELECT` queries.

| Vortex data type (`INSERT`) | ClickHouse data type                                                                      | Vortex data type (`SELECT`) |
| --------------------------- | ----------------------------------------------------------------------------------------- | --------------------------- |
| `Bool`                      | [Bool](/reference/data-types/boolean)                                                     | `Bool`                      |
| `I8`, `U8`                  | [Int8/UInt8](/reference/data-types/int-uint)                                              | `I8`, `U8`                  |
| `I16`, `U16`                | [Int16/UInt16](/reference/data-types/int-uint)                                            | `I16`, `U16`                |
| `I32`, `U32`                | [Int32/UInt32](/reference/data-types/int-uint)                                            | `I32`, `U32`                |
| `I64`, `U64`                | [Int64/UInt64](/reference/data-types/int-uint)                                            | `I64`, `U64`                |
| `F32`                       | [Float32](/reference/data-types/float)                                                    | `F32`                       |
| `F64`                       | [Float64](/reference/data-types/float)                                                    | `F64`                       |
| `Utf8`, `Binary`            | [String](/reference/data-types/string)                                                    | `Binary`                    |
| `Binary`                    | [FixedString](/reference/data-types/fixedstring)                                          | `Binary`                    |
| `Decimal`                   | [Decimal](/reference/data-types/decimal)                                                  | `Decimal`                   |
| `vortex.date`               | [Date32](/reference/data-types/date32)                                                    | `vortex.date`               |
| `vortex.timestamp`          | [DateTime](/reference/data-types/datetime)/[DateTime64](/reference/data-types/datetime64) | `vortex.timestamp`          |
| `vortex.time`               | [Time64](/reference/data-types/time64)                                                    | `vortex.time`               |
| `List`                      | [Array](/reference/data-types/array)                                                      | `List`                      |
| `Struct`                    | [Tuple](/reference/data-types/tuple)                                                      | `Struct`                    |
| `Null`                      | [Nothing](/reference/data-types/special-data-types/nothing)                               | `Null`                      |

Other types are not supported. In particular, [Map](/reference/data-types/map),
[Int128/UInt128/Int256/UInt256](/reference/data-types/int-uint), [IPv6](/reference/data-types/ipv6)
and [Interval](/reference/data-types/special-data-types/interval) columns cannot be written to Vortex files.
[String](/reference/data-types/string) columns are written as `Binary` because ClickHouse strings are
arbitrary byte sequences, while Vortex requires `Utf8` values to be valid UTF-8. Vortex has no
fixed-size binary type, so [FixedString](/reference/data-types/fixedstring) is also written as `Binary`,
and [LowCardinality](/reference/data-types/lowcardinality) columns are written as their underlying type
(Vortex chooses dictionary and other encodings adaptively by itself).
[DateTime](/reference/data-types/datetime) columns are written as `vortex.timestamp` with second precision,
so they are read back as [DateTime64](/reference/data-types/datetime64) with scale 0.
[IPv4](/reference/data-types/ipv4) columns are written as `U32` because Vortex has no type for IP addresses,
so schema inference reads them back as [UInt32](/reference/data-types/int-uint). Specify the type explicitly
to read such a column back as `IPv4`: `SELECT * FROM file('data.vortex', Vortex, 'ip IPv4')`.

The data types of ClickHouse table columns do not have to match the corresponding Vortex data fields.
When inserting data, ClickHouse interprets data types according to the table above and then
[casts](/reference/functions/regular-functions/type-conversion-functions#CAST) the data to the data type set for the
ClickHouse table column.

<h2 id="example-usage">
  Example usage
</h2>

You can select data from a Vortex file:

```sql theme={null}
SELECT * FROM file('data.vortex', Vortex);
```

And write data to a Vortex file:

```sql theme={null}
SELECT * FROM numbers(3) INTO OUTFILE 'numbers.vortex' FORMAT Vortex;
```

<h2 id="format-settings">
  Format settings
</h2>

The format has no dedicated settings. As in other columnar formats, only the columns used by the
query are read from the file, and columns missing in the file are filled with default values.