Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

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

يمكن تجاوز المعلَمات المضبوطة في مجموعة مسماة داخل SQL، وهذا موضح في الأمثلة أدناه. ويمكن تقييد هذه الإمكانية باستخدام الكلمات المفتاحية [NOT] OVERRIDABLE وسمات XML و/أو خيار التهيئة 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.xmlxml
<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>

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

يمكن تخزين المجموعات المُسمّاة إما على القرص المحلي أو في 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.

يمكنك فحص نوع التخزين النشط عبر system.server_settings وgetServerSetting:

SELECT value, getServerSetting('named_collections_storage_type')
FROM system.server_settings
WHERE name = 'named_collections_storage.type';

يتطلب تغيير نوع التخزين إعادة تشغيل الخادم؛ ولا يغيّر SYSTEM RELOAD CONFIG الواجهة الخلفية النشطة.

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

مثال بتنسيق XML

/etc/clickhouse-server/config.d/named_collections.xmlxml
<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

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;
┌

المجموعات المسماة للوصول إلى قاعدة بيانات 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');

┌

جدول MySQL

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

┌

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

CREATE DATABASE mydatabase ENGINE = MySQL(mymysql);

SHOW TABLES FROM mydatabase;

┌

قاموس 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);

┌

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

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

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

يمكن أيضًا تخزين إعدادات تجمّع الاتصالات الخاصة بـ PostgreSQL table engine (postgresql_connection_pool_size وإعدادات postgresql_* الأخرى) في المجموعة أو تمريرها كتجاوزات بصيغة key = value. وهي تنطبق على محرك الجدول PostgreSQL، والدالة الجدولية postgresql، ومحرك قاعدة البيانات PostgreSQL؛ وتكون لعبارة SETTINGS الصريحة على الجدول أولوية على القيم الواردة من المجموعة.

تُستخدم المعلمة 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');

┌

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

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

SELECT * FROM mypgtable;

┌

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

CREATE DATABASE mydatabase ENGINE = PostgreSQL(mypg);

SHOW TABLES FROM mydatabase

┌

مثال على استخدام المجموعات المسماة مع قاموس مصدره 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);

┌

المجموعات المسماة للوصول إلى قاعدة بيانات 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);
┌

مثال على استخدام المجموعات المسماة مع قاموس مصدره 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);
┌

المجموعات المسماة للوصول إلى 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;

┌

قاموس 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);

┌
Navigation