ClickHouse/docs/es/query_language/dicts/external_dicts_dict_sources.md

Fuentes de diccionarios externos

Un diccionario externo se puede conectar desde muchas fuentes diferentes.

Si el diccionario se configura usando xml-file, la configuración se ve así:

<yandex>
  <dictionary>
    ...
    <source>
      <source_type>
        <!-- Source configuration -->
      </source_type>
    </source>
    ...
  </dictionary>
  ...
</yandex>

En caso de Consulta DDL, la configuración igual parecerá:

CREATE DICTIONARY dict_name (...)
...
SOURCE(SOURCE_TYPE(param1 val1 ... paramN valN)) -- Source configuration
...

El origen está configurado en el source apartado.

Tipos de fuentes (source_type):

• Archivo Local
• Archivo ejecutable
• HTTP(s))
• DBMS
  • ODBC
  • MySQL
  • Haga clic en Casa
  • MongoDB
  • Redis

Archivo Local

Ejemplo de configuración:

<source>
  <file>
    <path>/opt/dictionaries/os.tsv</path>
    <format>TabSeparated</format>
  </file>
</source>

o

SOURCE(FILE(path '/opt/dictionaries/os.tsv' format 'TabSeparated'))

Configuración de campos:

• path – The absolute path to the file.
• format – The file format. All the formats described in “Formato” son compatibles.

Archivo ejecutable

Trabajar con archivos ejecutables depende de cómo se almacena el diccionario en la memoria. Si el diccionario se almacena usando cache y complex_key_cache, ClickHouse requests the necessary keys by sending a request to the executable file’s STDIN. Otherwise, ClickHouse starts executable file and treats its output as dictionary data.

Ejemplo de configuración:

<source>
    <executable>
        <command>cat /opt/dictionaries/os.tsv</command>
        <format>TabSeparated</format>
    </executable>
</source>

o

SOURCE(EXECUTABLE(command 'cat /opt/dictionaries/os.tsv' format 'TabSeparated'))

Configuración de campos:

• command – The absolute path to the executable file, or the file name (if the program directory is written to PATH).
• format – The file format. All the formats described in “Formato” son compatibles.

HTTP(s))

Trabajar con un servidor HTTP depende de cómo se almacena el diccionario en la memoria. Si el diccionario se almacena usando cache y complex_key_cache, ClickHouse solicita las claves necesarias enviando una solicitud a través del POST método.

Ejemplo de configuración:

<source>
    <http>
        <url>http://[::1]/os.tsv</url>
        <format>TabSeparated</format>
        <credentials>
            <user>user</user>
            <password>password</password>
        </credentials>
        <headers>
            <header>
                <name>API-KEY</name>
                <value>key</value>
            </header>
        </headers>
    </http>
</source>

o

SOURCE(HTTP(
    url 'http://[::1]/os.tsv'
    format 'TabSeparated'
    credentials(user 'user' password 'password')
    headers(header(name 'API-KEY' value 'key'))
))

Para que ClickHouse tenga acceso a un recurso HTTPS, debe configurar openSSL en la configuración del servidor.

Configuración de campos:

• url – The source URL.
• format – The file format. All the formats described in “Formato” son compatibles.
• credentials – Basic HTTP authentication. Optional parameter.
  • user – Username required for the authentication.
  • password – Password required for the authentication.
• headers – All custom HTTP headers entries used for the HTTP request. Optional parameter.
  • header – Single HTTP header entry.
  • name – Identifiant name used for the header send on the request.
  • value – Value set for a specific identifiant name.

ODBC

Puede utilizar este método para conectar cualquier base de datos que tenga un controlador ODBC.

Ejemplo de configuración:

<source>
    <odbc>
        <db>DatabaseName</db>
        <table>ShemaName.TableName</table>
        <connection_string>DSN=some_parameters</connection_string>
        <invalidate_query>SQL_QUERY</invalidate_query>
    </odbc>
</source>

o

SOURCE(ODBC(
    db 'DatabaseName'
    table 'SchemaName.TableName'
    connection_string 'DSN=some_parameters'
    invalidate_query 'SQL_QUERY'
))

Configuración de campos:

• db – Name of the database. Omit it if the database name is set in the <connection_string> parámetros.
• table – Name of the table and schema if exists.
• connection_string – Connection string.
• invalidate_query – Query for checking the dictionary status. Optional parameter. Read more in the section Actualización de diccionarios.

ClickHouse receives quoting symbols from ODBC-driver and quote all settings in queries to driver, so it’s necessary to set table name accordingly to table name case in database.

Si tiene problemas con las codificaciones al utilizar Oracle, consulte el Preguntas frecuentes artículo.

Vulnerabilidad conocida de la funcionalidad del diccionario ODBC

!!! attention "Atención" Cuando se conecta a la base de datos a través del parámetro de conexión del controlador ODBC Servername puede ser sustituido. En este caso los valores de USERNAME y PASSWORD de odbc.ini se envían al servidor remoto y pueden verse comprometidos.

Ejemplo de uso inseguro

Let’s configure unixODBC for PostgreSQL. Content of /etc/odbc.ini:

[gregtest]
Driver = /usr/lib/psqlodbca.so
Servername = localhost
PORT = 5432
DATABASE = test_db
#OPTION = 3
USERNAME = test
PASSWORD = test

Si luego realiza una consulta como

SELECT * FROM odbc('DSN=gregtest;Servername=some-server.com', 'test_db');

El controlador ODBC enviará valores de USERNAME y PASSWORD de odbc.ini a some-server.com.

Ejemplo de conexión de PostgreSQL

Sistema operativo Ubuntu.

Instalación de unixODBC y el controlador ODBC para PostgreSQL:

$ sudo apt-get install -y unixodbc odbcinst odbc-postgresql

Configuración /etc/odbc.ini (o ~/.odbc.ini):

    [DEFAULT]
    Driver = myconnection

    [myconnection]
    Description         = PostgreSQL connection to my_db
    Driver              = PostgreSQL Unicode
    Database            = my_db
    Servername          = 127.0.0.1
    UserName            = username
    Password            = password
    Port                = 5432
    Protocol            = 9.3
    ReadOnly            = No
    RowVersioning       = No
    ShowSystemTables    = No
    ConnSettings        =

La configuración del diccionario en ClickHouse:

<yandex>
    <dictionary>
        <name>table_name</name>
        <source>
            <odbc>
                <!-- You can specify the following parameters in connection_string: -->
                <!-- DSN=myconnection;UID=username;PWD=password;HOST=127.0.0.1;PORT=5432;DATABASE=my_db -->
                <connection_string>DSN=myconnection</connection_string>
                <table>postgresql_table</table>
            </odbc>
        </source>
        <lifetime>
            <min>300</min>
            <max>360</max>
        </lifetime>
        <layout>
            <hashed/>
        </layout>
        <structure>
            <id>
                <name>id</name>
            </id>
            <attribute>
                <name>some_column</name>
                <type>UInt64</type>
                <null_value>0</null_value>
            </attribute>
        </structure>
    </dictionary>
</yandex>

o

CREATE DICTIONARY table_name (
    id UInt64,
    some_column UInt64 DEFAULT 0
)
PRIMARY KEY id
SOURCE(ODBC(connection_string 'DSN=myconnection' table 'postgresql_table'))
LAYOUT(HASHED())
LIFETIME(MIN 300 MAX 360)

Es posible que tenga que editar odbc.ini para especificar la ruta completa a la biblioteca con el controlador DRIVER=/usr/local/lib/psqlodbcw.so.

Ejemplo de conexión de MS SQL Server

Sistema operativo Ubuntu.

Instalación del controlador: :

$ sudo apt-get install tdsodbc freetds-bin sqsh

Configuración del controlador:

    $ cat /etc/freetds/freetds.conf
    ...

    [MSSQL]
    host = 192.168.56.101
    port = 1433
    tds version = 7.0
    client charset = UTF-8

    $ cat /etc/odbcinst.ini
    ...

    [FreeTDS]
    Description     = FreeTDS
    Driver          = /usr/lib/x86_64-linux-gnu/odbc/libtdsodbc.so
    Setup           = /usr/lib/x86_64-linux-gnu/odbc/libtdsS.so
    FileUsage       = 1
    UsageCount      = 5

    $ cat ~/.odbc.ini
    ...

    [MSSQL]
    Description     = FreeTDS
    Driver          = FreeTDS
    Servername      = MSSQL
    Database        = test
    UID             = test
    PWD             = test
    Port            = 1433

Configuración del diccionario en ClickHouse:

<yandex>
    <dictionary>
        <name>test</name>
        <source>
            <odbc>
                <table>dict</table>
                <connection_string>DSN=MSSQL;UID=test;PWD=test</connection_string>
            </odbc>
        </source>

        <lifetime>
            <min>300</min>
            <max>360</max>
        </lifetime>

        <layout>
            <flat />
        </layout>

        <structure>
            <id>
                <name>k</name>
            </id>
            <attribute>
                <name>s</name>
                <type>String</type>
                <null_value></null_value>
            </attribute>
        </structure>
    </dictionary>
</yandex>

o

CREATE DICTIONARY test (
    k UInt64,
    s String DEFAULT ''
)
PRIMARY KEY k
SOURCE(ODBC(table 'dict' connection_string 'DSN=MSSQL;UID=test;PWD=test'))
LAYOUT(FLAT())
LIFETIME(MIN 300 MAX 360)

DBMS

MySQL

Ejemplo de configuración:

<source>
  <mysql>
      <port>3306</port>
      <user>clickhouse</user>
      <password>qwerty</password>
      <replica>
          <host>example01-1</host>
          <priority>1</priority>
      </replica>
      <replica>
          <host>example01-2</host>
          <priority>1</priority>
      </replica>
      <db>db_name</db>
      <table>table_name</table>
      <where>id=10</where>
      <invalidate_query>SQL_QUERY</invalidate_query>
  </mysql>
</source>

o

SOURCE(MYSQL(
    port 3306
    user 'clickhouse'
    password 'qwerty'
    replica(host 'example01-1' priority 1)
    replica(host 'example01-2' priority 1)
    db 'db_name'
    table 'table_name'
    where 'id=10'
    invalidate_query 'SQL_QUERY'
))

Configuración de campos:

• port – The port on the MySQL server. You can specify it for all replicas, or for each one individually (inside <replica>).

• user – Name of the MySQL user. You can specify it for all replicas, or for each one individually (inside <replica>).

• password – Password of the MySQL user. You can specify it for all replicas, or for each one individually (inside <replica>).

• replica – Section of replica configurations. There can be multiple sections.

  - `replica/host` – The MySQL host.
  - `replica/priority` – The replica priority. When attempting to connect, ClickHouse traverses the replicas in order of priority. The lower the number, the higher the priority.
  

• db – Name of the database.

• table – Name of the table.

• where – The selection criteria. The syntax for conditions is the same as for WHERE cláusula en MySQL, por ejemplo, id > 10 AND id < 20. Parámetro opcional.

• invalidate_query – Query for checking the dictionary status. Optional parameter. Read more in the section Actualización de diccionarios.

MySQL se puede conectar en un host local a través de sockets. Para hacer esto, establezca host y socket.

Ejemplo de configuración:

<source>
  <mysql>
      <host>localhost</host>
      <socket>/path/to/socket/file.sock</socket>
      <user>clickhouse</user>
      <password>qwerty</password>
      <db>db_name</db>
      <table>table_name</table>
      <where>id=10</where>
      <invalidate_query>SQL_QUERY</invalidate_query>
  </mysql>
</source>

o

SOURCE(MYSQL(
    host 'localhost'
    socket '/path/to/socket/file.sock'
    user 'clickhouse'
    password 'qwerty'
    db 'db_name'
    table 'table_name'
    where 'id=10'
    invalidate_query 'SQL_QUERY'
))

Haga clic en Casa

Ejemplo de configuración:

<source>
    <clickhouse>
        <host>example01-01-1</host>
        <port>9000</port>
        <user>default</user>
        <password></password>
        <db>default</db>
        <table>ids</table>
        <where>id=10</where>
    </clickhouse>
</source>

o

SOURCE(CLICKHOUSE(
    host 'example01-01-1'
    port 9000
    user 'default'
    password ''
    db 'default'
    table 'ids'
    where 'id=10'
))

Configuración de campos:

• host – The ClickHouse host. If it is a local host, the query is processed without any network activity. To improve fault tolerance, you can create a Distribuido tabla e ingrésela en configuraciones posteriores.
• port – The port on the ClickHouse server.
• user – Name of the ClickHouse user.
• password – Password of the ClickHouse user.
• db – Name of the database.
• table – Name of the table.
• where – The selection criteria. May be omitted.
• invalidate_query – Query for checking the dictionary status. Optional parameter. Read more in the section Actualización de diccionarios.

MongoDB

Ejemplo de configuración:

<source>
    <mongodb>
        <host>localhost</host>
        <port>27017</port>
        <user></user>
        <password></password>
        <db>test</db>
        <collection>dictionary_source</collection>
    </mongodb>
</source>

o

SOURCE(MONGO(
    host 'localhost'
    port 27017
    user ''
    password ''
    db 'test'
    collection 'dictionary_source'
))

Configuración de campos:

• host – The MongoDB host.
• port – The port on the MongoDB server.
• user – Name of the MongoDB user.
• password – Password of the MongoDB user.
• db – Name of the database.
• collection – Name of the collection.

Redis

Ejemplo de configuración:

<source>
    <redis>
        <host>localhost</host>
        <port>6379</port>
        <storage_type>simple</storage_type>
        <db_index>0</db_index>
    </redis>
</source>

o

SOURCE(REDIS(
    host 'localhost'
    port 6379
    storage_type 'simple'
    db_index 0
))

Configuración de campos:

• host – The Redis host.
• port – The port on the Redis server.
• storage_type – The structure of internal Redis storage using for work with keys. simple es para fuentes simples y para fuentes de clave única hash, hash_map es para fuentes hash con dos teclas. Los orígenes a distancia y los orígenes de caché con clave compleja no son compatibles. Puede omitirse, el valor predeterminado es simple.
• db_index – The specific numeric index of Redis logical database. May be omitted, default value is 0.

Artículo Original