البحث النصي الكامل باستخدام الفهارس النصية

تتيح الفهارس النصية (المعروفة أيضًا باسم الفهارس المعكوسة) إجراء بحث نصي كامل سريع في البيانات النصية. يخزن الفهرس النصي تعيينًا من الرموز إلى أرقام الصفوف التي تحتوي على كل رمز. وتُنشأ الرموز عبر عملية تُسمى تقسيم النص إلى رموز. على سبيل المثال، يحوّل مُجزِّئ النص الافتراضي في ClickHouse الجملة الإنجليزية “The cat likes mice.” إلى الرموز [“The”, “cat”, “likes”, “mice”]. على سبيل المثال، افترض وجود جدول يحتوي على عمود واحد وثلاثة صفوف

The cat likes mice.
Mice are afraid of dogs.
I have two dogs and a cat.

التوكنات المقابلة هي:

The, cat, likes, mice
Mice, are, afraid, of, dogs
I, have, two, dogs, and, a, cat

عادةً ما نفضّل البحث بغضّ النظر عن حالة الأحرف، لذلك نحوّل التوكنات إلى أحرف صغيرة:

the, cat, likes, mice
mice, are, afraid, of, dogs
i, have, two, dogs, and, a, cat

سنزيل أيضًا كلمات الحشو مثل “I” و”the” و”and” لأنها تتكرر في كل صف تقريبًا:

cat, likes, mice
mice, afraid, dogs
have, two, dogs, cat

وعليه، يحتوي الفهرس النصي (من حيث التصور) على المعلومات التالية:

afraid : [2]
cat    : [1, 3]
dogs   : [2, 3]
have   : [3]
likes  : [1]
mice   : [1]
two    : [3]

عند توفير رمز بحث، تتيح بنية الفهرس هذه العثور بسرعة على جميع الصفوف المطابقة.

إنشاء فهرس نصي

أصبحت الفهارس النصية متاحةً بشكل عام (GA) في ClickHouse الإصدار 26.2 والإصدارات الأحدث. في هذه الإصدارات، لا حاجة إلى تهيئة أي إعدادات خاصة لاستخدام الفهرس النصي. نوصي بشدة باستخدام إصدارات ClickHouse ‏>= 26.2 في بيئات الإنتاج.

يمكن استخدام الفهارس النصية مع أي إصدار من ClickHouse ‏>= 26.2، بغض النظر عن إعداد التوافق.

لإنشاء فهرس نصي، استخدم الصياغة التالية:

Query

CREATE TABLE table
(
    key UInt64,
    str String,
    INDEX text_idx str TYPE text(
                                -- Mandatory parameters:
                                tokenizer = splitByNonAlpha
                                            | splitByString[(S)]
                                            | asciiCJK
                                            | ngrams[(N)]
                                            | sparseGrams[(min_length[, max_length[, min_cutoff_length]])]
                                            | array
                                -- Optional parameters:
                                [, preprocessor = expression(str)]
                                -- Optional advanced parameters:
                                [, dictionary_block_size = D]
                                [, dictionary_block_frontcoding_compression = B]
                                [, posting_list_block_size = C]
                                [, posting_list_codec = 'none' | 'bitpacking' ]
                            )
)
ENGINE = MergeTree
ORDER BY key

يمكن تعريف الفهارس النصية على أعمدة من الأنواع التالية:

String وFixedString،
Array(String) وArray(FixedString)،
Map (باستخدام الدالتين mapKeys وmapValues)، و
JSON (باستخدام الدالتين JSONAllPaths وJSONAllValues).

كما أن الأعمدة من النوع Nullable(T) وLowCardinality() مدعومة أيضًا، بما في ذلك Array(Nullable(String or FixedString)). بدلًا من ذلك، لإضافة فهرس نصي إلى جدول موجود:

Query

ALTER TABLE table
    ADD INDEX text_idx str TYPE text(
                                -- Mandatory parameters:
                                tokenizer = splitByNonAlpha
                                            | splitByString[(S)]
                                            | asciiCJK
                                            | ngrams[(N)]
                                            | sparseGrams[(min_length[, max_length[, min_cutoff_length]])]
                                            | array
                                -- Optional parameters:
                                [, preprocessor = expression(str)]
                                -- Optional advanced parameters:
                                [, dictionary_block_size = D]
                                [, dictionary_block_frontcoding_compression = B]
                                [, posting_list_block_size = C]
                                [, posting_list_codec = 'none' | 'bitpacking' ]
                            )

إذا أضفت فهرسًا إلى جدول موجود، فنوصي بإنشاء الفهرس فعليًا لأجزاء الجدول الحالية (وإلا فسيعتمد البحث في الأجزاء التي لا تحتوي على فهرس على عمليات مسح شاملة بطيئة).

Query

ALTER TABLE table MATERIALIZE INDEX text_idx SETTINGS mutations_sync = 2;

لإزالة فهرس نصي، يُرجى تنفيذ

Query

ALTER TABLE table DROP INDEX text_idx;

الوسيطة tokenizer (إلزامية). تحدد الوسيطة tokenizer المُجزِّئ:

splitByNonAlpha يقسم السلاسل النصية عند محارف ASCII غير الأبجدية الرقمية (راجع الدالة splitByNonAlpha).
splitByString(S) يقسم السلاسل النصية باستخدام سلاسل فاصلة S يحددها المستخدم (راجع الدالة splitByString). يمكن تحديد الفواصل باستخدام معلمة اختيارية، على سبيل المثال: tokenizer = splitByString([', ', '; ', '\n', '\\']). لاحظ أن كل سلسلة يمكن أن تتكون من عدة محارف (', ' في المثال). قائمة الفواصل الافتراضية، إذا لم تُحدَّد صراحةً (على سبيل المثال: tokenizer = splitByString)، هي مسافة بيضاء واحدة [' '].
asciiCJK يقسم السلاسل النصية إلى رموز وفقًا لقواعد حدود الكلمات في Unicode (على غرار Unicode Text Segmentation (UAX #29)). وتُشكِّل محارف ASCII الأبجدية الرقمية والشرطات السفلية رموزًا مع الموصلات (ASCII : للحروف، و. و' للمحارف من النوع نفسه). أما محارف Unicode غير التابعة لـ ASCII، بما في ذلك محارف CJK، فتصبح رموزًا من محرف واحد.
ngrams(N) يقسم السلاسل النصية إلى n-grams متساوية الحجم بطول N (راجع الدالة ngrams). يمكن تحديد طول ngram باستخدام معلمة عدد صحيح اختيارية بين 1 و8، على سبيل المثال: tokenizer = ngrams(3). حجم ngram الافتراضي، إذا لم يُحدَّد صراحةً (على سبيل المثال: tokenizer = ngrams)، هو 3.
sparseGrams(min_length, max_length, min_cutoff_length) يقسم السلاسل النصية إلى n-grams متغيرة الطول، بحيث لا يقل طولها عن min_length ولا يزيد على max_length (شاملًا) من المحارف (راجع الدالة sparseGrams). ما لم يُحدَّد ذلك صراحةً، تكون القيم الافتراضية لـ min_length وmax_length هي 3 و100. إذا تم توفير المعلمة min_cutoff_length، فلن تُعاد إلا n-grams التي يكون طولها أكبر من أو مساويًا لـ min_cutoff_length. مقارنةً بـ ngrams(N)، يُنتج المُجزِّئ sparseGrams ‏N-grams متغيرة الطول، مما يتيح تمثيلًا أكثر مرونة للنص الأصلي. على سبيل المثال، tokenizer = sparseGrams(3, 5, 4) يُنشئ داخليًا 3- و4- و5-grams من سلسلة الإدخال، لكن لا تُعاد إلا 4- و5-grams.
array لا يُجري أي تجزئة، أي إن كل قيمة في row هي رمز (راجع الدالة array).

جميع المُجزِّئات المتاحة مُدرجة في system.tokenizers.

يطبّق المُجزِّئ splitByString فواصل التقسيم من اليسار إلى اليمين. وقد يؤدي ذلك إلى حدوث حالات التباس. على سبيل المثال، ستؤدي سلاسل الفواصل ['%21', '%'] إلى تجزئة %21abc على هيئة ['abc']، بينما سيؤدي تبديل ترتيب سلسلتي الفواصل إلى ['%', '%21'] إلى إخراج ['21abc']. في معظم الحالات، ستحتاج إلى أن تُفضِّل المطابقة الفواصل الأطول أولًا. ويمكن تحقيق ذلك عمومًا عبر تمرير سلاسل الفواصل بترتيب تنازلي حسب الطول. وإذا كانت سلاسل الفواصل تُشكّل prefix code، فيمكن تمريرها بأي ترتيب.

لفهم كيفية قيام المُجزِّئ بتقسيم سلسلة الإدخال، يمكنك استخدام الدالتين tokens وtokensForLikePattern: مثال:

Query

SELECT tokens('abc def', 'ngrams', 3);

Response

['abc','bc ','c d',' de','def']

العمل مع مدخلات غير ASCII. يمكن إنشاء فهرس نصي على بيانات نصية بأي لغة وبأي مجموعة محارف. بالنسبة إلى النصوص غير ASCII، يُوصى باستخدام المُجزِّئ asciiCJK لأنه يتعامل بشكل صحيح مع حدود الكلمات في Unicode، بما في ذلك محارف CJK. ::: وسيطة المعالج المسبق (اختيارية). يشير المعالج المسبق إلى تعبير يُطبَّق على سلسلة الإدخال قبل تقسيمها إلى رموز. تشمل حالات الاستخدام الشائعة لوسيطة المعالج المسبق

تحويل الأحرف إلى صغيرة/كبيرة، أو طيّ الحالة لتمكين المطابقة غير الحساسة لحالة الأحرف، مثل lower، lowerUTF8، caseFoldUTF8.
تطبيع UTF-8، مثل normalizeUTF8NFC، normalizeUTF8NFD، normalizeUTF8NFKC، normalizeUTF8NFKD، normalizeUTF8NFKCCasefold، toValidUTF8.
إزالة المحارف أو السلاسل الفرعية غير المرغوب فيها أو تحويلها، مثل علامات التشكيل، مثل extractTextFromHTML، substring، idnaEncode، translate، removeDiacriticsUTF8.

يجب أن يحوّل تعبير المعالج المسبق قيمة إدخال من النوع String أو FixedString إلى قيمة من النوع نفسه. إذا كان الفهرس النصي مبنيًا على عمود من النوع Nullable(T) أو LowCardinality(T)، فيجب أن يقبل تعبير المعالج المسبق القيم القابلة للإبطال أو منخفضة الكاردينالية (أي ألّا يطرح استثناءً). أمثلة:

INDEX idx col TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = lower(col))
INDEX idx col TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = substringIndex(col, '\n', 1))
INDEX idx col TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = lower(extractTextFromHTML(col)))
INDEX idx col TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = removeDiacriticsUTF8(caseFoldUTF8(col)))

كذلك، يجب ألا يشير تعبير المعالج المسبق إلا إلى العمود أو التعبير المعرَّف فوقه الفهرس النصي. أمثلة:

INDEX idx lower(col) TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = upper(lower(col)))
INDEX idx lower(col) TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = concat(lower(col), lower(col)))
غير مسموح: INDEX idx lower(col) TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = concat(col, col))

يُحظر استخدام الدوال غير الحتمية.

المعالجات المسبقة، من حيث المبدأ، تكافئ تغليف عمود الفهرس أو التعبير بتعبير المعالج المسبق. على سبيل المثال، يمكن محاكاة المعالج المسبق lower في INDEX idx col TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = lower(col)) باستخدام INDEX idx lower(col) TYPE text(tokenizer = 'splitByNonAlpha'). وعيب الصيغة الأخيرة هو أن المعالج المسبق المُحاكى لا يُطبَّق إلا إذا طابق شرط التصفية في بند WHERE. على سبيل المثال، يطابق WHERE hasAllTokens(lower(col), [...]) بينما لا يطابق WHERE hasAllTokens(col, [...]). لذلك، ولأفضل تجربة استخدام، نوصي باستخدام تعبيرات المعالج المسبق.

تستخدم الدوال hasToken، وhasAllTokens، وhasAnyTokens، وhasPhrase المعالج المسبق لتحويل مصطلح البحث أولًا قبل تقسيمه إلى رموز. لاحظ أنه نظرًا إلى أن المعالج المسبق لا يُطبَّق إلا على مسار الفهرس النصي، فقد تختلف نتائج هذه الدوال بين الاستعلامات التي تستخدم الفهرس النصي والاستعلامات التي لا تستخدمه (مثل SETTINGS use_skip_indexes = 0). على سبيل المثال،

Query

CREATE TABLE table
(
    str String,
    INDEX idx str TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = lower(str))
)
ENGINE = MergeTree
ORDER BY tuple();

SELECT count() FROM table WHERE hasToken(str, 'Foo');

يعادل ما يلي:

Query

CREATE TABLE table
(
    str String,
    INDEX idx lower(str) TYPE text(tokenizer = 'splitByNonAlpha')
)
ENGINE = MergeTree
ORDER BY tuple();

SELECT count() FROM table WHERE hasToken(str, lower('Foo'));

في هذه الحالة، يُحوِّل تعبير المعالجة المسبقة عناصر المصفوفة، كل عنصر على حدة. مثال:

Query

CREATE TABLE table
(
    arr Array(String),
    INDEX idx arr TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = lower(arr))

    -- This is not legal:
    INDEX idx_illegal arr TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = arraySort(arr))
)
ENGINE = MergeTree
ORDER BY tuple();

SELECT count() FROM tab WHERE hasAllTokens(arr, 'foo');

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

Query

CREATE TABLE table
(
    map Map(String, String),
    INDEX idx mapKeys(map)  TYPE text(tokenizer = 'splitByNonAlpha', preprocessor = lower(mapKeys(map)))
)
ENGINE = MergeTree
ORDER BY tuple();

SELECT count() FROM tab WHERE hasAllTokens(mapKeys(map), 'foo');

وسائط أخرى (اختيارية). حبيبية الفهرس. تُنفَّذ الفهارس النصية داخل ClickHouse كنوع من فهارس التخطي. ومع ذلك، وعلى خلاف فهارس التخطي الأخرى، تستخدم الفهارس النصية حبيبية لا نهائية (100 مليون). ويمكن ملاحظة ذلك في تعريف جدول الفهرس النصي. مثال:

Query

CREATE TABLE table(
    k UInt64,
    s String,
    INDEX idx s TYPE text(tokenizer = ngrams(2)))
ENGINE = MergeTree()
ORDER BY k;

SHOW CREATE TABLE table;

Response

┌─statement──────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.table                                            ↴│
│↳(                                                                     ↴│
│↳    `k` UInt64,                                                       ↴│
│↳    `s` String,                                                       ↴│
│↳    INDEX idx s TYPE text(tokenizer = ngrams(2)) GRANULARITY 100000000↴│ <-- here
│↳)                                                                     ↴│
│↳ENGINE = MergeTree                                                    ↴│
│↳ORDER BY k                                                            ↴│
│↳SETTINGS index_granularity = 8192                                      │
└────────────────────────────────────────────────────────────────────────┘

يضمن الارتفاع الكبير جدًا في حبيبية الفهرس إنشاء فهرس نصي للجزء بالكامل. ويُتجاهل أي حبيبية الفهرس مُحدَّدة صراحةً.

استخدام فهرس نصي

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

نوصي باستخدام الدالتين hasAnyTokens وhasAllTokens للبحث في الفهرس النصي؛ يُرجى الاطلاع على أدناه. تعمل هاتان الدالتان مع جميع المجزئات المتاحة وجميع تعبيرات المعالجة المسبقة الممكنة. ونظرًا إلى أن الدوال المدعومة الأخرى سبقت الفهرس النصي تاريخيًا، فقد كان عليها الاحتفاظ بسلوكها القديم في كثير من الحالات (مثلًا، عدم دعم المعالجة المسبقة).

الدوال المدعومة

يمكن استخدام فهرس نصي إذا استُخدمت دوال النص في بند WHERE أو بنود PREWHERE:

SELECT [...]
FROM [...]
WHERE string_search_function(column_with_text_index)

`=`

= (equals) يطابق مصطلح البحث المعطى بالكامل. مثال:

SELECT * from table WHERE str = 'Hello';

`IN`

IN (in) يشبه equals، لكنه يطابق كل مصطلحات البحث. مثال:

SELECT * from table WHERE str IN ('Hello', 'World');

NOT IN (notIn) غير مدعوم في الفهرس النصي.

`LIKE` and `match`

تستخدم هذه الدوال حاليًا الفهرس النصي للتصفية فقط إذا كان الـ مجزئ في الفهرس هو splitByNonAlpha أو ngrams أو sparseGrams.

لا يدعم الفهرس النصي NOT LIKE (notLike).

لاستخدام LIKE (like) والدالة match مع الفهارس النصية، يجب أن يتمكن ClickHouse من استخراج رموز كاملة من عبارة البحث. وبالنسبة إلى الفهرس الذي يستخدم مجزئ من النوع ngrams، يتحقق ذلك إذا كان طول السلاسل النصية المطلوب البحث عنها بين أحرف البدل مساويًا لطول ngram أو أكبر منه. Example لفهرس نصي يستخدم مجزئ من النوع splitByNonAlpha:

SELECT count() FROM table WHERE comment LIKE 'support%';

يمكن أن يطابق support في المثال كلمات مثل support وsupports وsupporting وغيرها. هذا النوع من الاستعلامات هو استعلام عن سلسلة فرعية، ولا يمكن تسريعه باستخدام فهرس نصي. لاستفادة من فهرس نصي في استعلامات LIKE، يجب إعادة كتابة نمط LIKE على النحو التالي:

SELECT count() FROM table WHERE comment LIKE ' support %'; -- or `% support %`

تضمن المسافات الواقعة إلى يسار support ويمينه إمكانية استخراج هذا المصطلح على أنه رمز. ولحسن الحظ، توجد حالة خاصة يمكن فيها لـ ClickHouse الاستفادة من الفهرس المقلوب لتسريع استعلامات LIKE بشكل كبير. راجع قسم ضبط أداء LIKE/ILIKE لمزيد من التفاصيل.

`multiSearchAny` و `multiMatchAny`

يختبر multiSearchAny وصيغته الخاصة بـ UTF-8، multiSearchAnyUTF8، ما إذا كانت أيٌّ من عدة سلاسل فرعية حرفية تظهر في النص المُراد البحث فيه، بينما يختبر multiMatchAny ما إذا كان أيٌّ من عدة تعبيرات نمطية يطابق. تستخدم هذه الدوال الفهرس النصي بالشروط نفسها التي تستخدمها LIKE و match (انظر أعلاه): يجب أن يتمكن ClickHouse من استخراج رموز كاملة من كل needle، ويجب أن تكون قائمة needles ثابتة. تُقرأ granule إذا كان من المحتمل أن تحتوي على أي needle. بالنسبة إلى multiMatchAny، إذا تعذر اختزال نمط واحد إلى متطلب رمز (على سبيل المثال .*، الذي يطابق أي مستند)، فلن يمكن استخدام الفهرس النصي، وسيرجع الاستعلام إلى فحص كامل. كما هو الحال مع LIKE و match، يعمل البحث بالسلاسل الفرعية والتعبيرات النمطية بأفضل شكل مع مجزئات ngrams و sparseGrams. تفهرس مجزئات النص هذه n-grams متداخلة من الأحرف، لذلك يُحلَّل needle إلى n-grams موجودة في الفهرس أينما ظهر needle كسلسلة فرعية، بغض النظر عمّا إذا كان يبدأ أو ينتهي في منتصف كلمة. وبالتالي يمكن استخدام needle كما هو، ما دام طوله لا يقل عن حجم n-gram. Example للفهرس النصي مع مجزئ ngrams:

SELECT count() FROM table WHERE multiSearchAny(comment, ['clickhouse', 'support']);

وعلى النقيض من ذلك، لا يفهرس المُجزِّئ splitByNonAlpha سوى الرموز الكاملة (أي الكلمات الكاملة). ولأن needle قد يبدأ أو ينتهي في منتصف كلمة، فإن ClickHouse يتجاهل الرمزين الأول والأخير في كل needle، بحيث لا يمكن للفهرس تقليم الحبيبات إلا بالاعتماد على الرموز الكاملة. ولكي يستخدم البحث عن substring والبحث بالتعبيرات النمطية الفهرس مع splitByNonAlpha، أَحِط كل needle بمحارف فاصلة (مثل المسافات) بحيث يُكوِّن رمزًا كاملًا واحدًا أو أكثر. مثال على الفهرس النصي مع المُجزِّئ splitByNonAlpha:

SELECT count() FROM table WHERE multiSearchAny(comment, [' clickhouse ', ' support ']);

`startsWith` and `endsWith`

على غرار LIKE، لا يمكن للدالتين startsWith وendsWith استخدام فهرس نصي إلا إذا أمكن استخراج رموز كاملة من عبارة البحث. وبالنسبة إلى الفهرس الذي يستخدم مجزئ ngrams، يتحقق ذلك إذا كان طول السلاسل النصية المطلوب البحث عنها بين أحرف البدل مساويًا لطول ngram أو أكبر منه. مثال على فهرس نصي يستخدم مجزئ splitByNonAlpha:

SELECT count() FROM table WHERE startsWith(comment, 'clickhouse support');

في هذا المثال، لا يُعدّ clickhouse إلا رمزًا واحدًا. أما support فلا يُعدّ رمزًا لأنه يمكن أن يطابق support وsupports وsupporting وغيرها. للعثور على جميع rows التي تبدأ بـ clickhouse supports، يُرجى إنهاء نمط البحث بمسافة لاحقة:

startsWith(comment, 'clickhouse supports ')`

وبالمثل، ينبغي استخدام endsWith مع مسافة في البداية:

SELECT count() FROM table WHERE endsWith(comment, ' olap engine');

`hasToken` و `hasTokenOrNull`

يبدو استخدام الدالة hasToken بسيطًا، لكنه ينطوي على بعض الجوانب التي قد تُسبب مشكلات عند استخدام مُجزِّئات غير افتراضية وتعبيرات المعالجة المسبقة. نوصي باستخدام الدالتين hasAnyTokens و hasAllTokens بدلًا من ذلك.

تُطابِق الدالتان hasToken و hasTokenOrNull رمزًا واحدًا محددًا. وعلى عكس الدوال المذكورة سابقًا، فإنهما لا تُجزِّئان مصطلح البحث إلى رموز (إذ تفترضان أن المُدخل عبارة عن رمز واحد). مثال:

SELECT count() FROM table WHERE hasToken(comment, 'clickhouse');

`hasAnyTokens` and `hasAllTokens`

تُطابِق الدالتان hasAnyTokens وhasAllTokens أيًّا من الرموز المعطاة أو جميعها. تقبل هاتان الدالتان رموز البحث إما كسلسلة نصية ستُجزَّأ إلى رموز باستخدام نفس المجزئ المستخدم لعمود الفهرس، أو كمصفوفة من الرموز المُعالجة مسبقًا، والتي لن يُجرى عليها أي تقسيم قبل البحث. راجع توثيق الدالة لمزيد من المعلومات. مثال:

-- Search tokens passed as string argument
SELECT count() FROM table WHERE hasAnyTokens(comment, 'clickhouse olap');
SELECT count() FROM table WHERE hasAllTokens(comment, 'clickhouse olap');

-- Search tokens passed as Array(String)
SELECT count() FROM table WHERE hasAnyTokens(comment, ['clickhouse', 'olap']);
SELECT count() FROM table WHERE hasAllTokens(comment, ['clickhouse', 'olap']);

`hasPhrase`

تُطابِق الدالة hasPhrase عبارةً ما: إذ يجب أن تظهر جميع الرموز بشكل متتالٍ وبالترتيب نفسه كما في سلسلة البحث. وعلى خلاف hasAllTokens، التي تشترط فقط وجود جميع الرموز في أي موضع، فإن hasPhrase تشترط أن تظهر كتسلسل متصل. تُجزَّأ عبارة البحث إلى رموز باستخدام المجزئ نفسه المُعدّ لعمود الفهرس. لاحظ أن الدالة تتطلب أحد مجزئات splitByNonAlpha أو splitByString أو ngrams أو asciiCJK. مثال:

-- Matches: 'clickhouse' and 'olap' must appear consecutively in that order
SELECT count() FROM table WHERE hasPhrase(comment, 'clickhouse olap');

-- Does NOT match a row containing 'olap clickhouse' (wrong order)
-- Does NOT match a row containing 'clickhouse fast olap' (non-consecutive)

`has`

تُطابِق دالة المصفوفات has رمز واحدًا ضمن مصفوفة من السلاسل النصية. مثال:

SELECT count() FROM table WHERE has(array, 'clickhouse');

`hasAny` و `hasAll`

تتحقق دوال المصفوفات hasAny و hasAll مما إذا كان عمود المصفوفة المفهرس يحتوي على أيٍّ من مجموعة ثابتة من سلاسل البحث أو عليها كلها. مثال:

SELECT count() FROM table WHERE hasAny(tags, ['clickhouse', 'olap']);
SELECT count() FROM table WHERE hasAll(tags, ['clickhouse', 'olap']);

`mapContains`

تُطابِق الدالة mapContains (وهي alias لـ mapContainsKey) مع الرموز المستخرجة من السلسلة النصية المطلوب البحث فيها ضمن مفاتيح الـ map. ويشبه هذا السلوك الدالة equals مع عمود String. ولا يُستخدَم فهرس نصي إلا إذا كان قد أُنشئ على expression ‏mapKeys(map). Example:

SELECT count() FROM table WHERE mapContainsKey(map, 'clickhouse');
-- OR
SELECT count() FROM table WHERE mapContains(map, 'clickhouse');

`mapContainsValue`

تُطابِق الدالة mapContainsValue الرموز المميزة المستخرجة من السلسلة النصية المطلوب البحث فيها داخل قيم map. ويشبه سلوكها سلوك الدالة equals مع عمود String. ولا يُستخدم الفهرس النصي إلا إذا كان قد أُنشئ على التعبير mapValues(map). مثال:

SELECT count() FROM table WHERE mapContainsValue(map, 'clickhouse');

`mapContainsKeyLike` و `mapContainsValueLike`

تُطابِق الدالتان mapContainsKeyLike و mapContainsValueLike نمطًا مع جميع مفاتيح Map أو قيمه (على الترتيب). مثال:

SELECT count() FROM table WHERE mapContainsKeyLike(map, '% clickhouse %');
SELECT count() FROM table WHERE mapContainsValueLike(map, '% clickhouse %');

`operator[]`

يمكن استخدام عامل الوصول operator[] مع الفهرس النصي لتصفية المفاتيح والقيم. ولا يُستخدم الفهرس النصي إلا إذا أُنشئ على التعبيرين mapKeys(map) أو mapValues(map)، أو كليهما. مثال:

SELECT count() FROM table WHERE map['engine'] = 'clickhouse';

راجع الأمثلة التالية لاستخدام الأعمدة من النوع Array(T) وMap(K, V) مع الفهرس النصي.

فهرسة أعمدة Array(String)

تخيّل منصة تدوين، يصنّف فيها الكتّاب تدويناتهم باستخدام الكلمات المفتاحية. ونريد أن يتمكّن المستخدمون من اكتشاف المحتوى ذي الصلة عبر البحث عن الموضوعات أو النقر عليها. ضع في اعتبارك تعريف الجدول التالي:

CREATE TABLE posts
(
    post_id UInt64,
    title String,
    content String,
    keywords Array(String)
)
ENGINE = MergeTree
ORDER BY (post_id);

بدون فهرس نصّي، يتطلّب العثور على منشورات تتضمن كلمة محددة (مثل clickhouse) فحص جميع السجلات:

SELECT count() FROM posts WHERE has(keywords, 'clickhouse'); -- slow full-table scan - checks every keyword in every post

مع توسّع المنصة، يصبح هذا أبطأ تدريجيًا لأن الاستعلام يجب أن يفحص كل مصفوفة keywords في كل صف. للتغلّب على مشكلة الأداء هذه، نُعرّف فهرسًا نصيًا للعمود keywords:

ALTER TABLE posts ADD INDEX keywords_idx(keywords) TYPE text(tokenizer = splitByNonAlpha);
ALTER TABLE posts MATERIALIZE INDEX keywords_idx; -- Don't forget to rebuild the index for existing data

فهرسة أعمدة Map

في العديد من حالات استخدام observability، تُقسَّم رسائل السجل إلى “مكوّنات” وتُخزَّن باستخدام أنواع البيانات المناسبة، مثلًا التاريخ والوقت للطابع الزمني، وenum لمستوى السجل، وما إلى ذلك. من الأفضل تخزين حقول المقاييس كأزواج مفتاح-قيمة. تحتاج فرق العمليات إلى البحث بكفاءة في السجلات لأغراض استكشاف الأخطاء وإصلاحها، والحوادث الأمنية، والمراقبة. خذ جدول السجلات هذا على سبيل المثال:

CREATE TABLE logs
(
    id UInt64,
    timestamp DateTime,
    message String,
    attributes Map(String, String)
)
ENGINE = MergeTree
ORDER BY (timestamp);

من دون فهرس نصي، يتطلب البحث في بيانات Map إجراء مسح كامل للجدول:

-- Finds all logs with rate limiting data:
SELECT * FROM logs WHERE has(mapKeys(attributes), 'rate_limit'); -- slow full-table scan

-- Finds all logs from a specific IP:
SELECT * FROM logs WHERE has(mapValues(attributes), '192.168.1.1'); -- slow full-table scan

مع ازدياد حجم السجلات، تصبح هذه الاستعلامات بطيئة. يتمثل الحل في إنشاء فهرس نصي لمفاتيح Map وقيمها. استخدم mapKeys لإنشاء فهرس نصي عندما تحتاج إلى العثور على السجلات بناءً على أسماء الحقول أو أنواع السمات:

ALTER TABLE logs ADD INDEX attributes_keys_idx mapKeys(attributes) TYPE text(tokenizer = array);
ALTER TABLE posts MATERIALIZE INDEX attributes_keys_idx;

استخدم mapValues لإنشاء فهرس نصي عندما تحتاج إلى البحث في المحتوى الفعلي للسمات نفسها:

ALTER TABLE logs ADD INDEX attributes_vals_idx mapValues(attributes) TYPE text(tokenizer = array);
ALTER TABLE posts MATERIALIZE INDEX attributes_vals_idx;

أمثلة على الاستعلامات:

-- Find all rate-limited requests:
SELECT * FROM logs WHERE mapContainsKey(attributes, 'rate_limit'); -- fast

-- Finds all logs from a specific IP:
SELECT * FROM logs WHERE has(mapValues(attributes), '192.168.1.1'); -- fast

-- Finds all logs where any attribute includes an error:
SELECT * FROM logs WHERE mapContainsValueLike(attributes, '% error %'); -- fast

فهرسة أعمدة JSON

يمكن استخدام الفهارس النصية مع أعمدة JSON بثلاث طرق:

فهارس على أعمدة فرعية محددة — أنشئ فهرسًا نصيًا على مسار JSON معروف، تمامًا كما تفعل مع عمود عادي. يؤدي ذلك إلى فهرسة القيم الموجودة في هذا المسار.
فهارس قائمة على المسار باستخدام JSONAllPaths — تُفهرِس جميع المسارات الموجودة في كل granule لتخطي الـ granules التي لا يمكن أن تحتوي على المسار المطلوب في الاستعلام. وهذا مشابه لأعمدة Map.
فهارس قائمة على القيم باستخدام JSONAllValues — تُفهرِس جميع القيم عبر جميع مسارات JSON لتسريع البحث النصي الكامل في أي عمود JSON فرعي باستخدام فهرس واحد.

فهارس على أعمدة فرعية محددة

يمكنك إنشاء فهرس تخطٍّ على أي عمود فرعي في JSON باستخدام الصياغة نفسها المستخدمة مع الأعمدة العادية. توجد طريقتان للإشارة إلى عمود JSON فرعي في تعبير الفهرس:

مسار محدد النوع مُعرَّف في تلميح نوع JSON — ويمكن الوصول إليه بالاسم مباشرةً: json.a.
مسار Dynamic مع تحويل نوع صريح — استخدم صياغة تحويل النوع ::: json.b::String.

مثال على تعريف الفهرس:

Query

CREATE TABLE sensor_data
(
    data JSON(sensor_id String),
    INDEX idx_sensor data.sensor_id TYPE text(tokenizer = splitByNonAlpha),
    INDEX idx_location data.location::String TYPE text(tokenizer = splitByNonAlpha)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 1;

INSERT INTO sensor_data SELECT toJSONString(map('sensor_id', 'id_' || number , 'location', 'room_' || toString(number))) FROM numbers(4);
INSERT INTO sensor_data SELECT toJSONString(map('sensor_id', 'id_' || number, 'location', 'room_' || toString(number))) FROM numbers(4, 4);

مثال على استعلام:

Query

EXPLAIN indexes = 1 SELECT * FROM sensor_data WHERE data.sensor_id = 'id_5';

Response

...
    Indexes:
      Skip
        Name: idx_sensor
        Description: text
        Condition: (mode: All; tokens: ["5", "id"])
        Parts: 1/2
        Granules: 1/8

مثال لاستعلام:

Query

EXPLAIN indexes = 1 SELECT * FROM sensor_data WHERE data.location::String = 'room_5';

Response

...
    Indexes:
      Skip
        Name: idx_location
        Description: text
        Condition: (mode: All; tokens: ["5", "room"])
        Parts: 1/2
        Granules: 1/8

الفهارس المستندة إلى المسار باستخدام JSONAllPaths

على غرار أعمدة Map، يمكن إنشاء فهارس نصية على أعمدة JSON باستخدام JSONAllPaths. يخزّن الفهرس مجموعة مسارات JSON الموجودة في كل حبيبة، ويستخدمها لتخطّي الحبيبات التي لا يحتوي فيها الاستعلام على المسار المطلوب. مثال على تعريف الفهرس:

Query

CREATE TABLE events
(
    data JSON,
    INDEX idx JSONAllPaths(data) TYPE text(tokenizer = array)
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO events VALUES ('{"user": {"name": "Alice"}, "action": "login"}');
INSERT INTO events VALUES ('{"metric": {"cpu": 0.95}, "host": "srv1"}');

يمكنك استخدام EXPLAIN indexes = 1 للتحقق من استخدام فهرس التخطي. عندما يكون المسار موجودًا في جزء واحد فقط، يتجاوز الفهرس الجزء الآخر. مثال:

Query

EXPLAIN indexes = 1 SELECT * FROM events WHERE data.user.name = 'Alice';

Response

...
    Indexes:
      Skip
        Name: idx
        Description: text
        Condition: (mode: All; tokens: ["user.name"])
        Parts: 1/2
        Granules: 1/2

عندما لا يوجد المسار في أي جزء، تُتخطى جميع الأجزاء والحبيبات. مثال:

Query

EXPLAIN indexes = 1 SELECT * FROM events WHERE data.nonexistent = 1;

Response

...
    Indexes:
      Skip
        Name: idx
        Description: text
        Condition: (mode: All; tokens: ["nonexistent"])
        Parts: 0/2
        Granules: 0/2

يستخدم IS NOT NULL الفهرس أيضًا — إذ يتخطى الحبيبات التي يغيب فيها المسار (لأن القيمة ستكون NULL): مثال:

Query

EXPLAIN indexes = 1 SELECT * FROM events WHERE data.user.name IS NOT NULL;

Response

...
    Indexes:
      Skip
        Name: idx
        Description: text
        Condition: (mode: All; tokens: ["user.name"])
        Parts: 1/2
        Granules: 1/2

الفهارس القائمة على القيم باستخدام JSONAllValues

يمكن استخدام الفهارس النصية لتسريع عمليات البحث في أعمدة JSON عبر الدالة JSONAllValues. تعيد JSONAllValues جميع القيم من عمود JSON بصيغة Array(String). وتُحوَّل قيم أنواع البيانات غير النصية (مثل الأعداد الصحيحة والمصفوفات) إلى تمثيلها النصي. ويفهرس فهرس نصي مُنشأ باستخدام JSONAllValues هذه التمثيلات النصية عبر جميع مسارات JSON في كل صف. ويمكن لهذا الفهرس بعد ذلك تسريع الاستعلامات التي تُطبِّق عامل تصفية على أعمدة JSON الفرعية الفردية. وعندما يطبّق استعلام عامل تصفية على عمود فرعي محدد (مثل data.user_name = 'alice')، يمكن للفهرس النصي أن يتخطى بسرعة الصفوف (والحبيبات) التي لا تحتوي أيٌّ من قيم JSON فيها على رموز البحث.

قد يُنتج الفهرس نتائج إيجابية كاذبة عندما تحتوي مسارات JSON مختلفة على الرموز نفسها. على سبيل المثال، إذا كان الصف 1 يحتوي على {"a": "hello", "b": "world"} وكان الاستعلام يبحث عن data.a = 'world'، فلن يتمكن الفهرس النصي من تمييز أن world تنتمي إلى المسار b لا إلى a. وفي مثل هذه الحالات، لن يتخطى الفهرس هذا الصف، وسيتولى عامل التصفية على بيانات العمود الفعلية إجراء التقييم النهائي. وهذا هو السلوك نفسه في حالات استخدام الفهرس النصي الأخرى، حيث يعمل الفهرس كعامل تصفية تمهيدي سريع.

إنشاء الفهرس

مثال على تعريف الفهرس:

CREATE TABLE events
(
    id UInt64,
    data JSON,
    INDEX json_idx JSONAllValues(data) TYPE text(tokenizer = splitByNonAlpha)
)
ENGINE = MergeTree
ORDER BY id;

أنماط الاستعلام المدعومة

بمجرد إنشاء الفهرس، يمكنه تسريع الاستعلامات على الأعمدة الفرعية في JSON باستخدام الدوال نفسها المستخدَمة مع أعمدة String، بالإضافة إلى الدالة equals لجميع الأعمدة. الوصول إلى العمود الفرعي:

SELECT * FROM events WHERE data.user_name = 'alice';
SELECT * FROM events WHERE data.message LIKE '% error %';
SELECT * FROM events WHERE startsWith(data.status, 'fail');
SELECT * FROM events WHERE hasToken(data.title, 'clickhouse');

الوصول إلى العمود الفرعي باستخدام CAST الصريح:

SELECT * FROM events WHERE hasAllTokens(data.message::String, 'connection timeout');
SELECT * FROM events WHERE data.status_code::UInt64 = 404;
SELECT * FROM events WHERE has(data.tags::Array(String), 'bug')

المعامل IN:

SELECT * FROM events WHERE data.level IN ('error', 'critical');

البحث عن العبارات

يدعم فهرس النص البحث عن العبارات عبر الدالة hasPhrase. يجب أن تظهر جميع الرموز في العبارة بشكل متتالٍ وبالترتيب نفسه داخل المستند. يُسرّع فهرس النص البحث عن العبارات من خلال تقاطع قوائم الترحيل الخاصة بجميع الرموز في العبارة لتحديد الحبيبات المرشحة. وداخل تلك الحبيبات، يتحقق ClickHouse بعد ذلك من التجاور الدقيق بين الرموز. تتوافق hasPhrase مع المُجزِّئات ‏splitByNonAlpha وsplitByString وngrams وasciiCJK. تُجزَّأ سلسلة العبارة إلى رموز باستخدام المُجزِّئ المُهيأ في الفهرس. ويتم تجاهل أحرف الفصل الخاصة بالـ المُجزِّئ في العبارة: ‏hasPhrase(text, 'quick+brown') تكافئ hasPhrase(text, 'quick brown') بالنسبة إلى الـ المُجزِّئ ‏splitByNonAlpha.

مثال

Query

CREATE TABLE tab (
    id UInt32,
    text String,
    INDEX idx text TYPE text(tokenizer = splitByNonAlpha)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO tab VALUES
    (1, 'weather in New York'),
    (2, 'New weather in York'),
    (3, 'weather in New Orleans');

Query

SELECT id, text FROM tab WHERE hasPhrase(text, 'weather in New York');

Response

   ┌─id─┬─text────────────────┐
1. │  1 │ weather in New York │
   └────┴─────────────────────┘

الصف 2 ('New weather in York') لا يتطابق لأن الرموز ليست بالترتيب الصحيح. الصف 3 ('weather in New Orleans') لا يتطابق لأنه لا يحتوي على الرمز 'York'.

ضبط الأداء

القراءة المباشرة

يمكن تسريع بعض أنواع الاستعلامات النصية بدرجة كبيرة بفضل تحسين يُعرف باسم “القراءة المباشرة”. مثال:

SELECT column_a, column_b, ...
FROM [...]
WHERE string_search_function(column_with_text_index)

تُجيب آلية تحسين direct read عن الاستعلام بالاعتماد حصريًا على فهرس النص (أي من خلال عمليات lookup في فهرس النص) من دون الوصول إلى عمود النص الأساسي. وتقرأ عمليات lookup في فهرس النص قدرًا قليلًا نسبيًا من البيانات، لذا فهي أسرع بكثير من فهارس التخطي المعتادة في ClickHouse (التي تُجري lookup في فهرس التخطي، ثم تحميل الحبيبات المتبقية وتصفيتها). يُتحكَّم في direct read عبر إعدادين:

الإعداد query_plan_direct_read_from_text_index (وقيمته الافتراضية true) الذي يحدد ما إذا كانت direct read مفعّلة بشكل عام.
كان الإعداد use_skip_indexes_on_data_read شرطًا مسبقًا لـ direct read في إصدارات ClickHouse الأقدم من < 26.4.

الدوال المدعومة تدعم آلية تحسين direct read الدوال hasToken وhasAllTokens وhasAnyTokens. إذا كان فهرس النص معرّفًا باستخدام المُجزِّئ array، فإن direct read تدعم أيضًا الدوال equals وhas وhasAny وhasAll وmapContainsKey وmapContainsValue. ويمكن أيضًا دمج هذه الدوال باستخدام عوامل التشغيل AND وOR وNOT. كما يمكن أن تتضمن عبارتا WHERE أو PREWHERE عوامل تصفية إضافية لا تتعلق بدوال البحث النصي (لأعمدة النص أو الأعمدة الأخرى) - وفي هذه الحالة ستظل آلية تحسين direct read مستخدمة، ولكن بفعالية أقل (إذ إنها تنطبق فقط على دوال البحث النصي المدعومة). للتحقق مما إذا كان الاستعلام يستخدم direct read، شغّل الاستعلام باستخدام EXPLAIN PLAN actions = 1. وعلى سبيل المثال، استعلام مع تعطيل direct read

EXPLAIN PLAN actions = 1
SELECT count()
FROM table
WHERE hasToken(col, 'some_token')
SETTINGS query_plan_direct_read_from_text_index = 0, -- disable direct read

القيمة المُعادة

[...]
Filter ((WHERE + Change column names to column identifiers))
Filter column: hasToken(__table1.col, 'some_token'_String) (removed)
Actions: INPUT : 0 -> col String : 0
         COLUMN Const(String) -> 'some_token'_String String : 1
         FUNCTION hasToken(col :: 0, 'some_token'_String :: 1) -> hasToken(__table1.col, 'some_token'_String) UInt8 : 2
[...]

في حين يُشغَّل الاستعلام نفسه مع query_plan_direct_read_from_text_index = 1

EXPLAIN PLAN actions = 1
SELECT count()
FROM table
WHERE hasToken(col, 'some_token')
SETTINGS query_plan_direct_read_from_text_index = 1, -- enable direct read

القيمة المعادة

[...]
Expression (Before GROUP BY)
Positions:
  Filter
  Filter column: __text_index_idx_hasToken_94cc2a813036b453d84b6fb344a63ad3 (removed)
  Actions: INPUT :: 0 -> __text_index_idx_hasToken_94cc2a813036b453d84b6fb344a63ad3 UInt8 : 0
[...]

يحتوي خرج EXPLAIN PLAN الثاني على عمود افتراضي __text_index_<index_name>_<function_name>_<id>. إذا كان هذا العمود موجودًا، فهذا يعني أنه تم استخدام القراءة المباشرة. إذا كانت عبارة التصفية في WHERE تحتوي فقط على دوال البحث النصي، فيمكن للاستعلام تجنّب قراءة بيانات العمود بالكامل وتحقيق أكبر فائدة أداء عبر القراءة المباشرة. ومع ذلك، حتى إذا جرى الوصول إلى العمود النصي في موضع آخر من الاستعلام، فستظل القراءة المباشرة توفّر تحسينًا في الأداء. القراءة المباشرة كتلميح تعتمد القراءة المباشرة كتلميح على المبادئ نفسها التي تعتمد عليها القراءة المباشرة العادية، لكنها تضيف بدلًا من ذلك عامل تصفية إضافيًا مُنشأً من بيانات فهرس النص، من دون الاستغناء عن العمود النصي الأساسي. وتُستخدم مع الدوال التي قد تؤدي فيها القراءة من فهرس النص فقط إلى مطابقات إيجابية كاذبة. الدوال المدعومة هي: like, startsWith, endsWith, equals, has, hasPhrase, mapContainsKey, و mapContainsValue. يمكن لعامل التصفية الإضافي أن يوفّر انتقائية إضافية لتقييد مجموعة النتائج بدرجة أكبر عند دمجه مع عوامل تصفية أخرى، مما يساعد على تقليل كمية البيانات المقروءة من الأعمدة الأخرى. تخضع القراءة المباشرة كتلميح للإعداد query_plan_text_index_add_hint (مُمكّن افتراضيًا). مثال على استعلام من دون تلميح:

EXPLAIN actions = 1
SELECT count()
FROM table
WHERE (col LIKE '%some-token%') AND (d >= today())
SETTINGS query_plan_text_index_add_hint = 0
FORMAT TSV

القيم المعادة

[...]
Prewhere filter column: and(like(__table1.col, \'%some-token%\'_String), greaterOrEquals(__table1.d, _CAST(20440_Date, \'Date\'_String))) (removed)
[...]

بينما يُنفَّذ الاستعلام نفسه مع query_plan_text_index_add_hint = 1

EXPLAIN actions = 1
SELECT count()
FROM table
WHERE col LIKE '%some-token%'
SETTINGS query_plan_text_index_add_hint = 1

القيمة المُعادة

[...]
Prewhere filter column: and(__text_index_idx_col_like_d306f7c9c95238594618ac23eb7a3f74, like(__table1.col, \'%some-token%\'_String), greaterOrEquals(__table1.d, _CAST(20440_Date, \'Date\'_String))) (removed)
[...]

في ناتج EXPLAIN PLAN الثاني، يمكنك ملاحظة أنه قد أُضيف جزء اقتراني إضافي (__text_index_...) إلى شرط التصفية. وبفضل تحسين PREWHERE، يُقسَّم شرط التصفية إلى ثلاثة أجزاء اقترانية منفصلة، تُطبَّق بترتيب تصاعدي بحسب التعقيد الحسابي. بالنسبة لهذا الاستعلام، يكون ترتيب التطبيق هو __text_index_...، ثم greaterOrEquals(...)، وأخيرًا like(...). ويتيح هذا الترتيب تخطي عدد أكبر من حبيبات البيانات مقارنةً بما يتخطاه الفهرس النصي وشرط التصفية الأصلي، وذلك قبل قراءة الأعمدة الثقيلة المستخدمة في الاستعلام بعد عبارة WHERE، مما يقلل بدرجة أكبر كمية البيانات المطلوب قراءتها.

استعلامات LIKE/ILIKE

عندما يكون نمط استعلام LIKE/ILIKE هو %<alpha-numeric-characters-without-spaces>% ويكون مُجزِّئ لفهرس النص text index هو splitByNonAlpha أو array، يستفيد ClickHouse من الفهرس المعكوس inverted index لتسريع استعلامات LIKE/ILIKE بشكل كبير. ولتحقيق ذلك، يفحص ClickHouse القاموس Dictionary الخاص بالفهرس المعكوس بدلًا من إجراء فحص كامل للجدول للعثور على النمط المطابق. عند تمكين هذا التحسين، يُفترض أن تصبح استعلامات LIKE/ILIKE أسرع بكثير من الفحص الكامل للجدول. ومع ذلك، إذا كان النمط يطابق معظم الرموز tokens في القاموس، فقد يصبح الأداء أسوأ مقارنةً بالفحص الكامل للجدول. ولحسن الحظ، توجد آلية احتياطية fallback تمنع ذلك. يخضع هذا التحسين لإعداد واحد:

use_text_index_like_evaluation_by_dictionary_scan

وتخضع الآلية الاحتياطية fallback لإعدادين:

لا يدعم هذا التحسين إلا الدالتين like و ilike.

التخزين المؤقت

تتوفر ذاكرات تخزين مؤقت متعددة للاحتفاظ بأجزاء من الفهرس النصي في الذاكرة (انظر قسم تفاصيل التنفيذ): توجد حالياً ذاكرات تخزين مؤقت للترويسات بعد فك تسلسلها، والرموز، وقوائم الترحيل الخاصة بالفهرس النصي لتقليل عمليات الإدخال/الإخراج. يمكن تفعيلها عبر الإعدادات use_text_index_header_cache وuse_text_index_tokens_cache وuse_text_index_postings_cache. تكون جميع ذاكرات التخزين المؤقت معطلة افتراضياً. لمسح ذاكرات التخزين المؤقت، استخدم العبارة SYSTEM CLEAR TEXT INDEX CACHES يرجى الرجوع إلى إعدادات الخادم التالية لضبط ذاكرات التخزين المؤقت.

إعدادات ذاكرة التخزين المؤقت لرموز الفهرس النصي

الإعداد	الوصف
text_index_tokens_cache_policy	اسم سياسة ذاكرة التخزين المؤقت لرموز الفهرس النصي.
text_index_tokens_cache_size	الحد الأقصى لحجم ذاكرة التخزين المؤقت بالبايت.
text_index_tokens_cache_max_entries	الحد الأقصى لعدد الرموز بعد إلغاء تسلسلها في ذاكرة التخزين المؤقت.
text_index_tokens_cache_size_ratio	حجم الطابور المحمي في ذاكرة التخزين المؤقت لرموز الفهرس النصي نسبةً إلى الحجم الإجمالي لذاكرة التخزين المؤقت.

إعدادات ذاكرة التخزين المؤقت للترويسات

الإعداد	الوصف
text_index_header_cache_policy	اسم سياسة ذاكرة التخزين المؤقت لترويسات الفهرس النصي.
text_index_header_cache_size	الحد الأقصى لحجم ذاكرة التخزين المؤقت بالبايت.
text_index_header_cache_max_entries	الحد الأقصى لعدد الترويسات بعد إلغاء تسلسلها في ذاكرة التخزين المؤقت.
text_index_header_cache_size_ratio	حجم الطابور المحمي في ذاكرة التخزين المؤقت لترويسات الفهرس النصي نسبةً إلى الحجم الإجمالي لذاكرة التخزين المؤقت.

إعدادات ذاكرة التخزين المؤقت لقوائم الترحيل

Setting	Description
text_index_postings_cache_policy	اسم سياسة ذاكرة التخزين المؤقت لقوائم الترحيل في الفهرس النصي.
text_index_postings_cache_size	الحد الأقصى لحجم ذاكرة التخزين المؤقت بالبايت.
text_index_postings_cache_max_entries	الحد الأقصى لعدد قوائم الترحيل التي فُكّ تسلسلها في ذاكرة التخزين المؤقت.
text_index_postings_cache_size_ratio	حجم الطابور المحمي في ذاكرة التخزين المؤقت لقوائم الترحيل في الفهرس النصي نسبةً إلى الحجم الإجمالي لذاكرة التخزين المؤقت.

القيود

للفهرس النصي حاليًا القيود التالية:

قد يستهلك البناء المادي للفهرسة النصية التي تحتوي على عدد كبير من الرموز (مثلًا 10 مليارات رمز) كميات كبيرة من الذاكرة. ويمكن أن يحدث البناء المادي للفهرس النصي مباشرةً (ALTER TABLE <table> MATERIALIZE INDEX <index>) أو بصورة غير مباشرة أثناء عمليات دمج الأجزاء.
لا يمكن إجراء البناء المادي للفهرسة النصية على الأجزاء التي تحتوي على أكثر من 4.294.967.296 (= 2^32 = نحو 4.2 مليارات) صف. ومن دون فهرس نصي مُنشأ ماديًا، تلجأ الاستعلامات إلى البحث البطيء بالقوة الغاشمة داخل الجزء. وكتقدير لأسوأ الاحتمالات، افترض أن جزءًا يحتوي على عمود واحد من النوع String وأن إعداد MergeTree max_bytes_to_merge_at_max_space_in_pool (القيمة الافتراضية: 150 جيجابايت) لم يتغير. في هذه الحالة، يحدث ذلك إذا كان العمود يحتوي في المتوسط على أقل من 29.5 حرفًا لكل صف. وعمليًا، تحتوي الجداول أيضًا على أعمدة أخرى، وتكون العتبة أقل من ذلك بعدة مرات (بحسب عدد الأعمدة الأخرى ونوعها وحجمها).

فهارس النص مقابل الفهارس المعتمدة على Bloom filter

يمكن تسريع predicates الخاصة بـ String باستخدام فهارس النص والفهارس المعتمدة على Bloom filter (أنواع الفهارس bloom_filter وngrambf_v1 وtokenbf_v1 وsparse_grams)، إلا أن كليهما يختلفان اختلافًا جوهريًا من حيث التصميم وحالات الاستخدام المستهدفة: فهارس Bloom filter

تستند إلى هياكل بيانات احتمالية قد تؤدي إلى false positives.
لا يمكنها إلا الإجابة عن أسئلة الانتماء إلى مجموعة، أي إن العمود قد يحتوي على الرمز X أو أنه بالتأكيد لا يحتوي على X.
تخزّن معلومات على مستوى الحبيبة، مما يتيح تخطي نطاقات واسعة أثناء تنفيذ query.
يصعب ضبطها على نحو صحيح (راجع هنا للاطلاع على مثال).
وهي مدمجة نسبيًا (بضعة كيلوبايتات أو ميغابايتات لكل part).

فهارس النص

تبني فهرسًا معكوسًا حتميًا على الرموز. ولا يمكن أن تنتج عن الفهرس نفسه false positives.
مُحسّنة خصيصًا لأعباء عمل البحث النصي.
تخزّن معلومات على مستوى الصف، مما يتيح lookup فعّالًا للمصطلحات.
وهي كبيرة نسبيًا (من عشرات إلى مئات الميغابايتات لكل part).

تدعم الفهارس المعتمدة على Bloom filter البحث النصي الكامل فقط كـ “أثر جانبي”:

فهي لا تدعم tokenization وpreprocessing المتقدمين.
وهي لا تدعم البحث باستخدام عدة رموز.
وهي لا توفر خصائص الأداء المتوقعة من فهرس معكوس.

أما فهارس النص، فعلى النقيض، فهي مصممة خصيصًا للبحث النصي الكامل:

فهي توفر tokenization وpreprocessing
وتوفر دعمًا فعّالًا لـ hasAllTokens وLIKE وmatch ووظائف البحث النصي المشابهة.
وتتمتع بقابلية توسّع أفضل بكثير مع المجموعات النصية الكبيرة.

تفاصيل التنفيذ

يتكوّن كل فهرس نصي من بنيتَي بيانات (مجرّدتين):

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

يُنشأ الفهرس النصي للجزء بأكمله. وعلى خلاف skip indexes الأخرى، يمكن دمج الفهرس النصي بدلًا من إعادة بنائه عند دمج data parts (انظر أدناه). أثناء إنشاء الفهرس، تُنشأ ثلاثة ملفات (لكل جزء): ملف كتل القاموس (.dct) تُرتَّب الرموز في الفهرس النصي وتُخزَّن في كتل قاموس تضم 512 رمزًا لكل منها (حجم الكتلة قابل للتهيئة عبر parameter ‏dictionary_block_size). ويتكوّن ملف كتل القاموس (.dct) من جميع كتل القاموس لكل index granules في الجزء. ملف ترويسة الفهرس (.idx) يحتوي ملف ترويسة الفهرس، لكل كتلة قاموس، على أول رمز في الكتلة وإزاحته النسبية داخل ملف كتل القاموس. تشبه بنية sparse index هذه فهرس المفتاح الأساسي المتناثر) في ClickHouse. ملف قوائم الترحيلات (.pst) تُرتَّب قوائم الترحيلات الخاصة بجميع الرموز ترتيبًا تسلسليًا في ملف قوائم الترحيلات. ولتوفير المساحة مع الحفاظ على سرعة عمليات التقاطع والاتحاد، تُخزَّن قوائم الترحيلات على هيئة roaring bitmaps. إذا كانت قائمة الترحيلات أكبر من posting_list_block_size، فتُقسَّم إلى عدة كتل تُخزَّن تسلسليًا في ملف قوائم الترحيلات. دمج الفهارس النصية عند دمج data parts، لا يحتاج الفهرس النصي إلى إعادة بنائه من الصفر؛ بل يمكن دمجه بكفاءة في step منفصلة من merge process. وخلال هذه step، تُقرأ القواميس المرتبة للفهارس النصية لكل جزء إدخال وتُدمج في قاموس موحّد جديد. كما يُعاد حساب أرقام الصفوف في قوائم الترحيلات لتعكس مواضعها الجديدة في data part المدمج، باستخدام mapping من أرقام الصفوف القديمة إلى الجديدة يُنشأ خلال Phase الدمج الأولية. وتشبه طريقة دمج الفهارس النصية هذه كيفية دمج projections التي تحتوي على العمود _part_offset. وإذا لم يكن الفهرس materialized في الجزء المصدر، فيُبنى ويُكتب في ملف مؤقت ثم يُدمج مع الفهارس من الأجزاء الأخرى ومن ملفات الفهارس المؤقتة الأخرى. تصحيح الأخطاء يمكن استخدام table function ‏mergeTreeTextIndex لفحص الفهارس النصية داخليًا.

مثال: مجموعة بيانات Hacker News

لنلقِ نظرة على تحسينات الأداء التي توفّرها الفهارس النصية في مجموعة بيانات كبيرة تضم قدرًا كبيرًا من النصوص. سنستخدم 28.7 مليون صف من التعليقات على موقع Hacker News الشهير. فيما يلي الجدول من دون فهرس نصي:

CREATE TABLE hackernews (
    id UInt64,
    deleted UInt8,
    type String,
    author String,
    timestamp DateTime,
    comment String,
    dead UInt8,
    parent UInt64,
    poll UInt64,
    children Array(UInt32),
    url String,
    score UInt32,
    title String,
    parts Array(UInt32),
    descendants UInt32
)
ENGINE = MergeTree
ORDER BY (type, author);

توجد 28.7 مليون صف في ملف Parquet على S3 — لِنُدرجها في جدول hackernews:

INSERT INTO hackernews
    SELECT * FROM s3Cluster(
        'default',
        'https://datasets-documentation.s3.eu-west-3.amazonaws.com/hackernews/hacknernews.parquet',
        'Parquet',
        '
    id UInt64,
    deleted UInt8,
    type String,
    by String,
    time DateTime,
    text String,
    dead UInt8,
    parent UInt64,
    poll UInt64,
    kids Array(UInt32),
    url String,
    score UInt32,
    title String,
    parts Array(UInt32),
    descendants UInt32');

سنستخدم ALTER TABLE لإضافة فهرس نصي إلى عمود comment، ثم نطبّقه فعليًا:

-- Add the index
ALTER TABLE hackernews ADD INDEX comment_idx comment TYPE text(tokenizer = splitByNonAlpha);

-- Materialize the index for existing data
ALTER TABLE hackernews MATERIALIZE INDEX comment_idx SETTINGS mutations_sync = 2;

الآن، لنشغّل استعلامات باستخدام الدوال hasToken وhasAnyTokens وhasAllTokens. ستُظهر الأمثلة التالية الفرق الكبير في الأداء بين فحص فهرس تقليدي وتحسين القراءة المباشرة.

1. استخدام `hasToken`

يتحقق hasToken مما إذا كان النص يحتوي على رمز واحد محدد. سنبحث عن الرمز الحساس لحالة الأحرف ‘ClickHouse’. القراءة المباشرة معطّلة (المسح القياسي) بشكل افتراضي، يستخدم ClickHouse فهرس التخطي لتصفية الحبيبات، ثم يقرأ بيانات العمود الخاصة بهذه الحبيبات. يمكننا محاكاة هذا السلوك من خلال تعطيل القراءة المباشرة.

SELECT count()
FROM hackernews
WHERE hasToken(comment, 'ClickHouse')
SETTINGS query_plan_direct_read_from_text_index = 0;

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

1 row in set. Elapsed: 0.362 sec. Processed 24.90 million rows, 9.51 GB

القراءة المباشرة مفعّلة (قراءة سريعة من الفهرس) نُشغِّل الآن الاستعلام نفسه مع تفعيل القراءة المباشرة (وهو الإعداد الافتراضي).

SELECT count()
FROM hackernews
WHERE hasToken(comment, 'ClickHouse')
SETTINGS query_plan_direct_read_from_text_index = 1;

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

1 row in set. Elapsed: 0.008 sec. Processed 3.15 million rows, 3.15 MB

استعلام direct read أسرع بأكثر من 45 مرة (0.362s مقابل 0.008s)، ويعالج بيانات أقل بكثير (9.51 GB مقابل 3.15 MB) عبر القراءة من الفهرس فقط.

2. استخدام `hasAnyTokens`

يتحقق hasAnyTokens مما إذا كان النص يحتوي على واحدة على الأقل من الوحدات المعطاة. سنبحث عن التعليقات التي تحتوي على ‘love’ أو ‘ClickHouse’. تم تعطيل Direct read (Standard scan)

SELECT count()
FROM hackernews
WHERE hasAnyTokens(comment, 'love ClickHouse')
SETTINGS query_plan_direct_read_from_text_index = 0;

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

1 row in set. Elapsed: 1.329 sec. Processed 28.74 million rows, 9.72 GB

القراءة المباشرة مفعّلة (قراءة سريعة للفهرس)

SELECT count()
FROM hackernews
WHERE hasAnyTokens(comment, 'love ClickHouse')
SETTINGS query_plan_direct_read_from_text_index = 1;

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

1 row in set. Elapsed: 0.015 sec. Processed 27.99 million rows, 27.99 MB

التحسّن في السرعة هنا أكثر وضوحًا في بحث “OR” الشائع هذا. أصبح الاستعلام أسرع بنحو 89 مرة تقريبًا (1.329s مقابل 0.015s) بفضل تجنّب إجراء مسح كامل للعمود.

3. استخدام `hasAllTokens`

يتحقق hasAllTokens من احتواء النص على جميع الرموز المعطاة. سنبحث عن التعليقات التي تحتوي على كلٍّ من ‘love’ و’ClickHouse’. القراءة المباشرة معطّلة (المسح القياسي) حتى مع تعطيل القراءة المباشرة، يظل فهرس التخطي القياسي فعّالًا. فهو يقلّص عدد الصفوف من 28.7 مليون صف إلى 147.46 ألف صف فقط، لكنه لا يزال مضطرًا إلى قراءة 57.03 ميغابايت من العمود.

SELECT count()
FROM hackernews
WHERE hasAllTokens(comment, 'love ClickHouse')
SETTINGS query_plan_direct_read_from_text_index = 0;

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

1 row in set. Elapsed: 0.184 sec. Processed 147.46 thousand rows, 57.03 MB

تم تفعيل direct read (قراءة سريعة للفهرس) يُجيب direct read عن الاستعلام بالاعتماد على بيانات الفهرس، فلا يقرأ سوى 147.46 KB.

SELECT count()
FROM hackernews
WHERE hasAllTokens(comment, 'love ClickHouse')
SETTINGS query_plan_direct_read_from_text_index = 1;

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

1 row in set. Elapsed: 0.007 sec. Processed 147.46 thousand rows, 147.46 KB

في عملية البحث هذه باستخدام “AND”، يكون تحسين القراءة المباشرة أسرع بأكثر من 26 مرة (0.184s مقابل 0.007s) من المسح القياسي لفهرس التخطي.

4. البحث المركب: OR, AND, NOT, …

يسري تحسين direct read أيضًا على التعبيرات المنطقية المركبة. سنُجري هنا بحثًا غير حساس لحالة الأحرف عن ‘ClickHouse’ OR ‘clickhouse’. مع تعطيل direct read (المسح القياسي)

SELECT count()
FROM hackernews
WHERE hasToken(comment, 'ClickHouse') OR hasToken(comment, 'clickhouse')
SETTINGS query_plan_direct_read_from_text_index = 0;

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

1 row in set. Elapsed: 0.450 sec. Processed 25.87 million rows, 9.58 GB

القراءة المباشرة مفعّلة (قراءة سريعة من الفهرس)

SELECT count()
FROM hackernews
WHERE hasToken(comment, 'ClickHouse') OR hasToken(comment, 'clickhouse')
SETTINGS query_plan_direct_read_from_text_index = 1;

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

1 row in set. Elapsed: 0.013 sec. Processed 25.87 million rows, 51.73 MB

من خلال دمج النتائج المستخرجة من الفهرس، يصبح استعلام القراءة المباشرة أسرع بمقدار 34 مرة (0.450s مقابل 0.013s)، ويتجنب قراءة 9.58 GB من بيانات الأعمدة. في هذه الحالة تحديدًا، ستكون الصياغة hasAnyTokens(comment, ['ClickHouse', 'clickhouse']) هي الخيار المفضل والأكثر كفاءة.

محتوى قديم

آخر تعديل في ٢٥ يونيو ٢٠٢٦

VersionedCollapsingMergeTreeيتيح الكتابة السريعة لحالات الكائنات التي تتغير باستمرار، وحذف حالات الكائنات القديمة في الخلفية.

​إنشاء فهرس نصي

​استخدام فهرس نصي

​الدوال المدعومة

​=

​IN

​LIKE and match

​multiSearchAny و multiMatchAny

​startsWith and endsWith

​hasToken و hasTokenOrNull

​hasAnyTokens and hasAllTokens

​hasPhrase

​has

​hasAny و hasAll

​mapContains

​mapContainsValue

​mapContainsKeyLike و mapContainsValueLike

​operator[]

​فهرسة أعمدة Array(String)

​فهرسة أعمدة Map

​فهرسة أعمدة JSON

​فهارس على أعمدة فرعية محددة

​الفهارس المستندة إلى المسار باستخدام JSONAllPaths

​الفهارس القائمة على القيم باستخدام JSONAllValues

إنشاء الفهرس

أنماط الاستعلام المدعومة

​البحث عن العبارات

​مثال

​ضبط الأداء

​القراءة المباشرة

​استعلامات LIKE/ILIKE

​التخزين المؤقت

​إعدادات ذاكرة التخزين المؤقت لرموز الفهرس النصي

​إعدادات ذاكرة التخزين المؤقت للترويسات

​إعدادات ذاكرة التخزين المؤقت لقوائم الترحيل

​القيود

​فهارس النص مقابل الفهارس المعتمدة على Bloom filter

​تفاصيل التنفيذ

​مثال: مجموعة بيانات Hacker News

​1. استخدام hasToken

​2. استخدام hasAnyTokens

​3. استخدام hasAllTokens

​4. البحث المركب: OR, AND, NOT, …

​محتوى ذو صلة

إنشاء فهرس نصي

استخدام فهرس نصي

الدوال المدعومة

`=`

`IN`

`LIKE` and `match`

`multiSearchAny` و `multiMatchAny`

`startsWith` and `endsWith`

`hasToken` و `hasTokenOrNull`

`hasAnyTokens` and `hasAllTokens`

`hasPhrase`

`has`

`hasAny` و `hasAll`

`mapContains`

`mapContainsValue`

`mapContainsKeyLike` و `mapContainsValueLike`

`operator[]`

فهرسة أعمدة Array(String)

فهرسة أعمدة Map

فهرسة أعمدة JSON

فهارس على أعمدة فرعية محددة

الفهارس المستندة إلى المسار باستخدام JSONAllPaths

الفهارس القائمة على القيم باستخدام JSONAllValues

البحث عن العبارات

مثال

ضبط الأداء

القراءة المباشرة

استعلامات LIKE/ILIKE

التخزين المؤقت

إعدادات ذاكرة التخزين المؤقت لرموز الفهرس النصي

إعدادات ذاكرة التخزين المؤقت للترويسات

إعدادات ذاكرة التخزين المؤقت لقوائم الترحيل

القيود

فهارس النص مقابل الفهارس المعتمدة على Bloom filter

تفاصيل التنفيذ

مثال: مجموعة بيانات Hacker News

1. استخدام `hasToken`

2. استخدام `hasAnyTokens`

3. استخدام `hasAllTokens`

4. البحث المركب: OR, AND, NOT, …

محتوى ذو صلة