system.documentation

Tabla del sistema que recopila en una sola tabla la documentación integrada de los componentes homogéneos del sistema (funciones, motores de tabla, tipos de datos, etc.), con la documentación de referencia presentada en formato Markdown.

​

Descripción

Recopila en una sola tabla la documentación integrada de los componentes homogéneos del sistema. Cada fila corresponde a una entidad (una función, un motor de tabla, un tipo de dato, etc.) y contiene su documentación de referencia integrada en formato Markdown. Este contenido sirve de base para la documentación generada del sitio web y para las tablas system.* específicas de cada tipo; las páginas web pueden añadir preámbulos u orientaciones exclusivos de MDX fuera de sus cuerpos generados.

La description se compone a partir de las partes estructuradas de la documentación integrada (description, syntax, argumentos, ejemplos, etc.), de modo que una sola columna contiene la documentación integrada completa de una entidad. Cuando la documentación integrada contiene en su description toda la página de referencia (como ocurre con los componentes cuyas páginas web se generan automáticamente a partir de ella: motores de tabla, motores de base de datos, tipos de datos, formatos y funciones de tabla), la página se publica tal cual, sin añadir secciones compuestas a partir de los campos de metadatos estructurados, ya que el cuerpo de la página ya cubre ese material. Los alias se muestran como una referencia breve a la entidad canónica; por ejemplo, Alias of `trunc`.

Esta tabla, en cierto modo, recopila la información disponible en las tablas de documentación específicas de cada tipo (system.functions, system.table_engines, system.data_type_families y otras). Está pensada, en particular, como base para un comando help interactivo en el client, pero también es útil por sí sola.

Se recopilan los siguientes tipos de entidades (el valor de la columna type se muestra entre paréntesis):

• Funciones (Function)
• Funciones de agregación (Aggregate Function)
• Funciones de tabla (Table Function)
• Motores de tabla (Table Engine)
• Motores de base de datos (Database Engine)
• Tipos de datos (Data Type)
• Diseños de diccionario (Dictionary Layout)
• Fuentes de diccionario (Dictionary Source)
• Combinadores de funciones de agregación (Aggregate Function Combinator)
• Tipos de índices de omisión de datos (Data Skipping Index)
• Tipos de disco (Disk Type)
• SETTINGS (Setting)
• SETTINGS de MergeTree (MergeTree Setting)
• SETTINGS del servidor (Server Setting)
• Formatos (Format)
• Códecs de compresión (Compression Codec)
• Eventos de perfil (Profile Event)
• Métricas actuales (Current Metric)
• Métricas asincrónicas (Asynchronous Metric)
• Tablas del sistema (System Table)
• Sentencias SQL (Statement)

En el caso de los SETTINGS (de cualquier tipo), la documentación es la descripción del SETTING, junto con su tipo y su valor predeterminado; los SETTINGS obsoletos no se exponen. También contiene el historial de los cambios en el valor predeterminado del SETTING entre las versiones de ClickHouse: la versión en la que se introdujo el SETTING y cada cambio posterior de su valor predeterminado, con el valor anterior, el valor nuevo y el motivo del cambio. Son los mismos datos que sirven de base para el SETTING compatibility y system.settings_changes, por lo que cubren los cambios registrados desde que se introdujo ese mecanismo: un SETTING antiguo cuyo valor predeterminado nunca cambió no tiene historial, ni tampoco los SETTINGS del servidor, que compatibility no cubre. Un cambio registrado bajo un alias de un SETTING pertenece al historial de ese SETTING, del mismo modo que lo aplica compatibility, por lo que el historial de un SETTING que se renombró no se interrumpe en el cambio de nombre; la excepción es un registro escrito bajo un alias con el único propósito de registrar ese alias, que pertenece únicamente al historial del alias. Un alias contiene el historial de su propio nombre: cada registro escrito bajo él, además del registro que lo registró como alias, que el archivo de historial a veces escribe bajo otro nombre del mismo SETTING.

En el caso de las tablas del sistema, la descripción, los ejemplos y el material relacionado se almacenan en el comentario de metadatos de la tabla mediante marcadores de sección ligeros. El cuerpo completo de la página generada se compone a partir de ese comentario y del esquema de columnas en vivo. Los catálogos de eventos y métricas se generan a partir de sus registros, de modo que los detalles generados se mantienen sincronizados con el binario en ejecución.

Para las sentencias SQL, la documentación se genera a partir de los campos estructurados expuestos por system.statements, incluida la sintaxis y las sentencias relacionadas cuando esas secciones no forman ya parte de la descripción controlada por el archivo fuente.

La columna source contiene una ruta de origen de la entidad, relativa a la raíz del repositorio. Para la mayoría de las entidades, se captura automáticamente en el lugar donde se construye el objeto de documentación (el punto de registro del componente); para las tablas del sistema es el archivo propietario de la documentación integrada (como attachSystemTables.cpp, SystemLog.h o un propietario de documentación específico), y para los tipos que se documentan cada uno en un único archivo fuente (como los SETTINGS, los eventos de perfil y las métricas actuales), ese archivo es el que se usa.

​

Columnas

• name (String) — El nombre de la entidad, p. ej. domainWithoutWWW o MergeTree.
• type (Enum8(‘Function’ = 1, ‘Aggregate Function’ = 2, ‘Table Function’ = 3, ‘Table Engine’ = 4, ‘Database Engine’ = 5, ‘Data Type’ = 6, ‘Dictionary Layout’ = 7, ‘Dictionary Source’ = 8, ‘Aggregate Function Combinator’ = 9, ‘Data Skipping Index’ = 10, ‘Disk Type’ = 11, ‘Setting’ = 12, ‘MergeTree Setting’ = 13, ‘Server Setting’ = 14, ‘Format’ = 15, ‘Compression Codec’ = 16, ‘Profile Event’ = 17, ‘Current Metric’ = 18, ‘Asynchronous Metric’ = 19, ‘System Table’ = 20, ‘Statement’ = 21)) — El tipo de la entidad, p. ej. Function o Table Engine.
• description (String) — La documentación de referencia de la entidad en formato Markdown, generada a partir de la documentación integrada, incluida la sintaxis, los ejemplos y otras partes estructuradas, si las hay. Las páginas del sitio web pueden añadir preámbulos u orientaciones exclusivos de MDX fuera de sus cuerpos generados.
• source (String) — La ruta al archivo fuente donde se define la documentación de la entidad, relativa a la raíz del repositorio. Vacío si se desconoce la ubicación del archivo fuente.

​

Ejemplo

Consulta la documentación de una entidad concreta:

Query

SELECT description
FROM system.documentation
WHERE type = 'Table Engine' AND name = 'MergeTree'
FORMAT TSVRaw;

El mismo nombre puede referirse a varios tipos de entidades (por ejemplo, existe tanto la función de tabla file como la fuente file), por lo que conviene buscar ese nombre en todos los tipos:

Query

SELECT type, name
FROM system.documentation
WHERE name = 'file'
ORDER BY type;

Cuenta las entidades documentadas de cada tipo:

Query

SELECT type, count()
FROM system.documentation
GROUP BY type
ORDER BY count() DESC;

Descubre en qué versión se introdujo un SETTING y cómo ha cambiado su valor predeterminado desde entonces:

Query

SELECT description
FROM system.documentation
WHERE type = 'Setting' AND name = 'async_insert_max_data_size'
FORMAT TSVRaw;

​

Véase también

• system.functions — Funciones normales y de agregación.
• system.table_functions — Funciones de tabla.
• system.table_engines — Motores de tabla.
• system.database_engines — Motores de base de datos.
• system.data_type_families — Tipos de datos.
• system.disk_types — Tipos de disco.
• system.settings — SETTINGS.
• system.merge_tree_settings — SETTINGS de MergeTree.
• system.server_settings — SETTINGS del servidor.
• system.settings_changes — Historial de cambios en los valores predeterminados de los SETTINGS.
• system.formats — Formatos.