المجموعات المُسمّاة

وثائق المجموعات المُسمّاة

توفر المجموعات المسماة طريقة لتخزين مجموعات من أزواج المفتاح والقيمة لاستخدامها في تهيئة عمليات التكامل مع المصادر الخارجية. يمكنك استخدام المجموعات المسماة مع القواميس والجداول ودوال الجداول وتخزين الكائنات.

يمكن تهيئة المجموعات المسماة باستخدام DDL أو ضمن ملفات التهيئة، ويُعمل بها عند بدء تشغيل ClickHouse. وهي تُبسّط إنشاء الكائنات وإخفاء بيانات الاعتماد عن المستخدمين الذين لا يملكون صلاحية وصول إدارية.

يجب أن تتطابق المفاتيح في المجموعة المسماة مع أسماء المعلَمات الخاصة بما يقابلها من دالة أو محرك جدول أو قاعدة بيانات، وما إلى ذلك. في الأمثلة أدناه، أُدرج رابط إلى قائمة المعلَمات الخاصة بكل نوع.

يمكن تجاوز المعلَمات المضبوطة في مجموعة مسماة داخل SQL، وهذا موضح في الأمثلة أدناه. ويمكن تقييد هذه الإمكانية باستخدام الكلمات المفتاحية [NOT] OVERRIDABLE وسمات XML و/أو خيار التهيئة allow_named_collection_override_by_default.

إذا كان السماح بالتجاوز مفعّلًا، فقد يتمكن المستخدمون الذين لا يملكون وصولًا إداريًا من معرفة بيانات الاعتماد التي تحاول إخفاءها. إذا كنت تستخدم المجموعات المسماة لهذا الغرض، فينبغي عليك تعطيل allow_named_collection_override_by_default (وهو مفعّل افتراضيًا).

​

تخزين المجموعات المسماة في قاعدة بيانات النظام

​

مثال على DDL

CREATE NAMED COLLECTION name AS
key_1 = 'value' OVERRIDABLE,
key_2 = 'value2' NOT OVERRIDABLE,
url = 'https://connection.url/'

في المثال أعلاه:

• يمكن دائمًا استبدال قيمة key_1.
• لا يمكن أبدًا استبدال قيمة key_2.
• يمكن استبدال قيمة url أو عدم استبدالها بحسب قيمة allow_named_collection_override_by_default.

​

الأذونات اللازمة لإنشاء المجموعات المسماة باستخدام DDL

لإدارة المجموعات المسماة باستخدام DDL، يجب أن يمتلك المستخدم امتياز named_collection_control. ويمكن تعيين ذلك بإضافة ملف إلى /etc/clickhouse-server/users.d/. ويوضح المثال منح المستخدم default امتيازي access_management وnamed_collection_control:

/etc/clickhouse-server/users.d/user_default.xml

<clickhouse>
  <users>
    <default>
      <password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex replace=true>
      <access_management>1</access_management>
      <named_collection_control>1</named_collection_control>
    </default>
  </users>
</clickhouse>

في المثال أعلاه، تمثّل قيمة password_sha256_hex القيمة السداسية العشرية لـ SHA256 hash لكلمة المرور. تحتوي تهيئة المستخدم default هذه على attribute ‏replace=true، لأن التهيئة الافتراضية تتضمن password بنص عادي، ولا يمكن تعيين كلمة مرور بنص عادي وكلمة مرور بتنسيق sha256 hex للمستخدم نفسه في الوقت ذاته.

​

تخزين المجموعات المُسمّاة

يمكن تخزين المجموعات المُسمّاة إما على القرص المحلي أو في ZooKeeper/Keeper. ويُستخدم التخزين المحلي افتراضيًا. كما يمكن تخزينها باستخدام التشفير، بالخوارزميات نفسها المستخدمة في تشفير القرص، حيث يُستخدم aes_128_ctr افتراضيًا.

لتهيئة تخزين المجموعات المُسمّاة، تحتاج إلى تحديد type. ويمكن أن تكون هذه القيمة إما local أو keeper/zookeeper. أما في حالة التخزين المشفّر، فيمكنك استخدام local_encrypted أو keeper_encrypted/zookeeper_encrypted.

لاستخدام ZooKeeper/Keeper، نحتاج أيضًا إلى إعداد path (المسار في ZooKeeper/Keeper الذي ستُخزَّن فيه المجموعات المُسمّاة) ضمن قسم named_collections_storage في ملف الإعدادات. يستخدم المثال التالي التشفير وZooKeeper/Keeper:

<clickhouse>
  <named_collections_storage>
    <type>zookeeper_encrypted</type>
    <key_hex>bebec0cabebec0cabebec0cabebec0ca</key_hex>
    <algorithm>aes_128_ctr</algorithm>
    <path>/named_collections_path/</path>
    <update_timeout_ms>1000</update_timeout_ms>
  </named_collections_storage>
</clickhouse>

القيمة الافتراضية لمَعلمة التهيئة الاختيارية update_timeout_ms هي 5000.

​

تخزين المجموعات المسماة في ملفات التهيئة

​

مثال بتنسيق XML

/etc/clickhouse-server/config.d/named_collections.xml

<clickhouse>
     <named_collections>
        <name>
            <key_1 overridable="true">value</key_1>
            <key_2 overridable="false">value_2</key_2>
            <url>https://connection.url/</url>
        </name>
     </named_collections>
</clickhouse>

في المثال أعلاه:

• يمكن دائمًا إعادة تعريف key_1.
• لا يمكن مطلقًا إعادة تعريف key_2.
• يمكن إعادة تعريف url أو عدم إعادة تعريفه بحسب قيمة allow_named_collection_override_by_default.

​

تعديل المجموعات المسماة

يمكن تعديل المجموعات المسماة المُنشأة باستعلامات DDL أو إسقاطها باستخدام DDL. أما المجموعات المسماة المُنشأة بملفات XML، فيمكن إدارتها عبر تحرير ملف XML المقابل أو حذفه.

​

تعديل مجموعة مسماة مُعرَّفة بـ DDL

غيّر أو أضف المفتاحين key1 وkey3 في المجموعة collection2 (لن يؤدّي هذا إلى تغيير قيمة العلامة overridable لهذين المفتاحين):

ALTER NAMED COLLECTION collection2 SET key1=4, key3='value3'

غيّر المفتاح key1 أو أضِفه، واسمح دائمًا باستبداله:

ALTER NAMED COLLECTION collection2 SET key1=4 OVERRIDABLE

احذف المفتاح key2 من collection2:

ALTER NAMED COLLECTION collection2 DELETE key2

غيّر المفتاح key1 أو أضِفه، واحذف المفتاح key3 في المجموعة collection2:

ALTER NAMED COLLECTION collection2 SET key1=4, DELETE key3

لفرض استخدام مفتاحٍ ما للإعدادات الافتراضية الخاصة بالعلامة overridable، عليك إزالة المفتاح ثم إعادة إضافته.

ALTER NAMED COLLECTION collection2 DELETE key1;
ALTER NAMED COLLECTION collection2 SET key1=4;

​

احذف المجموعة المُسمّاة لـ DDL collection2:

DROP NAMED COLLECTION collection2

​

المجموعات المسماة للوصول إلى S3

للاطلاع على وصف المعلمات، راجع الدالة الجدولية S3.

​

مثال على DDL

CREATE NAMED COLLECTION s3_mydata AS
access_key_id = 'AKIAIOSFODNN7EXAMPLE',
secret_access_key = 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
format = 'CSV',
url = 'https://s3.us-east-1.amazonaws.com/yourbucket/mydata/'

​

مثال بتنسيق XML

<clickhouse>
    <named_collections>
        <s3_mydata>
            <access_key_id>AKIAIOSFODNN7EXAMPLE</access_key_id>
            <secret_access_key>wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY</secret_access_key>
            <format>CSV</format>
            <url>https://s3.us-east-1.amazonaws.com/yourbucket/mydata/</url>
        </s3_mydata>
    </named_collections>
</clickhouse>

​

أمثلة على الدالة s3() والمجموعة المسماة لجدول S3

يستخدم كلٌّ من المثالين التاليين المجموعة المسماة نفسها s3_mydata:

​

الدالة s3()

INSERT INTO FUNCTION s3(s3_mydata, filename = 'test_file.tsv.gz',
   format = 'TSV', structure = 'number UInt64', compression_method = 'gzip')
SELECT * FROM numbers(10000);

الوسيطة الأولى للدالة s3() أعلاه هي اسم المجموعة المسماة، s3_mydata. ومن دون المجموعات المسماة، سيتعيّن تمرير معرّف مفتاح الوصول والمفتاح السري والتنسيق وURL في كل استدعاء للدالة s3().

​

جدول S3

CREATE TABLE s3_engine_table (number Int64)
ENGINE=S3(s3_mydata, url='https://s3.us-east-1.amazonaws.com/yourbucket/mydata/test_file.tsv.gz', format = 'TSV')
SETTINGS input_format_with_names_use_header = 0;

SELECT * FROM s3_engine_table LIMIT 3;
┌─number─┐
│      0 │
│      1 │
│      2 │
└────────┘

​

المجموعات المسماة للوصول إلى قاعدة بيانات MySQL

للاطلاع على وصف المعلمات، راجع mysql.

​

مثال على DDL

CREATE NAMED COLLECTION mymysql AS
user = 'myuser',
password = 'mypass',
host = '127.0.0.1',
port = 3306,
database = 'test',
connection_pool_size = 8,
replace_query = 1

​

مثال بتنسيق XML

<clickhouse>
    <named_collections>
        <mymysql>
            <user>myuser</user>
            <password>mypass</password>
            <host>127.0.0.1</host>
            <port>3306</port>
            <database>test</database>
            <connection_pool_size>8</connection_pool_size>
            <replace_query>1</replace_query>
        </mymysql>
    </named_collections>
</clickhouse>

​

أمثلة على المجموعة المسماة الخاصة بـ قاموس والدالة mysql() وجدول MySQL وقاعدة بيانات MySQL

تستخدم الأمثلة الأربعة التالية المجموعة المسماة نفسها mymysql:

​

دالة mysql()

SELECT count() FROM mysql(mymysql, table = 'test');

┌─count()─┐
│       3 │
└─────────┘

لا تتضمن المجموعة المسماة المَعلمة table، لذا جرى تحديدها في استدعاء الدالة بالشكل table = 'test'.

​

جدول MySQL

CREATE TABLE mytable(A Int64) ENGINE = MySQL(mymysql, table = 'test', connection_pool_size=3, replace_query=0);
SELECT count() FROM mytable;

┌─count()─┐
│       3 │
└─────────┘

تتجاوز عبارة DDL إعداد connection_pool_size المحدد في المجموعة المسماة.

​

قاعدة بيانات MySQL

CREATE DATABASE mydatabase ENGINE = MySQL(mymysql);

SHOW TABLES FROM mydatabase;

┌─name───┐
│ source │
│ test   │
└────────┘

​

قاموس MySQL

CREATE DICTIONARY dict (A Int64, B String)
PRIMARY KEY A
SOURCE(MYSQL(NAME mymysql TABLE 'source'))
LIFETIME(MIN 1 MAX 2)
LAYOUT(HASHED());

SELECT dictGet('dict', 'B', 2);

┌─dictGet('dict', 'B', 2)─┐
│ two                     │
└─────────────────────────┘

​

المجموعات المسماة للوصول إلى قاعدة بيانات PostgreSQL

للاطلاع على وصف المعلمات، راجع postgresql. بالإضافة إلى ذلك، تتوفر الأسماء المستعارة التالية:

• username بدلًا من user
• db بدلًا من database.

تُستخدم المعلمة addresses_expr في المجموعة بدلًا من host:port. وهذه المعلمة اختيارية، لأن هناك معلمات اختيارية أخرى، وهي: host وhostname وport. توضّح الشيفرة الزائفة التالية ترتيب الأولوية:

CASE
    WHEN collection['addresses_expr'] != '' THEN collection['addresses_expr']
    WHEN collection['host'] != ''           THEN collection['host'] || ':' || if(collection['port'] != '', collection['port'], '5432')
    WHEN collection['hostname'] != ''       THEN collection['hostname'] || ':' || if(collection['port'] != '', collection['port'], '5432')
END

مثال على عملية الإنشاء:

CREATE NAMED COLLECTION mypg AS
user = 'pguser',
password = 'jw8s0F4',
host = '127.0.0.1',
port = 5432,
database = 'test',
schema = 'test_schema'

مثال على التهيئة:

<clickhouse>
    <named_collections>
        <mypg>
            <user>pguser</user>
            <password>jw8s0F4</password>
            <host>127.0.0.1</host>
            <port>5432</port>
            <database>test</database>
            <schema>test_schema</schema>
        </mypg>
    </named_collections>
</clickhouse>

​

مثال على استخدام المجموعات المُسمّاة مع الدالة postgresql

SELECT * FROM postgresql(mypg, table = 'test');

┌─a─┬─b───┐
│ 2 │ two │
│ 1 │ one │
└───┴─────┘
SELECT * FROM postgresql(mypg, table = 'test', schema = 'public');

┌─a─┐
│ 1 │
│ 2 │
│ 3 │
└───┘

​

مثال على استخدام المجموعات المُسمّاة مع قاعدة بيانات تعمل بمحرك PostgreSQL

CREATE TABLE mypgtable (a Int64) ENGINE = PostgreSQL(mypg, table = 'test', schema = 'public');

SELECT * FROM mypgtable;

┌─a─┐
│ 1 │
│ 2 │
│ 3 │
└───┘

ينسخ PostgreSQL البيانات من المجموعة المُسمّاة عند إنشاء الجدول. وأي تغيير يطرأ على المجموعة لا يؤثر في الجداول الحالية.

​

مثال على استخدام المجموعات المسماة مع قاعدة بيانات تستخدم محرك PostgreSQL

CREATE DATABASE mydatabase ENGINE = PostgreSQL(mypg);

SHOW TABLES FROM mydatabase

┌─name─┐
│ test │
└──────┘

​

مثال على استخدام المجموعات المسماة مع قاموس مصدره POSTGRESQL

CREATE DICTIONARY dict (a Int64, b String)
PRIMARY KEY a
SOURCE(POSTGRESQL(NAME mypg TABLE test))
LIFETIME(MIN 1 MAX 2)
LAYOUT(HASHED());

SELECT dictGet('dict', 'b', 2);

┌─dictGet('dict', 'b', 2)─┐
│ two                     │
└─────────────────────────┘

​

المجموعات المسماة للوصول إلى قاعدة بيانات ClickHouse بعيدة

للاطلاع على وصف المعلمات، راجع remote.

مثال على التهيئة:

CREATE NAMED COLLECTION remote1 AS
host = 'remote_host',
port = 9000,
database = 'system',
user = 'foo',
password = 'secret',
secure = 1

<clickhouse>
    <named_collections>
        <remote1>
            <host>remote_host</host>
            <port>9000</port>
            <database>system</database>
            <user>foo</user>
            <password>secret</password>
            <secure>1</secure>
        </remote1>
    </named_collections>
</clickhouse>

secure غير ضروري للاتصال بسبب remoteSecure، لكن يمكن استخدامه مع القواميس.

​

مثال على استخدام المجموعات المُسمّاة مع الدالتين remote/remoteSecure

SELECT * FROM remote(remote1, table = one);
┌─dummy─┐
│     0 │
└───────┘

SELECT * FROM remote(remote1, database = merge(system, '^one'));
┌─dummy─┐
│     0 │
└───────┘

INSERT INTO FUNCTION remote(remote1, database = default, table = test) VALUES (1,'a');

SELECT * FROM remote(remote1, database = default, table = test);
┌─a─┬─b─┐
│ 1 │ a │
└───┴───┘

​

مثال على استخدام المجموعات المسماة مع قاموس مصدره ClickHouse

CREATE DICTIONARY dict(a Int64, b String)
PRIMARY KEY a
SOURCE(CLICKHOUSE(NAME remote1 TABLE test DB default))
LIFETIME(MIN 1 MAX 2)
LAYOUT(HASHED());

SELECT dictGet('dict', 'b', 1);
┌─dictGet('dict', 'b', 1)─┐
│ a                       │
└─────────────────────────┘

​

المجموعات المسماة للوصول إلى Kafka

راجع وصف المعلمات في Kafka.

​

مثال على DDL

CREATE NAMED COLLECTION my_kafka_cluster AS
kafka_broker_list = 'localhost:9092',
kafka_topic_list = 'kafka_topic',
kafka_group_name = 'consumer_group',
kafka_format = 'JSONEachRow',
kafka_max_block_size = '1048576';

​

مثال بتنسيق XML

<clickhouse>
    <named_collections>
        <my_kafka_cluster>
            <kafka_broker_list>localhost:9092</kafka_broker_list>
            <kafka_topic_list>kafka_topic</kafka_topic_list>
            <kafka_group_name>consumer_group</kafka_group_name>
            <kafka_format>JSONEachRow</kafka_format>
            <kafka_max_block_size>1048576</kafka_max_block_size>
        </my_kafka_cluster>
    </named_collections>
</clickhouse>

​

مثال على استخدام المجموعات المسماة مع جدول Kafka

يستخدم المثالان التاليان المجموعة المسماة نفسها my_kafka_cluster:

CREATE TABLE queue
(
    timestamp UInt64,
    level String,
    message String
)
ENGINE = Kafka(my_kafka_cluster)

CREATE TABLE queue
(
    timestamp UInt64,
    level String,
    message String
)
ENGINE = Kafka(my_kafka_cluster)
SETTINGS kafka_num_consumers = 4,
         kafka_thread_per_consumer = 1;

​

المجموعات المسماة الخاصة بالنسخ الاحتياطية

للاطلاع على وصف المعلمات، راجع النسخ الاحتياطي والاستعادة.

​

مثال على DDL

BACKUP TABLE default.test to S3(named_collection_s3_backups, 'directory')

​

مثال بتنسيق XML

<clickhouse>
    <named_collections>
        <named_collection_s3_backups>
            <url>https://my-s3-bucket.s3.amazonaws.com/backup-S3/</url>
            <access_key_id>ABC123</access_key_id>
            <secret_access_key>Abc+123</secret_access_key>
        </named_collection_s3_backups>
    </named_collections>
</clickhouse>

​

المجموعات المسماة للوصول إلى جدول MongoDB والقاموس

للاطلاع على وصف المعلمات، راجع mongodb.

​

مثال على DDL

CREATE NAMED COLLECTION mymongo AS
user = '',
password = '',
host = '127.0.0.1',
port = 27017,
database = 'test',
collection = 'my_collection',
options = 'connectTimeoutMS=10000'

​

مثال بتنسيق XML

<clickhouse>
    <named_collections>
        <mymongo>
            <user></user>
            <password></password>
            <host>127.0.0.1</host>
            <port>27017</port>
            <database>test</database>
            <collection>my_collection</collection>
            <options>connectTimeoutMS=10000</options>
        </mymongo>
    </named_collections>
</clickhouse>

​

جدول MongoDB

CREATE TABLE mytable(log_type VARCHAR, host VARCHAR, command VARCHAR) ENGINE = MongoDB(mymongo, options='connectTimeoutMS=10000&compressors=zstd')
SELECT count() FROM mytable;

┌─count()─┐
│       2 │
└─────────┘

تتجاوز عبارة DDL إعدادات الخيارات المحددة في المجموعة المسماة.

​

قاموس MongoDB

CREATE DICTIONARY dict
(
    `a` Int64,
    `b` String
)
PRIMARY KEY a
SOURCE(MONGODB(NAME mymongo COLLECTION my_dict))
LIFETIME(MIN 1 MAX 2)
LAYOUT(HASHED())

SELECT dictGet('dict', 'b', 2);

┌─dictGet('dict', 'b', 2)─┐
│ two                     │
└─────────────────────────┘

تحدِّد المجموعة المُسمّاة اسم الـ collection على أنه my_collection. وفي استدعاء الدالة، يُتجاوز هذا الإعداد باستخدام collection = 'my_dict' لاختيار collection أخرى.