Introducido en: v1.1.0Interpreta un número UInt64 como una dirección MAC en orden big-endian.
Devuelve la dirección MAC correspondiente en formato AA:BB:CC:DD:EE:FF (números en hexadecimal separados por dos puntos) como cadena.Sintaxis
Introducido en: v1.1.0Dada una dirección MAC con el formato AA:BB:CC:DD:EE:FF (números hexadecimales separados por dos puntos), devuelve los tres primeros octetos como un número UInt64. Si la dirección MAC tiene un formato no válido, devuelve 0.Sintaxis
Introducido en: v25.11.0Si el usuario de la sesión se ha cambiado con el comando EXECUTE AS, esta función devuelve el nombre del usuario original que se utilizó para autenticarse y crear la sesión.
Alias: authUser()Sintaxis
authenticatedUser()
Alias: authUserArgumentos
Ninguno.
Valor devueltoEl nombre del usuario autenticado. StringEjemplosEjemplo de uso
Query
EXECUTE as u1; SELECT currentUser(), authenticatedUser();
Introducido en: v1.1.0Crea un gráfico de barras.
Dibuja una banda con un ancho proporcional a (x - min) y de width caracteres cuando x = max.
La banda se dibuja con una precisión de un octavo de carácter.Sintaxis
Introducido en: v1.1.0Devuelve un número de secuencia del bloque que contiene la fila y que aumenta de forma monótona.
El número de bloque devuelto se actualiza en la medida de lo posible; es decir, puede no ser totalmente preciso.Sintaxis
blockNumber()
Argumentos
Ninguno.
Valor devueltoNúmero de secuencia del bloque de datos en el que se encuentra la fila. UInt64EjemplosUso básico
Introducido en: v1.1.0En ClickHouse, las consultas se procesan en bloques (fragmentos).
Esta función devuelve el tamaño (número de filas) del bloque sobre el que se invoca.Sintaxis
blockSize()
Argumentos
Ninguno.
Valor devueltoDevuelve el número de filas del bloque actual. UInt64EjemplosEjemplo de uso
Introducido en: v20.5.0Devuelve el ID de compilación generado por un compilador para el binario en ejecución del servidor ClickHouse.
Si se ejecuta en el contexto de una tabla distribuida, esta función genera una columna normal con valores correspondientes a cada segmento.
De lo contrario, produce un valor constante.Sintaxis
buildId()
Argumentos
Ninguno.
Valor devueltoDevuelve el ID de compilación. StringEjemplosEjemplo de uso
Introducido en: v21.1.0Devuelve una estimación del tamaño en bytes sin comprimir de sus argumentos en memoria.
Para argumentos de tipo String, la función devuelve la longitud de la cadena + 8 (longitud).
Si la función tiene varios argumentos, acumula sus tamaños en bytes.Sintaxis
byteSize(arg1[, arg2, ...])
Argumentos
arg1[, arg2, ...] — Valores de cualquier tipo de dato cuyo tamaño en bytes sin comprimir se desea estimar. Any
Valor devueltoDevuelve una estimación del tamaño en bytes de los argumentos en memoria. UInt64EjemplosEjemplo de uso
Introducido en: v22.9.0Evalúa un modelo externo de catboost. CatBoost es una biblioteca de gradient boosting de código abierto desarrollada por Yandex para aprendizaje automático.
Acepta una ruta a un modelo catboost y los argumentos del modelo (features).Requisitos previos
Compilar la biblioteca de evaluación de catboost
Antes de evaluar modelos catboost, la biblioteca libcatboostmodel.<so|dylib> debe estar disponible. Consulta la documentación de CatBoost para ver cómo compilarla.A continuación, especifica la ruta a libcatboostmodel.<so|dylib> en la configuración de ClickHouse:
Por razones de seguridad y aislamiento, la evaluación del modelo no se ejecuta en el proceso del servidor, sino en el proceso clickhouse-library-bridge.
En la primera ejecución de catboostEvaluate(), el servidor inicia el proceso clickhouse-library-bridge si aún no está en ejecución. Ambos procesos
se comunican mediante una interfaz HTTP. De forma predeterminada, se utiliza el puerto 9012. Se puede especificar un puerto diferente de la siguiente manera; esto resulta útil si el puerto
9012 ya está asignado a otro servicio.
Introducido en: v26.2.0Convierte un color del espacio de color perceptivo OKLab al espacio de color sRGB.El color de entrada se especifica en el espacio de color OKLab. Si los valores de entrada quedan fuera
de los rangos típicos de OKLab, el resultado depende de la implementación.OKLab usa tres componentes:
L: luminosidad perceptiva (normalmente en el rango [0..1])
a: eje oponente verde-rojo
b: eje oponente azul-amarillo
Los componentes a y b son teóricamente ilimitados, pero en la práctica se sitúan entre -0.4 y 0.4.
OKLab está diseñado para ser perceptualmente uniforme
sin dejar de ser poco costoso de calcular.La conversión está pensada para ser la inversa de colorSRGBToOKLAB y consta de
las siguientes etapas:
Conversión de OKLab a sRGB lineal.
2) Conversión de sRGB lineal a sRGB codificado con gamma.
El argumento gamma opcional especifica el exponente utilizado al convertir de sRGB lineal
a valores RGB codificados con gamma. Si no se especifica, se usa un valor gamma predeterminado
para mantener la coherencia con colorSRGBToOKLAB.Para obtener más información sobre el espacio de color OKLab y su relación con sRGB, consulte https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/oklab
.Sintaxis
gamma — Opcional. El exponente que se utiliza para transformar sRGB lineal de nuevo a sRGB aplicando (x ^ (1 / gamma)) * 255 a cada canal x. El valor predeterminado es 2.2. Float64
Valor devueltoDevuelve una tupla (R, G, B) que representa valores de color sRGB. Tuple(Float64, Float64, Float64)EjemplosConvertir OKLAB a sRGB (Float)
Query
SELECT colorOKLABToSRGB((0.4466, 0.0991, 0.44)) AS rgb;
Introducido en: v25.7.0Convierte un color del espacio de color perceptualmente uniforme OKLCH al conocido espacio de color sRGB.Si L está fuera del rango [0...1], C es negativo o H está fuera del rango [0...360], el resultado depende de la implementación.
OKLCH es una versión cilíndrica del espacio de color OKLab.
Sus tres coordenadas son L (la luminosidad en el rango [0...1]), C (croma >= 0) y H (tono en grados dentro de [0...360]).
OKLab/OKLCH está diseñado para ser perceptualmente uniforme y seguir siendo barato de calcular.
OKLCH a OKLab.
2) OKLab a sRGB lineal
3) sRGB lineal a sRGB
El segundo argumento, gamma, se utiliza en la última etapa.Para ver referencias de colores en el espacio OKLCH y cómo se corresponden con los colores sRGB, consulta https://oklch.com/.Sintaxis
colorOKLCHToSRGB(tuple [, gamma])
Argumentos
tuple — Una tupla de tres valores numéricos L, C, H, donde L está en el intervalo [0...1], C >= 0 y H está en el intervalo [0...360]. Tuple(Float64, Float64, Float64)
gamma — Opcional. El exponente que se utiliza para convertir sRGB lineal de nuevo a sRGB aplicando (x ^ (1 / gamma)) * 255 a cada canal x. El valor predeterminado es 2.2. Float64
Valor devueltoDevuelve una tupla (R, G, B) que representa los valores de color sRGB. Tuple(Float64, Float64, Float64)EjemplosConvertir OKLCH a sRGB
Introducido en: v26.2.0Convierte un color codificado en el espacio de color sRGB al espacio de color OKLAB, que es perceptualmente uniforme.Si algún canal de entrada está fuera de [0...255] o el valor de gamma no es positivo, el comportamiento depende de la implementación.
OKLAB es un espacio de color perceptualmente uniforme.
Sus tres coordenadas son L (la luminosidad en el intervalo [0...1]), a (eje verde-rojo) y b (eje azul-amarillo).
OKLab está diseñado para ser perceptualmente uniforme y, al mismo tiempo, ser poco costoso de calcular.
gamma — Opcional. Exponente que se usa para linealizar sRGB al aplicar (x / 255)^gamma a cada canal x. El valor predeterminado es 2.2. Float64
Valor devueltoDevuelve una tupla (L, a, b) que representa los valores del espacio de color OKLAB. Tuple(Float64, Float64, Float64)EjemplosConvertir sRGB a OKLAB
Query
SELECT colorSRGBToOKLAB((128, 64, 32), 2.2) AS lab;
Introducido en: v25.7.0Convierte un color codificado en el espacio de color sRGB al espacio de color OKLCH, perceptualmente uniforme.Si algún canal de entrada está fuera de [0...255] o el valor gamma no es positivo, el comportamiento depende de la implementación.
OKLCH es una versión cilíndrica del espacio de color OKLab.
Sus tres coordenadas son L (la luminosidad en el intervalo [0...1]), C (croma >= 0) y H (el tono en grados dentro de [0...360]).
OKLab/OKLCH está diseñado para ser perceptualmente uniforme y, al mismo tiempo, tener un coste de cálculo bajo.
La conversión consta de tres etapas:
sRGB a sRGB lineal
2) sRGB lineal a OKLab
3) OKLab a OKLCH.
Para consultar referencias de colores en el espacio OKLCH y cómo se corresponden con los colores sRGB, consulte https://OKLCH.com/.Sintaxis
gamma — Opcional. Exponente que se usa para linealizar sRGB aplicando (x / 255)^gamma a cada canal x. El valor predeterminado es 2.2. Float64
Valor devueltoDevuelve una tupla (L, C, H) que representa los valores del espacio de color OKLCH. Tuple(Float64, Float64, Float64)EjemplosConvertir sRGB a OKLCH
Query
SELECT colorSRGBToOKLCH((128, 64, 32), 2.2) AS lch;
Introducido en: v21.3.0Devuelve el ID de la conexión del cliente que envió la consulta actual.
Esta función resulta especialmente útil en tareas de depuración.
Se creó para mantener la compatibilidad con la función CONNECTION_ID de MySQL.
No suele utilizarse en consultas de producción.Sintaxis
connectionId()
Argumentos
Ninguno.
Valor devueltoDevuelve el ID de la conexión del cliente actual. UInt64EjemplosEjemplo de uso
Introducido en: v20.8.0Devuelve la cantidad de dígitos decimales necesarios para representar un valor.
Esta función tiene en cuenta las escalas de los valores decimales; es decir, calcula el resultado sobre el tipo entero subyacente, que es (value * scale).Por ejemplo:
countDigits(42) = 2
countDigits(42.000) = 5
countDigits(0.04200) = 4
Puede comprobar el desbordamiento decimal de Decimal64 con countDigits(x) > 18,
aunque es más lento que isDecimalOverflow.
Introducido en: v1.1.0Devuelve el nombre de la base de datos actual.
Es útil en los parámetros del motor de tabla de las sentencias CREATE TABLE en las que necesitas especificar la base de datos.Consulta también la sentencia SET.Sintaxis
Introducido en: v20.1.0Devuelve el nombre del usuario actual.
En el caso de una consulta distribuida, se devuelve el nombre del usuario que inició la consulta.Sintaxis
currentUser()
Alias: current_user, userArgumentos
Ninguno.
Valor devueltoDevuelve el nombre del usuario actual o, si no, el inicio de sesión del usuario que inició la consulta. StringEjemplosEjemplo de uso
Introducido en: v21.9.0Devuelve un array con los nombres de los perfiles de configuración predeterminados del usuario actual.Sintaxis
defaultProfiles()
Argumentos
Ninguno.
Valor devueltoDevuelve un array con los nombres de los perfiles de configuración predeterminados del usuario actual. Array(String)EjemplosEjemplo de uso
Introducido en: v1.1.0Devuelve el valor predeterminado de un tipo de dato determinado.
No incluye los valores predeterminados de las columnas personalizadas definidas por el usuario.Sintaxis
defaultValueOfArgumentType(expression)
Argumentos
expression — Un valor de tipo arbitrario o una expresión cuyo resultado es un valor de tipo arbitrario. Any
Valor devueltoDevuelve 0 para números, una cadena vacía para cadenas o NULL para tipos Nullable. UInt8 o String o NULLEjemplosEjemplo de uso
Query
SELECT defaultValueOfArgumentType(CAST(1 AS Int8));
Introducido en: v1.1.0Devuelve el valor predeterminado del nombre de tipo especificado.Sintaxis
defaultValueOfTypeName(type)
Argumentos
type — Una cadena que representa un nombre de tipo. String
Valor devueltoDevuelve el valor predeterminado para el nombre de tipo especificado: 0 para números, una cadena vacía para cadenas, o NULL para NullableUInt8 o String o NULLEjemplosEjemplo de uso
Introducido en: v22.11.0Devuelve el valor de display_name de configuración o el nombre de dominio completo (FQDN) del servidor si no está configurado.Sintaxis
displayName()
Argumentos
Ninguno.
Valor devueltoDevuelve el valor de display_name de la configuración o el FQDN del servidor si no está definido. StringEjemplosEjemplo de uso
Introducido en: v21.9.0Devuelve un array de nombres de perfiles de configuración habilitados para el usuario actual.Sintaxis
enabledProfiles()
Argumentos
Ninguno.
Valor devueltoDevuelve un array con los nombres de los perfiles de configuración habilitados para el usuario actual. Array(String)EjemplosEjemplo de uso
Introducido en: v20.12.0Devuelve el nombre en texto de un código de error numérico de ClickHouse.
La correspondencia entre los códigos de error numéricos y sus nombres está disponible aquí.Sintaxis
Introducido en: v21.3.0Lee un archivo como una cadena y carga los datos en la columna especificada.
El contenido del archivo no se interpreta.Consulte también la función de tabla file.Sintaxis
file(path[, default])
Argumentos
path — La ruta del archivo relativa a user_files_path. Admite comodines *, **, ?, {abc,def} y {N..M}, donde N y M son números y 'abc' y 'def' son cadenas. String
default — El valor que se devuelve si el archivo no existe o no se puede acceder a él. String o NULL
Valor devueltoDevuelve el contenido del archivo como una cadena. StringEjemplosInsertar archivos en una tabla
Query
INSERT INTO table SELECT file('a.txt'), file('b.txt');
Introducido en: v20.1.0Devuelve la cantidad de espacio libre en el sistema de archivos que aloja la persistencia de la base de datos.
El valor devuelto siempre es inferior al espacio libre total (filesystemUnreserved) porque parte del espacio está reservado para el sistema operativo.Sintaxis
filesystemAvailable([disk_name])
Argumentos
disk_name — Opcional. El nombre del disco del que se quiere obtener la cantidad de espacio libre. Si se omite, se usa el disco predeterminado. String o FixedString
Valor devueltoDevuelve la cantidad de espacio libre restante en bytes. UInt64EjemplosEjemplo de uso
Query
SELECT formatReadableSize(filesystemAvailable()) AS "Available space";
Introducido en: v22.12.0Devuelve la cantidad total de espacio libre en el sistema de archivos que hospeda la persistencia de la base de datos (anteriormente filesystemFree).
Véase también filesystemAvailable.Sintaxis
filesystemUnreserved([disk_name])
Argumentos
disk_name — Opcional. El nombre del disco cuyo espacio libre total se debe obtener. Si se omite, se usa el disco predeterminado. String o FixedString
Valor devueltoDevuelve la cantidad de espacio libre en bytes. UInt64EjemplosEjemplo de uso
Query
SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";
Introducido en: v1.1.0Dado un estado de agregación, esta función devuelve el resultado de la agregación (o el estado final cuando se utiliza un combinador -State).Sintaxis
WITH initializeAggregation('sumState', number) AS one_row_sum_stateSELECT number, finalizeAggregation(one_row_sum_state) AS one_row_sum, runningAccumulate(one_row_sum_state) AS cumulative_sumFROM numbers(5);
Introducido en: v25.11.0Invierte las coordenadas x e y de los objetos geométricos. Esta operación intercambia la latitud y la longitud, lo que resulta útil para convertir entre distintos sistemas de coordenadas o corregir el orden de las coordenadas.En un Point, intercambia las coordenadas x e y. En las geometrías complejas (LineString, Polygon, MultiPolygon, Ring, MultiLineString), aplica la transformación de forma recursiva a cada par de coordenadas.La función admite tanto tipos de geometría individuales (Point, Ring, Polygon, MultiPolygon, LineString, MultiLineString) como el tipo variante Geometry.Sintaxis
flipCoordinates(geometry)
Argumentos
geometry — La geometría que se va a transformar. Tipos admitidos: Point (Tuple(Float64, Float64)), Ring (Array(Point)), Polygon (Array(Ring)), MultiPolygon (Array(Polygon)), LineString (Array(Point)), MultiLineString (Array(LineString)) o Geometry (una variante que contiene cualquiera de estos tipos).
Introducido en: v23.10.0Devuelve una versión con formato, posiblemente de varias líneas, de la consulta SQL dada. Genera una excepción en caso de error de análisis sintáctico.
[example:multiline]Sintaxis
formatQuery(query)
Argumentos
query — La consulta SQL que se va a formatear. String
Valor devueltoLa consulta formateada StringEjemplosmultiline
Query
SELECT formatQuery('select a, b FRom tab WHERE a > 3 and b < 3');
Introducido en: v23.11.0Devuelve una versión formateada, posiblemente de varias líneas, de la consulta SQL proporcionada. Devuelve NULL en caso de error de análisis sintáctico.
[example:multiline]Sintaxis
formatQueryOrNull(query)
Argumentos
query — La consulta SQL que se va a formatear. String
Valor devueltoLa consulta formateada StringEjemplosmultilínea
Query
SELECT formatQuery('select a, b FRom tab WHERE a > 3 and b < 3');
Introducido en: v23.10.0Como formatQuery(), pero la cadena formateada que se devuelve no contiene saltos de línea. Genera una excepción en caso de error de análisis sintáctico.
[example:multiline]Sintaxis
formatQuerySingleLine(query)
Argumentos
query — La consulta SQL que se va a formatear. String
Valor devueltoLa consulta formateada StringEjemplosmultiline
Query
SELECT formatQuerySingleLine('select a, b FRom tab WHERE a > 3 and b < 3');
Introducido en: v23.11.0Como formatQuery(), pero la cadena formateada devuelta no contiene saltos de línea. Devuelve NULL en caso de error de análisis sintáctico.
[example:multiline]Sintaxis
formatQuerySingleLineOrNull(query)
Argumentos
query — La consulta SQL que se va a dar formato. String
Valor devueltoLa consulta formateada StringEjemplosmultilínea
Query
SELECT formatQuerySingleLine('select a, b FRom tab WHERE a > 3 and b < 3');
Introducido en: v22.11.0Dado un tamaño (número de bytes), esta función devuelve un tamaño legible y redondeado con sufijo (KB, MB, etc.) en forma de cadena.La operación inversa de esta función es parseReadableSize.Sintaxis
Introducido en: v20.10.0Dado un número, esta función devuelve una cadena con el número redondeado y un sufijo (mil, millón, mil millones, etc.).Esta función acepta cualquier tipo numérico como entrada, pero internamente lo convierte a Float64.
Los resultados pueden no ser óptimos con valores grandes.Sintaxis
Introducido en: v1.1.0Dado un tamaño (número de bytes), esta función devuelve un tamaño legible y redondeado con sufijo (KiB, MiB, etc.) en forma de cadena.Las operaciones opuestas de esta función son parseReadableSize, parseReadableSizeOrZero y parseReadableSizeOrNull.
Esta función acepta cualquier tipo numérico como entrada, pero internamente lo convierte a Float64. Los resultados pueden no ser óptimos con valores grandes.Sintaxis
Introducido en: v20.12.0Dado un intervalo de tiempo (delta) en segundos, esta función devuelve dicho delta como una cadena con años/meses/días/horas/minutos/segundos/milisegundos/microsegundos/nanosegundos.Esta función acepta cualquier tipo numérico como entrada, pero internamente lo convierte a Float64. Los resultados pueden no ser óptimos con valores grandes.Sintaxis
column — Una columna con una diferencia de tiempo numérica. Float64
maximum_unit — Opcional. La unidad máxima que se mostrará. Valores aceptables: nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, months, years. Valor predeterminado: years. const String
minimum_unit — Opcional. La unidad mínima que se mostrará. Todas las unidades más pequeñas se truncan. Valores aceptables: nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, months, years. Si el valor especificado explícitamente es mayor que maximum_unit, se lanzará una excepción. Valor predeterminado: seconds si maximum_unit es seconds o una unidad mayor; nanoseconds en caso contrario. const String
Valor devueltoDevuelve una diferencia de tiempo en forma de cadena. StringEjemplosEjemplo de uso
Query
SELECT arrayJoin([100, 12345, 432546534]) AS elapsed, formatReadableTimeDelta(elapsed) AS time_delta
Response
┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐│ 100 │ 1 minute and 40 seconds ││ 12345 │ 3 hours, 25 minutes and 45 seconds ││ 432546534 │ 13 years, 8 months, 17 days, 7 hours, 48 minutes and 54 seconds│└────────────┴────────────────────────────────────────────────────────────────┘
Con la unidad máxima
Query
SELECT arrayJoin([100, 12345, 432546534]) AS elapsed, formatReadableTimeDelta(elapsed, 'minutes') AS time_delta
Response
┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐│ 100 │ 1 minute and 40 seconds ││ 12345 │ 205 minutes and 45 seconds ││ 432546534 │ 7209108 minutes and 54 seconds │└────────────┴─────────────────────────────────────────────────────────────────┘
Introducido en: v26.2.0Analiza la cadena de consulta proporcionada y le aplica mutaciones aleatorias del AST (fuzzing). Devuelve la consulta modificada mediante fuzzing como una cadena. No determinista: cada llamada puede producir un resultado diferente. Requiere allow_fuzz_query_functions = 1.Sintaxis
fuzzQuery(query)
Argumentos
query — La consulta SQL a la que se aplicará fuzzing. String
Valor devueltoLa cadena de consulta resultante del fuzzing StringEjemplosbásico
Query
SET allow_fuzz_query_functions = 1; SELECT fuzzQuery('SELECT 1');
number_of_columns — El número deseado de columnas en la estructura de la tabla resultante. Si se establece en 0 o Null, el número de columnas será aleatorio, entre 1 y 128. Valor predeterminado: Null. UInt64
seed — Semilla aleatoria para producir resultados estables. Si no se especifica o se establece en Null, se genera aleatoriamente. UInt64
Valor devueltoEstructura de tabla generada aleatoriamente. StringEjemplosEjemplo de uso
Introducido en: v25.1.0Genera y devuelve números secuenciales a partir del valor anterior del contador.
Esta función acepta un argumento de cadena: un identificador de serie, y un valor inicial opcional.
El servidor debe estar configurado con Keeper.
Las series se almacenan en nodos de Keeper en la ruta, que puede configurarse en series_keeper_path en la configuración del servidor.Sintaxis
series_identifier — Identificador de la serie const String
start_value — Opcional. Valor inicial del contador. El valor predeterminado es 0. Nota: este valor solo se usa al crear una serie nueva y se ignora si la serie ya existe UInt*
Valor devueltoDevuelve números consecutivos a partir del valor anterior del contador. UInt64Ejemplosprimera llamada
Introducido en: v24.5.0Obtiene el valor de una cabecera HTTP.
Si no existe esa cabecera o la solicitud actual no se realiza a través de la interfaz HTTP, la función devuelve una cadena vacía.
Algunas cabeceras HTTP (por ejemplo, Authentication y X-ClickHouse-*) están restringidas.
Se requiere la configuración allow_get_client_http_headerLa función requiere que la configuración allow_get_client_http_header esté habilitada.
Esta configuración no está habilitada de forma predeterminada por motivos de seguridad, ya que algunas cabeceras, como Cookie, podrían contener información confidencial.
Para esta función, las cabeceras HTTP distinguen entre mayúsculas y minúsculas.
Si la función se usa en el contexto de una consulta distribuida, solo devuelve un resultado no vacío en el nodo iniciador.Sintaxis
Introducido en: v20.1.0Devuelve el valor de una macro del archivo de configuración del servidor.
Las macros se definen en la sección <macros> del archivo de configuración y pueden utilizarse para distinguir servidores mediante nombres fáciles de identificar, incluso si tienen nombres de host complejos.
Si la función se ejecuta en el contexto de una tabla distribuida, genera una columna normal con valores correspondientes a cada segmento.Sintaxis
getMacro(name)
Argumentos
name — El nombre de la macro que se va a obtener. const String
Valor devueltoDevuelve el valor de la macro especificada. StringEjemplosUso básico
Introducido en: v24.10.0Devuelve el valor actual de un SETTING, o el valor predeterminado especificado en el segundo argumento si el SETTING no está definido en el perfil actual.Sintaxis
Introducido en: v23.3.0Recibe una expresión o un identificador, y una cadena constante con el nombre de la subcolumna.Devuelve la subcolumna solicitada extraída de la expresión.Sintaxis
Introducido en: v22.6.0Enumera las rutas de los streams de serialización de un tipo de dato.
Esta función está pensada para fines de desarrollo.Sintaxis
getTypeSerializationStreams(col)
Argumentos
col — Columna o representación en cadena de un tipo de dato a partir de la cual se detectará el tipo de dato. Any
Valor devueltoDevuelve un array con todas las rutas de los subflujos de serialización. Array(String)Ejemplostupla
Introducido en: v20.5.0Toma un argumento de tipo cadena constante y devuelve el valor de la variable global con ese nombre. Esta función está pensada para mantener la compatibilidad con MySQL y no es necesaria ni útil para el funcionamiento normal de ClickHouse. Solo hay definidas unas pocas variables globales ficticias.Sintaxis
Introducido en: v1.1.0Comprueba si una columna específica existe en una tabla de una base de datos.
En el caso de los elementos de una estructura de datos anidada, la función comprueba si existe una columna.
En el caso de la propia estructura de datos anidada, la función devuelve 0.Sintaxis
Introducido en: v26.5.0Analiza una cadena con una consulta de ClickHouse SQL y devuelve un array de rangos destacados para el resaltado de sintaxis.
Cada rango es una tupla con nombre con la posición inicial (en bytes), la posición final y el tipo de resaltado.
Los tipos de resaltado describen el papel sintáctico del fragmento (palabra clave, identificador, función, etc.)
y pueden usarse para asignar colores en una UI. Dentro de los patrones de cadena de LIKE y REGEXP, los metacaracteres
y los caracteres de escape se resaltan por separado.Sintaxis
highlightQuery(query)
Argumentos
query — Una cadena de consulta de ClickHouse SQL. String.
Introducido en: v20.5.0Devuelve el nombre del host en el que se ejecutó esta función.
Si la función se ejecuta en un servidor remoto (procesamiento distribuido), se devuelve el nombre de ese servidor.
Si la función se ejecuta en el contexto de una tabla distribuida, genera una columna normal con valores correspondientes a cada segmento.
De lo contrario, produce un valor constante.Sintaxis
hostName()
Alias: hostnameArgumentos
Ninguno.
Valor devueltoDevuelve el nombre del host. StringEjemplosEjemplo de uso
Introducido en: v1.1.0Esta función devuelve el argumento que se le pasa, lo que resulta útil para la depuración y las pruebas. Permite omitir el uso de índices para ver, en su lugar, el rendimiento de un escaneo completo. El analizador de consultas ignora todo lo que haya dentro de las funciones identity al buscar índices que usar, y también desactiva el plegado de constantes.Sintaxis
Introducido en: v1.1.0Esta función está pensada para depuración e introspección.
Ignora su argumento y siempre devuelve 1.
Los argumentos no se evalúan.Durante el análisis del índice, se asume que el argumento de esta función no está envuelto en indexHint.
Esto le permite seleccionar datos en rangos del índice mediante la condición correspondiente, pero sin aplicar después un filtrado por esa condición.
El índice de ClickHouse es disperso, y usar indexHint devolverá más datos que especificar directamente la misma condición.
Explicación
Cuando ejecuta:
SELECT * FROM test WHERE key = 123;
ClickHouse hace dos cosas:
Usa el índice para encontrar qué gránulos (bloques de ~8192 filas) podrían contener key = 123
Lee esos gránulos y los filtra fila por fila para devolver solo las filas donde key = 123
Así que, aunque lea 8192 filas del disco, solo devuelve la única fila que realmente coincide.Con indexHint, cuando ejecuta:
SELECT * FROM test WHERE indexHint(key = 123);
ClickHouse hace solo una cosa:
Usa el índice para encontrar qué gránulos podrían contener key = 123 y devuelve todas las filas de esos gránulos sin filtrarlas.
Devuelve las 8192 filas, incluidas las filas donde key = 456, key = 789, etc. (Todo lo que haya quedado almacenado en el mismo gránulo).
indexHint() no sirve para mejorar el rendimiento. Sirve para depurar y entender cómo funciona el índice de ClickHouse:
¿Qué gránulos selecciona mi condición?
¿Cuántas filas hay en esos gránulos?
¿Se está usando mi índice de forma eficaz?
Nota: No es posible optimizar una consulta con la función indexHint. La función indexHint no optimiza la consulta, ya que no proporciona ninguna información adicional para el análisis de la consulta. Tener una expresión dentro de la función indexHint no es en modo alguno mejor que no usar la función indexHint. La función indexHint solo puede usarse con fines de introspección y depuración, y no mejora el rendimiento. Si ve que alguien que no sea colaborador de ClickHouse usa indexHint, probablemente sea un error y debería eliminarlo.Sintaxis
indexHint(expression)
Argumentos
expression — Cualquier expresión para la selección del rango del índice. Expression
Valor devueltoDevuelve 1 en todos los casos. UInt8EjemplosEjemplo de uso con filtro por fecha
Query
SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;
Introducido en: v1.1.0Devuelve el ID de la consulta inicial de la consulta actual.
Otros parámetros de una consulta pueden extraerse del campo initial_query_id en system.query_log.A diferencia de la función queryID, initialQueryID devuelve los mismos resultados en diferentes segmentos.Sintaxis
initialQueryID()
Aliases: initial_query_idArgumentos
Ninguno.
Valor devueltoDevuelve el ID de la consulta inicial asociada a la consulta actual. StringEjemplosEjemplo de uso
Query
CREATE TABLE tmp (str String) ENGINE = Log;INSERT INTO tmp (*) VALUES ('a');SELECT count(DISTINCT t) FROM (SELECT initialQueryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
Introducido en: v25.4.0Devuelve la hora de inicio de la consulta actual original.
initialQueryStartTime devuelve los mismos resultados en diferentes segmentos.Sintaxis
initialQueryStartTime()
Alias: initial_query_start_timeArgumentos
Ninguno.
Valor devueltoDevuelve la hora de inicio de la consulta inicial de la consulta actual. DateTimeEjemplosEjemplo de uso
Query
CREATE TABLE tmp (str String) ENGINE = Log;INSERT INTO tmp (*) VALUES ('a');SELECT count(DISTINCT t) FROM (SELECT initialQueryStartTime() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
Introducido en: v20.6.0Calcula el resultado de una función de agregación a partir de un único valor.
Esta función puede utilizarse para inicializar funciones de agregación con el combinador -State.
Puede crear estados de funciones de agregación e insertarlos en columnas de tipo AggregateFunction, o usar agregados inicializados como valores por defecto.Sintaxis
aggregate_function — Nombre de la función de agregación que se va a inicializar. String
arg1[, arg2, ...] — Argumentos de la función de agregación. Any
Valor devueltoDevuelve el resultado de la agregación para cada fila que se pasa a la función. El tipo de retorno es el mismo que el de la función que initializeAggregation recibe como primer argumento. AnyEjemplosUso básico con uniqState
Query
SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));
Response
┌─uniqMerge(state)─┐│ 3 │└──────────────────┘
Uso de sumState y finalizeAggregation
Query
SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));
Introducido en: v20.3.0Indica si el argumento es una expresión constante.
Una expresión constante es una expresión cuyo resultado se conoce durante el análisis de la consulta, es decir, antes de la ejecución.
Por ejemplo, las expresiones sobre literales son expresiones constantes.
Esta función está pensada principalmente para desarrollo, depuración y demostración.Sintaxis
Introducido en: v20.8.0Comprueba si un número decimal tiene demasiados dígitos para caber correctamente en un tipo de dato Decimal con la precisión indicada.Sintaxis
isDecimalOverflow(value[, precision])
Argumentos
value — Valor Decimal que se va a comprobar. Decimal
precision — Opcional. La precisión del tipo Decimal. Si se omite, se usa la precisión inicial del primer argumento. UInt8
Valor devueltoDevuelve 1 si el valor decimal tiene más dígitos de los permitidos por su precisión, y 0 si el valor decimal cumple la precisión especificada. UInt8EjemplosEjemplo de uso
Introducido en: v18.16.0Permite extraer datos de una tabla de la misma manera que de un diccionario.
Obtiene datos de tablas Join usando la clave de join especificada.
Solo admite tablas creadas con la instrucción ENGINE = Join(ANY, LEFT, <join_keys>)sentencia.
join_storage_table_name — Un identificador que indica dónde realizar la búsqueda. El identificador se busca en la base de datos predeterminada (consulte el parámetro default_database en el archivo de configuración). Para anular la base de datos predeterminada, use la consulta USE database_name o especifique la base de datos y la tabla mediante un punto, como database_name.table_name. String
value_column — El nombre de la columna de la tabla que contiene los datos necesarios. const String
Introducido en: v20.4.0Permite extraer datos de una tabla de la misma forma que de un diccionario.
Obtiene datos de tablas Join mediante la clave de join especificada.
A diferencia de joinGet, devuelve NULL cuando la clave no existe.
Solo admite tablas creadas con la ENGINE = Join(ANY, LEFT, <join_keys>)sentencia.
join_storage_table_name — Un identificador que indica dónde realizar la búsqueda. El identificador se busca en la base de datos predeterminada (consulte el parámetro default_database en el archivo de configuración). Para usar otra base de datos distinta de la predeterminada, utilice la consulta USE database_name o especifique la base de datos y la tabla separadas por un punto, como en database_name.table_name. String
value_column — El nombre de la columna de la tabla que contiene los datos necesarios. const String
Introducido en: v18.12.0Devuelve la posición de un valor en el diccionario de una columna LowCardinality. Las posiciones empiezan en 1. Como LowCardinality tiene diccionarios por cada parte, esta función puede devolver posiciones distintas para el mismo valor en diferentes partes.Sintaxis
Valor devueltoLa posición del valor en el diccionario de la parte actual. UInt64EjemplosEjemplos de uso
Query
DROP TABLE IF EXISTS test;CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;-- crear dos partes:INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');SELECT s, lowCardinalityIndices(s) FROM test;
Response
┌─s──┬─lowCardinalityIndices(s)─┐│ ab │ 1 ││ cd │ 2 ││ ab │ 1 ││ ab │ 1 ││ df │ 3 │└────┴──────────────────────────┘┌─s──┬─lowCardinalityIndices(s)─┐│ ef │ 1 ││ cd │ 2 ││ ab │ 3 ││ cd │ 2 ││ ef │ 1 │└────┴──────────────────────────┘
Introducido en: v18.12.0Devuelve los valores del diccionario de una columna LowCardinality.
Si el bloque es más pequeño o más grande que el tamaño del diccionario, el resultado se truncará o se completará con valores predeterminados.
Dado que LowCardinality tiene diccionarios por parte, esta función puede devolver valores de diccionario diferentes en distintas partes.Sintaxis
Valor devueltoDevuelve las claves del diccionario. UInt64EjemploslowCardinalityKeys
Query
DROP TABLE IF EXISTS test;CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;-- crear dos partes:INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');SELECT s, lowCardinalityKeys(s) FROM test;
Response
┌─s──┬─lowCardinalityKeys(s)─┐│ ef │ ││ cd │ ef ││ ab │ cd ││ cd │ ab ││ ef │ │└────┴───────────────────────┘┌─s──┬─lowCardinalityKeys(s)─┐│ ab │ ││ cd │ ab ││ ab │ cd ││ ab │ df ││ df │ │└────┴───────────────────────┘
Introducido en: v1.1.0Convierte una constante en una columna completa que contiene un solo valor.
Las columnas completas y las constantes se representan de forma diferente en memoria.
Las funciones suelen ejecutar código diferente para los argumentos normales y los constantes, aunque por lo general el resultado debería ser el mismo.
Esta función puede utilizarse para depurar este comportamiento.Sintaxis
Valor devueltoDevuelve una columna completa con el valor constante. AnyEjemplosEjemplo de uso
Query
-- En el ejemplo siguiente, la función `countMatches` espera un segundo argumento constante.-- Este comportamiento puede depurarse usando la función `materialize` para convertir una constante en una columna completa,-- verificando que la función arroja un error para un argumento no constante.SELECT countMatches('foobarfoo', 'foo');SELECT countMatches('foobarfoo', materialize('foo'));
Response
2Code: 44. DB::Exception: Received from localhost:9000. DB::Exception: Illegal type of argument #2 'pattern' of function countMatches, expected constant String, got String
Introducido en: v23.10.0Calcula el tamaño mínimo de muestra necesario para una prueba A/B que compara las medias de una métrica continua en dos muestras.Usa la fórmula descrita en este artículo.
Asume tamaños iguales para los grupos de tratamiento y de control.
Devuelve el tamaño de muestra necesario para un grupo (es decir, el tamaño de muestra necesario para todo el experimento es el doble del valor devuelto).
También asume una varianza igual de la métrica evaluada en los grupos de tratamiento y de control.Sintaxis
baseline — Valor de referencia de una métrica. (U)Int* o Float*
sigma — Desviación estándar de referencia de una métrica. (U)Int* o Float*
mde — Efecto mínimo detectable (MDE) como porcentaje del valor de referencia (p. ej., para un valor de referencia de 112.25, un MDE de 0.03 significa un cambio esperado a 112.25 ± 112.25*0.03). (U)Int* o Float*
power — Potencia estadística requerida de una prueba (1 - probabilidad de error de tipo II). (U)Int* o Float*
alpha — Nivel de significación requerido de una prueba (probabilidad de error de tipo I). (U)Int* o Float*
Valor devueltoDevuelve un Tuple con nombre con 3 elementos: minimum_sample_size, detect_range_lower y detect_range_upper. Estos corresponden, respectivamente, al tamaño de muestra requerido, al límite inferior del rango de valores no detectables con el tamaño de muestra requerido devuelto, calculado como baseline * (1 - mde), y al límite superior del rango de valores no detectables con el tamaño de muestra requerido devuelto, calculado como baseline * (1 + mde) (Float64). Tuple(Float64, Float64, Float64)EjemplosminSampleSizeContinuous
Query
SELECT minSampleSizeContinuous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size
Introducido en: v22.6.0Calcula el tamaño mínimo de muestra necesario para una prueba A/B que compara conversiones (proporciones) en dos muestras.Utiliza la fórmula descrita en este artículo. Asume tamaños iguales para los grupos de tratamiento y de control. Devuelve el tamaño de muestra necesario para un grupo (es decir, el tamaño de muestra necesario para todo el experimento es el doble del valor devuelto).Sintaxis
baseline — Tasa de conversión de referencia. Float*
mde — Efecto mínimo detectable (MDE), en puntos porcentuales (p. ej., para una tasa de conversión de referencia de 0.25, un MDE de 0.03 significa un cambio esperado a 0.25 ± 0.03). Float*
power — Potencia estadística requerida de una prueba (1 - probabilidad de error de tipo II). Float*
alpha — Nivel de significación requerido de una prueba (probabilidad de error de tipo I). Float*
Valor devueltoDevuelve un Tuple con nombre con 3 elementos: minimum_sample_size, detect_range_lower, detect_range_upper. Estos son, respectivamente: el tamaño de muestra requerido, el límite inferior del intervalo de valores no detectables con el tamaño de muestra requerido devuelto, calculado como baseline - mde, y el límite superior del intervalo de valores no detectables con el tamaño de muestra requerido devuelto, calculado como baseline + mde. Tuple(Float64, Float64, Float64)EjemplosminSampleSizeConversion
Query
SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size
Introducido en: v20.1.0Devuelve un valor de una columna con un desplazamiento especificado respecto de la fila actual.
Esta función está obsoleta y es propensa a errores porque opera sobre el orden físico de los bloques de datos, que puede no corresponderse con el orden lógico que esperan los usuarios.
Considere usar funciones de ventana adecuadas en su lugar.La función puede habilitarse estableciendo allow_deprecated_error_prone_window_functions = 1.Sintaxis
offset — El desplazamiento con respecto a la fila actual. Los valores positivos avanzan y los valores negativos retroceden. Integer
default_value — Opcional. El valor que se devuelve si el desplazamiento queda fuera de los límites de los datos. Si no se especifica, se usa el valor predeterminado del tipo de columna. Any
Valor devueltoDevuelve un valor en el desplazamiento especificado o el valor predeterminado si queda fuera de los límites. AnyEjemplosEjemplo de uso
Query
SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;
Introducido en: v20.8.0Sustituye los literales, las secuencias de literales y los alias complejos (que contienen espacios en blanco, más de dos dígitos o tienen una longitud de al menos 36 bytes, como los UUID) por el marcador de posición ?.Sintaxis
Introducido en: v21.2.0Reemplaza los literales y las secuencias de literales por el marcador de posición ?, pero no reemplaza los alias complejos (que contienen espacios en blanco, más de dos dígitos o tienen una longitud de al menos 36 bytes, como los UUID).
Esto ayuda a analizar mejor los logs de consultas complejas.Sintaxis
Valor devueltoDevuelve la secuencia de caracteres proporcionada con marcadores de posición. StringEjemplosEjemplo de uso
Query
SELECT normalizeQuery('SELECT 1 AS aComplexName123'), normalizeQueryKeepNames('SELECT 1 AS aComplexName123')
Response
┌─normalizeQuery('SELECT 1 AS aComplexName123')─┬─normalizeQueryKeepNames('SELECT 1 AS aComplexName123')─┐│ SELECT ? AS `?` │ SELECT ? AS aComplexName123 │└───────────────────────────────────────────────┴────────────────────────────────────────────────────────┘
Introducido en: v20.8.0Devuelve valores hash idénticos de 64 bits para consultas similares, sin tener en cuenta los valores de los literales.
Puede ser útil para analizar los logs de consultas.Sintaxis
Introducido en la versión v21.2.0Al igual que normalizedQueryHash, devuelve valores hash idénticos de 64 bits para consultas similares sin incluir los valores de los literales, pero no reemplaza los alias complejos (que contienen espacios en blanco, más de dos dígitos o tienen una longitud mínima de 36 bytes, como los UUID) por un marcador de posición antes de calcular el hash.
Puede ser útil para analizar el log de consulta.Sintaxis
Valor devueltoDevuelve un valor hash de 64 bits. UInt64EjemplosEjemplo de uso
Query
SELECT normalizedQueryHash('SELECT 1 AS `xyz123`') != normalizedQueryHash('SELECT 1 AS `abc123`') AS normalizedQueryHash;SELECT normalizedQueryHashKeepNames('SELECT 1 AS `xyz123`') != normalizedQueryHashKeepNames('SELECT 1 AS `abc123`') AS normalizedQueryHashKeepNames;
Introducido en: v26.4.0Ofusca una consulta SQL sustituyendo los identificadores por palabras aleatorias y los literales por valores aleatorios, a la vez que conserva la estructura de la consulta.Esta función es útil para anonimizar consultas antes de registrarlas o compartirlas con fines de depuración.
Distintas filas producirán resultados ofuscados diferentes incluso para la misma consulta de entrada, lo que ayuda
a mantener la privacidad al trabajar con múltiples consultas.El parámetro opcional tag evita la eliminación de subexpresiones comunes cuando la misma llamada a la función
se usa varias veces en una consulta. Esto garantiza que cada invocación produzca un resultado ofuscado diferente.Características:
Sustituye los nombres de tabla, los nombres de columna y los alias por palabras aleatorias
Sustituye los literales numéricos y de texto por valores aleatorios
Conserva la estructura general de la consulta y la sintaxis SQL
Produce resultados diferentes para distintas filas
Sintaxis
obfuscateQuery(query[, tag])
Argumentos
query — La consulta SQL que se va a ofuscar. String
tag — Opcional. Un valor para evitar la eliminación de subexpresiones comunes cuando la misma llamada a función se utiliza varias veces.
Valor devueltoLa consulta ofuscada, con los identificadores y literales reemplazados, conservando la estructura original de la consulta. StringEjemplosUso básico
Query
SELECT obfuscateQuery('SELECT name, age FROM users WHERE age > 30')
Response
SELECT fruit, number FROM table WHERE number > 12
Con una etiqueta para evitar la eliminación de subexpresiones comunes
Query
SELECT obfuscateQuery('SELECT * FROM t', 1), obfuscateQuery('SELECT * FROM t', 2)
Response
SELECT a FROM b, SELECT c FROM d
Filas distintas producen resultados diferentes
Query
SELECT obfuscateQuery('SELECT 1') AS a, obfuscateQuery('SELECT 1') AS b
Introducido en: v26.4.0Ofusca una consulta SQL usando una semilla específica para obtener resultados deterministas.A diferencia de obfuscateQuery(), esta función produce resultados deterministas cuando se le proporciona la misma semilla.
Esto resulta útil cuando necesitas una ofuscación coherente en varias ejecuciones o cuando quieres
reproducir la misma consulta ofuscada para fines de prueba o depuración.Características:
Ofuscación determinista basada en la semilla proporcionada
La misma semilla siempre produce el mismo resultado ofuscado
Semillas diferentes producen resultados diferentes
Conserva la estructura de la consulta, igual que obfuscateQuery()
Casos de uso:
Casos de prueba reproducibles
Anonimización coherente en varias ejecuciones
Depuración con consultas ofuscadas coherentes
Sintaxis
obfuscateQueryWithSeed(query, seed)
Argumentos
query — La consulta SQL que se va a ofuscar. String
seed — La semilla de la ofuscación. La misma semilla produce resultados deterministas. Integer o String
Valor devueltoLa consulta ofuscada, generada de forma determinista a partir de la semilla proporcionada. StringEjemplosOfuscación determinista con una semilla entera
Query
SELECT obfuscateQueryWithSeed('SELECT name FROM users', 42)
Response
SELECT fruit FROM table
Ofuscación determinista con una semilla de texto
Query
SELECT obfuscateQueryWithSeed('SELECT id, value FROM data', 'myseed')
Introducido en: v24.6.0Dada una cadena que contiene un tamaño en bytes y B, KiB, KB, MiB, MB, etc. como unidad (es decir, ISO/IEC 80000-13 o una unidad decimal de bytes), esta función devuelve el número de bytes correspondiente.
Si la función no puede interpretar el valor de entrada, lanza una excepción.Las operaciones inversas de esta función son formatReadableSize y formatReadableDecimalSize.Sintaxis
parseReadableSize(x)
Argumentos
x — Tamaño legible con una unidad de bytes ISO/IEC 80000-13 o decimal. String
Valor devueltoDevuelve el número de bytes, redondeado hacia arriba al entero más cercano. UInt64EjemplosEjemplo de uso
Query
SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes, parseReadableSize(readable_sizes) AS sizes;
Introducido en: v24.6.0Dada una cadena que contiene un tamaño de bytes y B, KiB, KB, MiB, MB, etc. como unidad (es decir, ISO/IEC 80000-13 o una unidad decimal de bytes), esta función devuelve el número de bytes correspondiente.
Si la función no puede interpretar el valor de entrada, devuelve NULL.Las operaciones inversas de esta función son formatReadableSize y formatReadableDecimalSize.Sintaxis
parseReadableSizeOrNull(x)
Argumentos
x — Tamaño en formato legible con una unidad de bytes ISO/IEC 80000-13 o decimal. String
Valor devueltoDevuelve el número de bytes, redondeado hacia arriba al entero más cercano, o NULL si no se puede interpretar la entrada Nullable(UInt64)EjemplosEjemplo de uso
Query
SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrNull(readable_sizes) AS sizes;
Introducido en: v24.6.0Dada una cadena que contiene un tamaño en bytes y B, KiB, KB, MiB, MB, etc. como unidad (es decir, ISO/IEC 80000-13 o una unidad decimal de bytes), esta función devuelve el número de bytes correspondiente.
Si la función no puede interpretar el valor de entrada, devuelve 0.Las operaciones inversas de esta función son formatReadableSize y formatReadableDecimalSize.Sintaxis
parseReadableSizeOrZero(x)
Argumentos
x — Tamaño legible con una unidad de bytes según ISO/IEC 80000-13 o decimal. String
Valor devueltoDevuelve el número de bytes, redondeado hacia arriba al entero más cercano, o 0 si no es posible analizar la entrada. UInt64EjemplosEjemplo de uso
Query
SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrZero(readable_sizes) AS sizes;
Introducido en: v22.7.0Analiza una secuencia de números seguida de algo que se asemeja a una unidad de tiempo.La cadena de intervalo de tiempo usa estas especificaciones de unidades de tiempo:
years, year, yr, y
months, month, mo
weeks, week, w
days, day, d
hours, hour, hr, h
minutes, minute, min, m
seconds, second, sec, s
milliseconds, millisecond, millisec, ms
microseconds, microsecond, microsec, μs, µs, us
nanoseconds, nanosecond, nanosec, ns
Se pueden combinar varias unidades de tiempo con separadores (espacio, ;, -, +, ,, :).La duración de los años y los meses es aproximada: un año equivale a 365 días y un mes a 30.5 días.Sintaxis
parseTimeDelta(timestr)
Argumentos
timestr — Una secuencia de números seguida de algo parecido a una unidad de tiempo. String
Valor devueltoEl número de segundos. Float64EjemplosEjemplo de uso
Esta función es lenta y no debe utilizarse con grandes cantidades de filas.
Sintaxis
partitionId(column1[, column2, ...])
Alias: partitionIDArgumentos
column1, column2, ... — Columna cuyo ID de partición se devuelve.
Valor devueltoDevuelve el ID de partición al que pertenece la fila. StringEjemplosEjemplo de uso
Query
DROP TABLE IF EXISTS tab;CREATE TABLE tab( i int, j int)ENGINE = MergeTreePARTITION BY iORDER BY tuple();INSERT INTO tab VALUES (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6);SELECT i, j, partitionId(i), _partition_id FROM tab ORDER BY i, j;
Introducido en: v21.9.0Devuelve el ID de la consulta actual.
Se pueden extraer otros parámetros de la consulta del campo query_id de la tabla system.query_log.A diferencia de la función initialQueryID, queryID puede devolver resultados diferentes en distintos segmentos.Sintaxis
queryID()
Alias: query_idArgumentos
Ninguno.
Valor devueltoDevuelve el ID de la consulta actual. StringEjemplosEjemplo de uso
Query
CREATE TABLE tmp (str String) ENGINE = Log;INSERT INTO tmp (*) VALUES ('a');SELECT count(DISTINCT t) FROM (SELECT queryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
Introducido en: v1.1.0Para cada bloque procesado por rowNumberInBlock, devuelve el número de la fila actual.El número devuelto comienza en 0 en cada bloque.Sintaxis
rowNumberInBlock()
Argumentos
Ninguno.
Valor devueltoDevuelve el número ordinal de la fila del bloque de datos a partir de 0. UInt64EjemplosEjemplo de uso
Introducido en: v1.1.0Acumula los estados de una función de agregación para cada fila de un bloque de datos.
ObsoletoEl estado se restablece con cada nuevo bloque de datos.
Debido a este comportamiento propenso a errores, la función ha quedado obsoleta, y se recomienda usar funciones de ventana en su lugar.
Puede usar la configuración allow_deprecated_error_prone_window_functions para permitir el uso de esta función.
grouping — Opcional. Clave de agrupación. El estado de la función se restablece si cambia el valor de grouping. Puede ser cualquiera de los tipos de datos compatibles para los que esté definido el operador de igualdad. Any
Valor devueltoDevuelve el resultado acumulado para cada fila. AnyEjemplosEjemplo de uso con initializeAggregation
Query
WITH initializeAggregation('sumState', number) AS one_row_sum_stateSELECT number, finalizeAggregation(one_row_sum_state) AS one_row_sum, runningAccumulate(one_row_sum_state) AS cumulative_sumFROM numbers(5);
Introducido en: v21.3.0Calcula el número de eventos concurrentes.
Cada evento tiene una hora de inicio y una hora de finalización.
La hora de inicio se incluye en el evento, mientras que la hora de finalización se excluye.
Las columnas con una hora de inicio y una hora de finalización deben tener el mismo tipo de datos.
La función calcula el número total de eventos activos (concurrentes) para cada hora de inicio de evento.
RequisitosLos eventos deben estar ordenados por hora de inicio en orden ascendente.
Si no se cumple este requisito, la función genera una excepción.
Cada bloque de datos se procesa por separado.
Si los eventos de distintos bloques de datos se superponen, no se pueden procesar correctamente.
Introducido en: v1.1.0Calcula la diferencia entre los valores de dos filas consecutivas en el bloque de datos.
Devuelve 0 para la primera fila y, para las siguientes, la diferencia con respecto a la fila anterior.
ObsoletoSolo devuelve diferencias dentro del bloque de datos que se está procesando en ese momento.
Debido a este comportamiento propenso a errores, la función está obsoleta.
Se recomienda usar funciones de ventana en su lugar.Puede usar la configuración allow_deprecated_error_prone_window_functions para permitir el uso de esta función.
El resultado de la función depende de los bloques de datos procesados y del orden de los datos dentro del bloque.
El orden de las filas durante el cálculo de runningDifference() puede diferir del orden de las filas que se devuelven al usuario.
Para evitarlo, puede crear una subconsulta con ORDER BY y llamar a la función fuera de la subconsulta.
Tenga en cuenta que el tamaño del bloque afecta al resultado.
El estado interno de runningDifference se restablece con cada bloque nuevo.Sintaxis
runningDifference(x)
Argumentos
x — Columna para la que se calcula la diferencia entre valores consecutivos. Any
Valor devueltoDevuelve la diferencia entre valores consecutivos, con 0 en la primera fila.EjemplosEjemplo de uso
Query
SELECT EventID, EventTime, runningDifference(EventTime) AS deltaFROM( SELECT EventID, EventTime FROM events WHERE EventDate = '2025-11-24' ORDER BY EventTime ASC LIMIT 5);
Introducido en: v1.1.0Calcula la diferencia entre los valores de filas consecutivas en un bloque de datos, pero, a diferencia de runningDifference, devuelve el valor real de la primera fila en lugar de 0.
ObsoletoSolo devuelve las diferencias dentro del bloque de datos que se está procesando en ese momento.
Debido a este comportamiento propenso a errores, la función está obsoleta.
Se recomienda usar funciones de ventana en su lugar.Puede usar la configuración allow_deprecated_error_prone_window_functions para permitir el uso de esta función.
Sintaxis
runningDifferenceStartingWithFirstValue(x)
Argumentos
x — Columna para la que se calcula la diferencia acumulada. Any
Valor devueltoDevuelve la diferencia entre valores consecutivos; para la primera fila, devuelve el valor de esa misma fila. AnyEjemplosEjemplo de uso
Query
SELECT number, runningDifferenceStartingWithFirstValue(number) AS diffFROM numbers(5);
Introducido en: v20.1.0Devuelve el UUID (v4) aleatorio y único generado cuando el servidor se inicia por primera vez.
El UUID se almacena de forma persistente; es decir, en el segundo, tercer, etc. inicio del servidor se devuelve el mismo UUID.Sintaxis
serverUUID()
Argumentos
Ninguno.
Valor devueltoDevuelve el UUID aleatorio del servidor. UUIDEjemplosEjemplo de uso
Introducido en: v21.9.0Devuelve el número total de segmentos de una consulta distribuida.
Si la consulta no es distribuida, se devuelve el valor constante 0.Sintaxis
shardCount()
Argumentos
Ninguno.
Valor devueltoDevuelve el número total de segmentos o 0. UInt32EjemplosEjemplo de uso
Query
-- Consulta el ejemplo de shardNum() anterior, que también muestra shardCount()CREATE TABLE shard_count_example (dummy UInt8)ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);SELECT shardCount() FROM shard_count_example;
Introducido en: v21.9.0Devuelve el índice de un segmento que procesa una parte de los datos en una consulta distribuida.
Los índices comienzan en 1.
Si una consulta no es distribuida, se devuelve el valor constante 0.Sintaxis
shardNum()
Argumentos
Ninguno.
Valor devueltoDevuelve el índice del segmento o una constante 0. UInt32EjemplosEjemplo de uso
Introducido en: v22.6.0Muestra información sobre el certificado SSL actual del servidor, si se ha configurado.
Consulta Configuración de TLS para obtener más información sobre cómo configurar ClickHouse para usar certificados OpenSSL para validar las conexiones.Sintaxis
showCertificate()
Argumentos
Ninguno.
Valor devueltoDevuelve un mapa de pares clave-valor relacionados con el certificado SSL configurado. Map(String, String)EjemplosEjemplo de uso
Introducido en: v1.1.0Pausa la ejecución de una consulta durante el número de segundos especificado.
La función se utiliza principalmente para pruebas y depuración.Por lo general, la función sleep() no debe usarse en entornos de producción, ya que puede afectar negativamente al rendimiento de las consultas y a la capacidad de respuesta del sistema.
Sin embargo, puede resultar útil en los siguientes casos:
Pruebas: Al probar o ejecutar benchmarks de ClickHouse, es posible que desee simular retrasos o introducir pausas para observar cómo se comporta el sistema en determinadas condiciones.
Depuración: Si necesita examinar el estado del sistema o la ejecución de una consulta en un momento concreto, puede usar sleep() para introducir una pausa, lo que le permitirá inspeccionar o recopilar información relevante.
Simulación: En algunos casos, es posible que desee simular situaciones reales en las que se producen retrasos o pausas, como la latencia de red o las dependencias de sistemas externos.
Es importante usar la función sleep() con prudencia y solo cuando sea necesario, ya que puede afectar al rendimiento general y a la capacidad de respuesta de su sistema ClickHouse.
Por razones de seguridad, la función solo puede ejecutarse en el perfil de usuario predeterminado (con allow_sleep habilitado).Sintaxis
sleep(seconds)
Argumentos
seconds — El número de segundos durante los que se pausará la ejecución de la consulta, con un máximo de 3 segundos. Puede ser un valor de coma flotante para especificar fracciones de segundo. const UInt* o const Float*
Valor devueltoDevuelve 0. UInt8EjemplosEjemplo de uso
Query
-- Esta consulta se pausará durante 2 segundos antes de completarse.-- Durante este tiempo, no se devolverán resultados y la consulta parecerá estar bloqueada o sin respuesta.SELECT sleep(2);
Response
┌─sleep(2)─┐│ 0 │└──────────┘1 row in set. Elapsed: 2.012 sec.
Introducido en: v1.1.0Pausa la ejecución de una consulta durante un número determinado de segundos por cada fila del conjunto de resultados.La función sleepEachRow() se utiliza principalmente para pruebas y depuración, de forma similar a la función sleep().
Permite simular retrasos o introducir pausas en el procesamiento de cada fila, lo que puede resultar útil en escenarios como los siguientes:
Pruebas: Al probar o hacer benchmark del rendimiento de ClickHouse en condiciones específicas, puede usar sleepEachRow() para simular retrasos o introducir pausas en cada fila procesada.
Depuración: Si necesita examinar el estado del sistema o la ejecución de una consulta para cada fila procesada, puede usar sleepEachRow() para introducir pausas, lo que le permitirá inspeccionar o recopilar información relevante.
Simulación: En algunos casos, puede que desee simular situaciones del mundo real en las que se producen retrasos o pausas por cada fila procesada, como al trabajar con sistemas externos o con latencias de red.
Al igual que con la función sleep(), es importante usar sleepEachRow() con prudencia y solo cuando sea necesario, ya que puede afectar significativamente al rendimiento general y a la capacidad de respuesta de su sistema ClickHouse, especialmente al trabajar con conjuntos de resultados grandes.
Sintaxis
sleepEachRow(seconds)
Argumentos
seconds — Número de segundos durante los que se pausa la ejecución de la consulta para cada fila del conjunto de resultados, con un máximo de 3 segundos. Puede ser un valor de punto flotante para especificar fracciones de segundo. const UInt* o const Float*
Valor devueltoDevuelve 0 para cada fila. UInt8EjemplosEjemplo de uso
Query
-- La salida se retrasará, con una pausa de 0,5 segundos entre cada fila.SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;
Introducido en: v23.8.0Convierte la estructura de una tabla de ClickHouse en un esquema de formato Protobuf.Esta función toma la definición de la estructura de una tabla de ClickHouse y la convierte en una definición de esquema de Protocol Buffers (Protobuf) con sintaxis proto3. Esto resulta útil para generar esquemas de Protobuf que coincidan con las estructuras de tus tablas de ClickHouse para el intercambio de datos.Sintaxis
structure — Definición de la estructura de la tabla de ClickHouse como una cadena (p. ej., ‘column1 Type1, column2 Type2’). String
message_name — Nombre del tipo de mensaje de Protobuf en el esquema generado. String
Valor devueltoDevuelve una definición de esquema Protobuf en sintaxis proto3 que corresponde a la estructura de ClickHouse proporcionada. StringEjemplosConversión de la estructura de ClickHouse a un esquema Protobuf
Query
SELECT structureToProtobufSchema('s String, x UInt32', 'MessageName') FORMAT TSVRaw;
Response
syntax = "proto3";message MessageName{ bytes s = 1; uint32 x = 2;}
Introducido en: v20.12.0Devuelve el número de puerto TCP en el que escucha el server nativo.
Si se ejecuta en el contexto de una tabla distribuida, esta función genera una columna normal con valores correspondientes a cada segmento.
De lo contrario, devuelve un valor constante.Sintaxis
tcpPort()
Argumentos
Ninguno.
Valor devueltoDevuelve el número de puerto TCP. UInt16EjemplosEjemplo de uso
Introducido en: v1.1.0Lanza una excepción si el argumento x es verdadero.
Para usar el argumento error_code, el parámetro de configuración allow_custom_error_code_in_throw debe estar habilitado.Sintaxis
message — Opcional. Mensaje de error personalizado. const String
error_code — Opcional. Código de error personalizado. const Int8/16/32
Valor devueltoDevuelve 0 si la condición es falsa; lanza una excepción si la condición es verdadera. UInt8EjemplosEjemplo de uso
Query
SELECT throwIf(number = 3, 'Too many') FROM numbers(10);
Response
↙ Progress: 0.00 rows, 0.00 B (0.00 rows/s., 0.00 B/s.) Received exception from server (version 19.14.1):Code: 395. DB::Exception: Received from localhost:9000. DB::Exception: Too many.
Introducido en: v1.1.0Devuelve el nombre interno del tipo de datos del valor dado.
A diferencia de la función toTypeName, el tipo de datos devuelto puede incluir columnas internas contenedoras como Const y LowCardinality.Sintaxis
toColumnTypeName(value)
Argumentos
value — Valor para el que se devuelve el tipo de dato interno. Any
Valor devueltoDevuelve el tipo de dato interno que se usa para representar el valor. StringEjemplosEjemplo de uso
Query
SELECT toColumnTypeName(CAST('2025-01-01 01:02:03' AS DateTime));
Introducido en: v1.1.0Devuelve el nombre del tipo del argumento proporcionado.
Si se pasa NULL, la función devuelve el tipo Nullable(Nothing), que corresponde a la representación interna de NULL en ClickHouse.Sintaxis
Introducido en: v26.5.0Tokeniza una cadena de consulta SQL de ClickHouse y devuelve un array de tokens.
Cada token es una tupla con nombre con la posición inicial (en bytes), la posición final y el tipo de token.Sintaxis
tokenizeQuery(query)
Argumentos
query — Una cadena con una consulta de ClickHouse SQL. String.
Introducido en: v22.6.0Devuelve el ID de una transacción.
Esta función forma parte de un conjunto de funcionalidades experimentales.
Habilite la compatibilidad experimental con transacciones añadiendo este ajuste a su configuración:
Introducido en: v22.6.0Devuelve la instantánea más reciente (Commit Sequence Number) de una transacción disponible para lectura.
Esta función forma parte de un conjunto de características experimentales. Habilite la compatibilidad experimental con transacciones añadiendo esta configuración a su archivo de configuración:
Introducido en: v22.6.0Devuelve la instantánea más antigua (Commit Sequence Number) visible para alguna transacción en ejecución.
Esta función forma parte de un conjunto de características experimentales. Habilite la compatibilidad con transacciones experimentales añadiendo esta configuración a su configuración:
Introducido en: v1.1.0Transforma un valor según una asignación definida explícitamente de unos elementos a otros.Hay dos variantes de esta función:
transform(x, array_from, array_to, default) - transforma x mediante arrays de asignación, con un valor predeterminado para los elementos que no coincidan
transform(x, array_from, array_to) - realiza la misma transformación, pero devuelve el x original si no se encuentra ninguna coincidencia
La función busca x en array_from y devuelve el elemento correspondiente de array_to en el mismo índice.
Si x no se encuentra en array_from, devuelve el valor default (versión de 4 parámetros) o el x original (versión de 3 parámetros).
Si hay varios elementos coincidentes en array_from, devuelve el elemento correspondiente a la primera coincidencia.Requisitos:
array_from y array_to deben tener el mismo número de elementos
Para la versión de 4 parámetros: transform(T, Array(T), Array(U), U) -> U donde T y U pueden ser tipos compatibles distintos
Para la versión de 3 parámetros: transform(T, Array(T), Array(T)) -> T donde todos los tipos deben ser iguales
default — Opcional. Valor que se devolverá si x no se encuentra en array_from. Si se omite, devuelve x sin cambios. (U)Int* o Decimal o Float* o String o Date o DateTime
Valor devueltoDevuelve el valor correspondiente de array_to si x coincide con un elemento de array_from; de lo contrario, devuelve default (si se proporciona) o x (si no se proporciona default). AnyEjemplostransform(T, Array(T), Array(U), U) -> U
Query
SELECTtransform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,count() AS cFROM test.hitsWHERE SearchEngineID != 0GROUP BY titleORDER BY c DESC
Response
┌─title─────┬──────c─┐│ Yandex │ 498635 ││ Google │ 229872 ││ Other │ 104472 │└───────────┴────────┘
transform(T, Array(T), Array(T)) -> T
Query
SELECTtransform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s, count() AS cFROM test.hitsGROUP BY domain(Referer)ORDER BY count() DESCLIMIT 10
Introducido en: v22.9.0Calcula la intersección de dos objetos uniqThetaSketch (operación de conjuntos ∩); el resultado es un nuevo uniqThetaSketch.Sintaxis
Valor devueltoUn nuevo uniqThetaSketch que contiene el resultado de intersect. UInt64EjemplosEjemplo de uso
Query
SELECT finalizeAggregation(uniqThetaIntersect(a, b)) AS a_intersect_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinalityFROM(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);
Introducido en: v22.9.0Dados dos objetos uniqThetaSketch, realiza el cálculo a_not_b (operación de conjuntos ×) y el resultado es un nuevo uniqThetaSketch.Sintaxis
Valor devueltoDevuelve un nuevo uniqThetaSketch que contiene el resultado de a_not_b. UInt64EjemplosEjemplo de uso
Query
SELECT finalizeAggregation(uniqThetaNot(a, b)) AS a_not_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinalityFROM(SELECT arrayReduce('uniqThetaState', [2, 3, 4]) AS a, arrayReduce('uniqThetaState', [1, 2]) AS b);
Introducido en: v22.9.0Une dos objetos uniqThetaSketch para realizar el cálculo de unión (operación de conjuntos ∪); el resultado es un nuevo uniqThetaSketch.Sintaxis
Valor devueltoDevuelve un nuevo uniqThetaSketch con el resultado de la unión. UInt64EjemplosEjemplo de uso
Query
SELECT finalizeAggregation(uniqThetaUnion(a, b)) AS a_union_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinalityFROM(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);
Introducido en: v1.1.0Devuelve el tiempo de actividad del servidor en segundos.
Si se ejecuta en el contexto de una tabla distribuida, esta función genera una columna normal con valores correspondientes a cada segmento.
De lo contrario, produce un valor constante.Sintaxis
uptime()
Argumentos
Ninguno.
Valor devueltoDevuelve el tiempo de actividad del servidor en segundos. UInt32EjemplosEjemplo de uso
type_name — El nombre del tipo de variante que se va a extraer. String
default_value — El valor predeterminado que se usará si variant no tiene una variante del tipo especificado. Puede ser de cualquier tipo. Opcional. Any
Valor devueltoDevuelve una columna con el tipo de variante especificado extraído de la columna Variant. AnyEjemplosEjemplo de uso
Query
CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);SELECT v, variantElement(v, 'String'), variantElement(v, 'UInt64'), variantElement(v, 'Array(UInt64)') FROM test;
Introducido en: v24.2.0Devuelve el nombre del tipo de variante de cada fila de una columna Variant. Si una fila contiene NULL, devuelve ‘None’.Sintaxis
Valor devueltoDevuelve una columna Enum con el nombre del tipo de Variant para cada fila. EnumEjemplosEjemplo de uso
Query
CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);SELECT variantType(v) FROM test;
Introducido en: v1.1.0Devuelve la versión actual de ClickHouse como una cadena con el formato: major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release.
Si se ejecuta en el contexto de una tabla distribuida, esta función genera una columna normal con valores correspondientes a cada segmento.
En caso contrario, produce un valor constante.Sintaxis
version()
Argumentos
Ninguno.
Valor devueltoDevuelve la versión actual de ClickHouse. StringEjemplosEjemplo de uso
Introducido en: v1.1.0Calcula el ancho aproximado al mostrar valores en la consola en formato de texto (separado por tabulaciones).
El sistema usa esta función para implementar los formatos Pretty.
NULL se representa como una cadena correspondiente a NULL en los formatos Pretty.Sintaxis
