| Entrada | Salida | Alias |
|---|---|---|
| ✔ | ✔ |
Descripción
Native es el formato más eficiente de ClickHouse porque es realmente “columnar”,
ya que no convierte las columnas en filas.
En este formato, los datos se escriben y se leen por bloques en formato binario.
Para cada bloque, se registran uno tras otro el número de filas, el número de columnas, los nombres y tipos de las columnas, y las partes de las columnas del bloque.
Este es el formato que se utiliza en la interfaz nativa para la interacción entre servidores, para usar el cliente de línea de comandos y para los clientes de C++.
Formato wire de los tipos de datos
Al usar el protocolo binario TCP nativo (o cuando el endpoint HTTP recibe
?client_protocol_version=<n>),
se escribe una estructura BlockInfo antes del recuento de columnas y filas. Los ejemplos de esta sección usan
la interfaz HTTP simple, sin versión de protocolo, por lo que se omite BlockInfo.Estructura del bloque
number y str, con tres filas:
Múltiples bloques
Tipos de datos simples
RowBinary/RowBinaryWithNamesAndTypes.
La lista completa de tipos que se ajustan a esta descripción incluye:
- (U)Int8, (U)Int16, (U)Int32, (U)Int64, (U)Int128, (U)Int256
- Float32, Float64
- Bool
- String
- FixedString(N)
- Date
- Date32
- DateTime
- DateTime64
- IPv4
- IPv6
- UUID
Tipos de datos complejos
RowBinary y RowBinaryWithNamesAndTypes.
- Nullable
- LowCardinality
- Array
- Map
- Variant
- Dynamic
- JSON
Nullable
Native, una columna Nullable tendrá un número de bytes igual al número de filas del bloque antes de los datos propiamente dichos. Cada uno de estos bytes indica si el valor es NULL o no. Por ejemplo, con esta consulta, cada número impar será NULL:
Nullable(String). El indicador de nulo siempre proviene del byte de máscara de Nullable:
un valor de máscara de 0x01 significa que la fila es NULL independientemente del contenido de la cadena. En las filas NULL,
la cadena subyacente se almacena como una cadena vacía (longitud LEB128 0). Tenga en cuenta que una cadena vacía no NULL
también tiene una longitud LEB128 de 0, por lo que solo el byte de máscara distingue ambos casos. Por ejemplo, la siguiente consulta:
LowCardinality
LowCardinality es transparente, el formato Native utiliza una codificación columnar basada en diccionario. Una columna se codifica como un prefijo de versión, seguido de un diccionario de valores únicos y un array de índices enteros dentro de ese diccionario.
Una columna puede definirse como
LowCardinality(Nullable(T)), pero no es posible definirla como Nullable(LowCardinality(T)) — siempre dará como resultado un error del servidor.UInt64(LE) con valor 1, escrito una vez por columna. Luego, por bloque, se escribe lo siguiente:
UInt64(LE)— campo de bitsIndexesSerializationType. Los bits 0–7 codifican el ancho del índice (0 = UInt8, 1 = UInt16, 2 = UInt32, 3 = UInt64). El bit 8 (NeedGlobalDictionaryBit) nunca se establece en el formato Native (el servidor genera una excepción si lo encuentra). El bit 9 indica que hay claves de diccionario adicionales presentes. El bit 10 indica que el diccionario debe restablecerse.UInt64(LE)— número de claves del diccionario, seguido de las claves serializadas en bloque mediante la codificación del tipo interno.UInt64(LE)— número de filas, seguido de los valores de índice serializados en bloque usando el ancho de UInt correspondiente.
String, 0 para los tipos numéricos). Para LowCardinality(Nullable(T)), el índice 0 representa NULL, y las claves se serializan sin el contenedor Nullable.
Por ejemplo, LowCardinality(String) con 5 filas ['foo', 'bar', 'baz', 'foo', 'bar']:
LowCardinality(Nullable(String)), el índice 0 es NULL:
Array
- N offsets
UInt64acumulativos (little-endian, 8 bytes cada uno). La filaitieneoffset[i] - offset[i-1]elementos, conoffset[-1]implícitamente igual a 0. - Todos los elementos anidados de todas las filas, serializados en bloque de forma contigua.
Array(UInt32) con 3 filas [[0, 10], [1, 11], [2, 12]]:
Array(String) con 4 filas [[], ['0'], ['0','1'], ['0','1','2']]:
Map
Map(K, V) se codifica como Array(Tuple(K, V)) — offsets del array, seguidos de todas las claves y luego de todos los valores. Esto difiere de RowBinary, donde las claves y los valores se intercalan en cada entrada.
Por ejemplo, Map(String, UInt64) con 3 filas [{'a':0,'b':10}, {'a':1,'b':11}, {'a':2,'b':12}]:
Variant
Variant se codifica de la siguiente manera:
- Prefijo del modo de discriminadores
UInt64(LE)(0= BASIC,1= COMPACT). La salida del formato Native suele usar BASIC (0); el modo COMPACT puede aparecer al leer datos almacenados conuse_compact_variant_discriminators_serializationactivado. - N discriminadores
UInt8, uno por fila. - Los datos de cada tipo de variante como una columna en bloque independiente que contiene solo las filas correspondientes, en orden de discriminante.
Variant(String, UInt32) con 5 filas [0::UInt32, 'hello', NULL, 3::UInt32, 'hello'] (ordenados: String = 0, UInt32 = 1):
Dynamic
Dynamic como un prefijo de estructura seguido de una columna Variant.
El prefijo de estructura contiene una versión de serialización UInt64(LE), luego el número de tipos dinámicos (como VarUInt) y, a continuación, los nombres de los tipos como cadenas. En la versión V1, el recuento de tipos se escribe dos veces por compatibilidad. Los datos que siguen corresponden a una columna Variant cuya lista de tipos incluye los tipos dinámicos más un tipo interno SharedVariant, ordenados alfabéticamente.
Por ejemplo, Dynamic con 5 filas [0::UInt32, 'hello', NULL, 3::UInt32, 'hello']:
JSON
JSON en una estructura columnar. La codificación es compleja y depende de la versión: consta de un prefijo de estructura con la versión de serialización, nombres de rutas dinámicas y la disposición de los datos compartidos, seguido de rutas tipadas (cada una como una columna en bloque), rutas dinámicas (cada una como una columna Dynamic) y datos compartidos para las rutas de desbordamiento.
Para una interoperabilidad más sencilla, considere usar la configuración output_format_native_write_json_as_string=1, que serializa las columnas JSON como cadenas de texto JSON simples (una String por fila).