محرك الجدول TimeSeries

محرك الجدول يُخزّن سلاسل زمنية، أي مجموعة من القيم المرتبطة بالطوابع الزمنية والوسوم (أو التسميات).

محرك الجدول يخزّن سلسلة زمنية، أي مجموعة من القيم المرتبطة بطوابع زمنية ووسوم (أو تسميات):

metric_name1[tag1=value1, tag2=value2, ...] = {timestamp1: value1, timestamp2: value2, ...}
metric_name2[...] = ...

هذه ميزة في private preview، وقد تتغير مستقبلًا على نحو غير متوافق مع الإصدارات السابقة. فعِّل استخدام محرك الجدول TimeSeries باستخدام الإعداد enable_time_series_table. أدخِل الأمر set enable_time_series_table = 1.

محرك الجدول TimeSeries متاح في ClickHouse Cloud كميزة في private preview. الخدمات المشارِكة في private preview لديها بالفعل الإعداد enable_time_series_table مهيَّأً. أما خدمات ClickHouse Cloud الأخرى فلا تتوفر لديها هذه التهيئة، ولا يمكنك تفعيل المحرك بنفسك على مثل هذه الخدمة.

​

الصياغة

CREATE TABLE name [(columns)] ENGINE=TimeSeries
[SETTINGS var1=value1, ...]
[SAMPLES db.samples_table_name | [SAMPLES INNER COLUMNS (...)] [SAMPLES INNER ENGINE engine(arguments)]]
[RECENT SAMPLES db.recent_samples_table_name | [RECENT SAMPLES INNER COLUMNS (...)] [RECENT SAMPLES INNER ENGINE engine(arguments)]]
[TAGS db.tags_table_name | [TAGS INNER COLUMNS (...)] [TAGS INNER ENGINE engine(arguments)]]
[METRIC FAMILIES db.metric_families_table_name | [METRIC FAMILIES INNER COLUMNS (...)] [METRIC FAMILIES INNER ENGINE engine(arguments)]]

للكلمة المفتاحية SAMPLES اسم مستعار هو DATA، وللكلمة المفتاحية METRIC FAMILIES اسم مستعار هو METRICS، وقد أُبقي على كليهما للحفاظ على التوافق مع الإصدارات السابقة. يُكتب تعريف الجدول الخاص بأي version أقدم من 4 باستخدام METRICS، حتى يتمكن خادم أقدم من قراءته.

​

الاستخدام

من الأسهل البدء بالإعدادات الافتراضية لكل شيء (يُسمح بإنشاء جدول TimeSeries من دون تحديد قائمة بالأعمدة):

CREATE TABLE my_table ENGINE=TimeSeries

بعد ذلك، يمكن استخدام هذا الجدول مع البروتوكولات التالية (يجب تعيين منفذ في تهيئة الخادم):

• prometheus remote-write
• prometheus remote-read

​

الأعمدة الخارجية

تُنشأ أعمدة جدول TimeSeries تلقائيًا. وهذه هي الأعمدة الخارجية؛ فهي لا تخزّن أي بيانات، وإنما توفّر فقط واجهة لـ SELECT/INSERT. وتُخزَّن البيانات الفعلية في الجداول الهدف. وفيما يلي قائمة الأعمدة الخارجية:

Name	Type	Description
metric_name	String	اسم المقياس
tags	Map(String, String)	خريطة الوسوم (التسميات) للسلسلة الزمنية
samples	Array(Tuple(DateTime64(3), Float64)) افتراضيًا	مصفوفة من أزواج (timestamp، value) لسلسلة زمنية. ويمكن اشتقاق نوعَي عنصر timestamp والعنصر scalar في Tuple من تعريف INNER COLUMNS الخاص بـ samples (راجع تحديد الأعمدة الخارجية). ويُسمّى العمود time_series في الجداول ذات الإصدار 2 والإصدارات الأقدم
metric_family	String	اسم عائلة المقياس (للبيانات الوصفية للمقاييس)
type	String	نوع المقياس (مثل “counter” و”gauge”)
unit	String	وحدة المقياس
help	String	وصف المقياس

مثال:

INSERT INTO my_table (metric_name, tags, samples) VALUES
    ('cpu_usage', {'job': 'node_exporter', 'instance': 'host1:9100'},
     [(toDateTime64('2024-01-01 00:00:00', 3), 0.5), (toDateTime64('2024-01-01 00:01:00', 3), 0.7)])

يُسمح بأن تكون القيمة metric_name فارغة عند الإدخال، ما يعني أن اسم المقياس يُحدَّد في tags ضمن __name__، على سبيل المثال:

INSERT INTO my_table (tags, samples) VALUES
    ({'__name__': 'cpu_usage', 'job': 'test'},
     [(toDateTime64('2024-01-01 00:00:00', 3), 0.5)])

لإدراج البيانات الوصفية للمقاييس، أدرِجها في الأعمدة metric_family وtype وunit وhelp:

INSERT INTO my_table (metric_name, tags, samples, metric_family, type, unit, help) VALUES
    ('http_requests_total', {'method': 'GET'}, [(now64(), 100.0)],
     'http_requests_total', 'counter', 'requests', 'Total HTTP requests')

​

تحديد الأعمدة الخارجية

يمكن إدراج العمود الخارجي samples صراحةً في عبارة CREATE TABLE لاستبدال نوعه الافتراضي Array(Tuple(DateTime64(3), Float64)) (كما يُقبل اسمه القديم time_series أيضاً). يستخرج ClickHouse نوعَي الطابع الزمني والقيمة scalar من الـ tuple ويُمرّرهما إلى جدول العينات الداخلي:

CREATE TABLE my_table (samples Array(Tuple(UInt32, Float32))) ENGINE=TimeSeries

وهذا يعادل التصريح مباشرةً بأنواع أعمدة الطابع الزمني والقيمة في عبارة INNER COLUMNS الخاصة بجدول samples:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp UInt32 CODEC(Delta, T64, ZSTD(3)), value Float32 CODEC(ALP, ZSTD(3)))

إذا استُخدمت الصيغتان كلتاهما ضمن عبارة CREATE TABLE نفسها، فيجب أن تتطابق الأنواع المُعلنة.

​

الجداول الهدف

لا يحتوي جدول TimeSeries على بيانات خاصة به، إذ يُخزَّن كل شيء في جداوله الهدف. وهذا يشبه طريقة عمل العرض المادي، مع فارق أن العرض المادي له جدول هدف واحد، بينما يحتوي جدول TimeSeries على ثلاثة جداول هدف إلزامية باسم samples وtags وعائلة المقياس، وجدول هدف اختياري لـ العينات الحديثة يكون مُمكّنًا افتراضيًا (انظر الإعداد recent_samples_ttl_seconds).

يمكن تحديد الجداول الهدف صراحةً في استعلام CREATE TABLE أو يمكن لمحرك الجدول TimeSeries إنشاء الجداول الهدف الداخلية تلقائيًا.

تُحوَّل الصفوف المُدرجة في جدول TimeSeries، وتُقسَّم إلى كتل، ثم تُدرج في هذه الجداول الهدف.

الجداول الهدف هي كما يلي:

​

جدول العينات

يحتوي جدول samples على سلاسل زمنية مرتبطة بمعرّف معيّن.

يجب أن يحتوي جدول samples على الأعمدة التالية:

الاسم	إلزامي؟	النوع الافتراضي	الأنواع الممكنة	الوصف
id	[x]	Tuple(UInt64, LowCardinality(UUID))	أيّ نوع	يحدّد مجموعة من أسماء المقاييس والوسوم
timestamp	[x]	DateTime64(3)	DateTime64(X)	نقطة زمنية
value	[x]	Float64	Float32 أو Float64	قيمة مرتبطة بـ timestamp

تستخدم الأعمدة التي ينشئها المحرك تلقائيًا برامج ترميز ضغط للسلاسل الزمنية: timestamp CODEC(Delta, T64, ZSTD(3)) وvalue CODEC(ALP, ZSTD(3)). بالكاد تُضغط الطوابع الزمنية شبه الرتيبة باستخدام برامج الترميز العامة، وقد تستحوذ لولا ذلك على معظم حجم جدول العينات على القرص. يفعّل المحرك ALP لجداول العينات الداخلية وجداول العينات الحديثة الخاصة به دون الحاجة إلى ضبط enable_alp_codec. انظر أيضًا ضبط أنواع الأعمدة.

​

جدول العينات الحديثة

جدول العينات الحديثة اختياري ومُفعّل افتراضيًا (راجع إعداد recent_samples_ttl_seconds؛ إذ يؤدي ضبطه على صفر إلى تعطيل الجدول). يحتوي على نسخة من العينات الأحدث من قيمة TTL التي يحددها هذا الإعداد، ويجب أن يتضمن الأعمدة نفسها الموجودة في جدول العينات. يستخدم العمود المُولَّد timestamp الترميز CODEC(Delta, T64, ZSTD(3))، ويستخدم العمود المُولَّد value الترميز CODEC(ALP, ZSTD(3)).

تُكتب كل عينة مُدرجة في كلٍّ من جدول العينات وجدول العينات الحديثة. تقرأ الاستعلامات التي يقع نطاقها الزمني ضمن نافذة TTL من جدول العينات الحديثة بدلًا من جدول العينات الرئيسي لأنه أصغر بكثير (يمكن تعطيل ذلك باستخدام إعداد على مستوى الاستعلام time_series_prefer_recent_samples_table).

تُشتق قيمة TTL لجدول العينات الحديثة الداخلي دائمًا من إعداد recent_samples_ttl_seconds.

​

جدول الوسوم

يحتوي جدول tags على المعرّفات المحسوبة لكل توليفة من اسم مقياس والوسوم.

يجب أن يحتوي جدول tags على الأعمدة التالية:

Name	Mandatory?	Default type	Possible types	Description
id	[x]	Tuple(UInt64, LowCardinality(UUID))	any (must match the type of id in the samples table)	يعرّف id توليفة من اسم مقياس والوسوم. ويحدّد تعبير DEFAULT كيفية حساب هذا المعرّف
metric_name	[x]	LowCardinality(String)	String or LowCardinality(String)	اسم المقياس
<tag_value_column>	[ ]	String	String or LowCardinality(String) or LowCardinality(Nullable(String))	قيمة وسم معيّن، ويُحدَّد اسم الوسم واسم العمود المقابل له في الإعداد tags_to_columns
tags	[x]	Map(LowCardinality(String), String)	Map(String, String) or Map(LowCardinality(String), String) or Map(LowCardinality(String), LowCardinality(String))	خريطة لجميع الوسوم، بما فيها الوسم __name__ الذي يحتوي على اسم المقياس، والوسوم التي أُدرجت أسماؤها في الإعداد tags_to_columns. كانت الجداول التي أنشأتها الإصدارات الأقدم من ClickHouse تخزّن في هذا العمود الوسوم التي لا تحتوي على أعمدة مخصصة فقط ودون اسم المقياس؛ وتدعم القراءة كلتا الحالتين
min_time	[ ]	Nullable(DateTime64(3))	DateTime64(X) or Nullable(DateTime64(X))	أدنى طابع زمني للسلسلة الزمنية ذات id هذا. يُنشأ العمود إذا كانت قيمة store_min_time_and_max_time هي true
max_time	[ ]	Nullable(DateTime64(3))	DateTime64(X) or Nullable(DateTime64(X))	أقصى طابع زمني للسلسلة الزمنية ذات id هذا. يُنشأ العمود إذا كانت قيمة store_min_time_and_max_time هي true

تحتوي جداول الوسوم الداخلية الجديدة من version 5 فما بعد، والتي تستخدم محركًا من عائلة MergeTree، على فهرس نصي معكوس على tags: INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs'). وهو يسرّع المطابقات التامة للوسوم مثل {job="api"} في PromQL عبر البحث عن المفتاح والقيمة معًا. أما المقارنات مع سلسلة فارغة فتطابق أيضًا الوسوم المفقودة ولا تستفيد من هذا الفهرس.

تحلّ الفهارس الصريحة المعلَنة في TAGS INNER COLUMNS محل الفهرس الافتراضي. أما الجداول الموجودة وجداول الوسوم الخارجية فتحتفظ بفهارسها؛ ولتفعيله عليها، أضف الفهرس وجسّده على جدول الهدف الخاص بوسومها.

​

جدول عائلات المقاييس

يحتوي جدول metric families على بعض المعلومات حول عائلات المقاييس التي تُجمع، وأنواع تلك العائلات وأوصافها. عائلة المقياس هي مجموعة من المقاييس التي تحمل الاسم نفسه (الوسم __name__) والنوع نفسه، فعلى سبيل المثال المُدرَّج التكراري هو عائلة مقياس تتكون من عدة مقاييس.

يجب أن يحتوي جدول metric families على الأعمدة التالية:

الاسم	إلزامي؟	النوع الافتراضي	الأنواع الممكنة	الوصف
metric_family_name	[x]	String	String أو LowCardinality(String)	اسم عائلة المقياس
type	[x]	LowCardinality(String)	String أو LowCardinality(String)	نوع عائلة المقياس، ويكون إحدى القيم التالية: “counter” أو “gauge” أو “summary” أو “stateset” أو “histogram” أو “gaugehistogram”
unit	[x]	LowCardinality(String)	String أو LowCardinality(String)	الوحدة المستخدمة في المقياس
help	[x]	String	String أو LowCardinality(String)	وصف المقياس

​

الإنشاء

توجد عدة طرق لإنشاء جدول باستخدام محرك الجدول TimeSeries. أبسط عبارة

CREATE TABLE my_table ENGINE=TimeSeries

سينشئ فعليًا الجدول التالي (يمكنك التحقق من ذلك بتنفيذ SHOW CREATE TABLE my_table):

CREATE TABLE my_table
(
    `metric_name` String,
    `tags` Map(String, String),
    `samples` Array(Tuple(DateTime64(3), Float64)),
    `metric_family` String,
    `type` String,
    `unit` String,
    `help` String
)
ENGINE = TimeSeries
SETTINGS version = 5, recent_samples_ttl_seconds = 345600
SAMPLES INNER COLUMNS
(
    `id` Tuple(UInt64, LowCardinality(UUID)),
    `timestamp` DateTime64(3) CODEC(Delta, T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
SAMPLES INNER ENGINE = MergeTree ORDER BY (id, timestamp) SETTINGS index_granularity = 32768
RECENT SAMPLES INNER COLUMNS
(
    `id` Tuple(UInt64, UUID),
    `timestamp` DateTime64(3) CODEC(Delta, T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
RECENT SAMPLES INNER ENGINE = MergeTree PARTITION BY toStartOfInterval(toDateTime(timestamp), toIntervalHour(5)) ORDER BY (id, timestamp) TTL toDateTime(timestamp) + toIntervalSecond(345600) SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1
TAGS INNER COLUMNS
(
    `id` Tuple(UInt64, LowCardinality(UUID)) DEFAULT tuple(sipHash64(metric_name), toLowCardinality(reinterpretAsUUID(sipHash128(tags)))),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `min_time` SimpleAggregateFunction(min, Nullable(DateTime64(3))),
    `max_time` SimpleAggregateFunction(max, Nullable(DateTime64(3))),
    INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs') GRANULARITY 100000000
)
TAGS INNER ENGINE = AggregatingMergeTree PRIMARY KEY metric_name ORDER BY (metric_name, id) SETTINGS allow_dimensions_outside_sorting_key = 1, index_granularity = 8192
METRIC FAMILIES INNER COLUMNS
(
    `metric_family_name` String,
    `type` LowCardinality(String),
    `unit` LowCardinality(String),
    `help` String
)
METRIC FAMILIES INNER ENGINE = ReplacingMergeTree ORDER BY metric_family_name

لذلك، جرى إنشاء الأعمدة تلقائيًا، وهناك أيضًا أربعة جداول هدف داخلية، لكل منها تعريفات أعمدة خاصة مخزنة في عبارات INNER COLUMNS. وكُتب الإعداد recent_samples_ttl_seconds في عبارة SETTINGS بقيمته الافتراضية: يحدد الإعداد TTL لجدول العينات الحديثة، لذا تُثبَّت قيمته الفعلية عند الإنشاء. كما جرى تثبيت أحدث إصدار من المخطط في الإعداد version (انظر إصدارات المخطط).

تحمل الجداول الهدف الداخلية أسماء مثل .inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx، و.inner_id.recentsamples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx، و.inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx، و.inner_id.metricfamilies.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ولكل جدول هدف مجموعته الخاصة من الأعمدة:

CREATE TABLE default.`.inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` Tuple(UInt64, LowCardinality(UUID)),
    `timestamp` DateTime64(3) CODEC(Delta(8), T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
ENGINE = MergeTree
ORDER BY (id, timestamp)
SETTINGS index_granularity = 32768

CREATE TABLE default.`.inner_id.recentsamples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` Tuple(UInt64, UUID),
    `timestamp` DateTime64(3) CODEC(Delta(8), T64, ZSTD(3)),
    `value` Float64 CODEC(ALP, ZSTD(3))
)
ENGINE = MergeTree
PARTITION BY toStartOfInterval(toDateTime(timestamp), toIntervalHour(5))
ORDER BY (id, timestamp)
TTL toDateTime(timestamp) + toIntervalSecond(345600)
SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1

CREATE TABLE default.`.inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` Tuple(UInt64, LowCardinality(UUID)) DEFAULT tuple(sipHash64(metric_name), toLowCardinality(reinterpretAsUUID(sipHash128(tags)))),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `min_time` SimpleAggregateFunction(min, Nullable(DateTime64(3))),
    `max_time` SimpleAggregateFunction(max, Nullable(DateTime64(3))),
    INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs') GRANULARITY 100000000
)
ENGINE = AggregatingMergeTree
PRIMARY KEY metric_name
ORDER BY (metric_name, id)
SETTINGS allow_dimensions_outside_sorting_key = 1, index_granularity = 8192

CREATE TABLE default.`.inner_id.metricfamilies.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `metric_family_name` String,
    `type` LowCardinality(String),
    `unit` LowCardinality(String),
    `help` String
)
ENGINE = ReplacingMergeTree
ORDER BY metric_family_name
SETTINGS index_granularity = 8192

​

إنشاء جدول AS جدول موجود

تنشئ العبارة CREATE TABLE new_table AS existing_table جدول TimeSeries مهيأً على غرار existing_table، الذي يجب أن يكون بدوره جدول TimeSeries. لا تُنسخ الأهداف الخارجية لـ existing_table؛ إذ يجب أن تعرّفها العبارة بنفسها.

تنسخ العبارة من existing_table:

• عبارة SETTINGS، باستثناء version: يحصل الجدول الجديد دائمًا على أحدث إصدار. تُدمج الإعدادات المكتوبة في العبارة نفسها مع الإعدادات المنسوخة بحسب الاسم، لذا يتقدم الإعداد المكتوب على الإعداد المنسوخ، ويؤدي name = DEFAULT إلى إعادة ضبط إعداد منسوخ إلى قيمته الافتراضية؛
• عبارتا INNER COLUMNS وINNER ENGINE لكل جدول داخلي. يُحتفظ بالأعمدة المخصصة (مثل الأعمدة الإضافية والأعمدة التي تحتوي على برنامج ترميز الضغط أو تعبير DEFAULT) وأجزاء المحرك المخصصة (مثل محرك ذي arguments أو sorting key مخصص أو إعداد للمحرك)، بينما تُضبط الأعمدة وأجزاء المحرك الأخرى وفقًا لإعدادات الجدول الجديد، بحيث تسري، على سبيل المثال، قيم tags_to_columns أو aggregate_min_time_and_max_time أو tags_index_granularity المكتوبة في العبارة.

تُؤخذ أيضًا أنواع أعمدة id والطابع الزمني والقيمة، ونوع النسخ المتماثل للمحركات الداخلية (MergeTree، ReplicatedMergeTree أو SharedMergeTree) من existing_table، ما لم تعرّفها العبارة بنفسها. تُعاد إنشاء قائمة الأعمدة الخارجية ولا تُنسخ.

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

​

ضبط أنواع الأعمدة

يمكنك ضبط أنواع الأعمدة في الجداول الهدف الداخلية باستخدام عبارة INNER COLUMNS. على سبيل المثال، لتخزين الطوابع الزمنية بالميكروثانية والقيم كـ Float32، استخدم:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(6) CODEC(Delta, T64, ZSTD(3)), value Float32 CODEC(ALP, ZSTD(3)))

يعني تحديد الأعمدة الداخلية دون برامج ترميز الضغط استخدام برنامج ترميز الضغط الافتراضي لها:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(6), value Float32)

​

العمود id

يحتوي العمود id على معرّفات، ويُحتسب كل معرّف استنادًا إلى تركيبة من اسم المقياس والوسوم. يمكن تخصيص النوع وتعبير DEFAULT المستخدم لتوليد المعرّفات عبر العبارة TAGS INNER COLUMNS:

CREATE TABLE my_table ENGINE=TimeSeries
TAGS INNER COLUMNS (id UInt64 DEFAULT sipHash64(tags))

يمكن أن يكون العمود id من أي نوع غير Nullable قابل للمقارنة. يجب أن تتطابق أنواع id المُعلنة في الجدولين الداخليين samples وtags.

إذا لم يتم تحديد التعبير DEFAULT للعمود id ولم يكن الإعداد id_generator مُعيَّنًا، فسيختار ClickHouse التعبير DEFAULT تلقائيًا بناءً على نوع id، ولكن فقط إذا كان نوع id أحد الأنواع UUID أو UInt64 أو UInt128 أو FixedString(16)، أو الأنواع نفسها المغلّفة بـLowCardinality، أو زوجًا من اثنين من هذه الأنواع. بالنسبة إلى هذا الزوج، يحسب التعبير المختار تلقائيًا تجزئةً لاسم المقياس في المكوّن الأول وتجزئةً لجميع الوسوم في المكوّن الثاني.

يُبقي نوع المعرّف LowCardinality، مثل Tuple(UInt64, LowCardinality(UUID))، المعرّفات مُرمَّزة بالقاموس: إذ يخزّن جدول samples قواميس صغيرة لكل كتلة مع فهارس القاموس بدلًا من تكرار المعرّف الكامل في كل صف، مما يقلل كمية البيانات التي تقرؤها الاستعلامات.

يوفّر الإعداد id_generator مستوى التخصيص نفسه من دون استخدام العبارة INNER COLUMNS:

CREATE TABLE my_table ENGINE=TimeSeries
SETTINGS id_generator = 'sipHash64(tags)'

إذا كان هذا الإعداد مُعيَّنًا، فسيُستخدم لتوليد id حتى إذا كانت قيمة DEFAULT الخاصة بالعمود تحتوي على تعبير مختلف.

يمكن أيضًا تحديد نوع العمود id في الإعداد id_type بدلًا من العبارة INNER COLUMNS:

CREATE TABLE my_table ENGINE=TimeSeries
SETTINGS id_type = 'UInt64', id_generator = 'sipHash64(tags)'

عندما يكون الإعداد id_generator مُعيَّنًا، يُسجَّل الإعداد id_type تلقائيًا عند CREATE، بحيث يحتفظ التعريف بالنوع الذي كُتب التعبير من أجله.

​

العمود tags

يحتوي العمود tags على جميع وسوم السلسلة الزمنية، بما في ذلك الوسم __name__ الذي يحتوي على اسم المقياس.

يتيح الإعداد tags_to_columns تحديد وسم معيّن لتخزينه أيضًا في عمود منفصل بالإضافة إلى الخريطة داخل العمود tags:

CREATE TABLE my_table
ENGINE = TimeSeries
SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'}

ستضيف هذه العبارة العمودين instance وjob إلى جدول الوسوم الهدف الداخلي. ستُخزَّن قيم الوسمين instance وjob في العمودين المذكورين وفي العمود tags.

في الجداول التي أنشأتها إصدارات أقدم من ClickHouse، يحتوي العمود tags على الوسوم التي لا توجد لها أعمدة مخصصة فقط، ولا يتضمن اسم المقياس، بينما يكون العمود all_tags عمودًا مؤقتًا جرى ملؤه عند الإدراج بجميع الوسوم باستثناء اسم المقياس.

​

محركات الجداول الخاصة بالجداول الهدف الداخلية

تستخدم الجداول الهدف الداخلية، افتراضيًا، محركات الجداول التالية:

• يستخدم جدول العينات محرك MergeTree;
• يستخدم جدول العينات الحديثة محرك MergeTree مقسمًا إلى حاويات زمنية مدتها 5 ساعات (راجع إعداد recent_samples_partition_by) مع قيمة TTL مشتقة من إعداد recent_samples_ttl_seconds ومع تمكين ttl_only_drop_parts، بحيث تُحذف الأجزاء المنتهية الصلاحية كاملةً؛
• يستخدم جدول الوسوم محرك AggregatingMergeTree لأن البيانات نفسها تُدرج في هذا الجدول غالبًا عدة مرات، لذا نحتاج إلى طريقة لإزالة التكرارات، وكذلك لأن التجميع مطلوب للعمودين min_time و max_time;
• يستخدم جدول عائلات المقاييس محرك ReplacingMergeTree لأن البيانات نفسها تُدرج في هذا الجدول غالبًا عدة مرات، لذا نحتاج إلى طريقة لإزالة التكرارات.

تتبع عائلة محركات الجداول الداخلية المُنشأة إعداد مستوى الاستعلام default_table_engine: فعند استخدام default_table_engine = ReplicatedMergeTree أو SharedMergeTree، تستخدم الجداول الداخلية محركات Replicated أو Shared المقابلة. ومع default_table_engine = None (أو أي قيمة أخرى)، يجب تحديد محركات الجداول الداخلية صراحةً.

يجب أن تكون جميع الجداول الداخلية من نفس نوع النسخ المتماثل: فإذا كان أحدها متماثلًا (أو مشتركًا)، يجب أن تكون الجداول الداخلية الأخرى متماثلة (أو مشتركة) أيضًا، وإلا فستتباين محتوياتها بين النسخ المتماثلة. على سبيل المثال، يتطلب تعريف SAMPLES INNER ENGINE = ReplicatedMergeTree(...) أن تكون المحركات الداخلية الأخرى متماثلة أيضًا - إما بتعريفها صراحةً أو بإنشائها باستخدام default_table_engine = ReplicatedMergeTree.

كما يمكن استخدام محركات جداول أخرى للجداول الهدف الداخلية إذا تم تحديد ذلك:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES ENGINE=ReplicatedMergeTree
RECENT SAMPLES ENGINE=ReplicatedMergeTree
TAGS ENGINE=ReplicatedAggregatingMergeTree
METRIC FAMILIES ENGINE=ReplicatedReplacingMergeTree

يُبقي جدول الوسوم أعمدة الوسوم (والـ Map tags) خارج مفتاح الفرز الخاص به، وهو ما يرفضه AggregatingMergeTree افتراضيًا (راجع allow_dimensions_outside_sorting_key). وهذا آمن هنا لأن تلك الأعمدة تعتمد وظيفيًا على id، وهو جزء من مفتاح الفرز، لذا فإن جميع الصفوف التي تدمجها عملية دمج في الخلفية معًا تتشارك القيم نفسها. وعندما يُنشأ جدول الوسوم الداخلي أو يُحدَّد محركه inline كما هو موضح أعلاه، يضبط TimeSeries القيمة allow_dimensions_outside_sorting_key = 1 عليه تلقائيًا؛ أما بالنسبة إلى جدول الوسوم التجميعي الخارجي الذي يُنشأ يدويًا، فيجب عليك تعيين هذا الإعداد بنفسك.

​

الجداول الهدف الخارجية

يمكن إعداد جدول TimeSeries لاستخدام جدول أُنشئ يدويًا:

CREATE TABLE samples_for_my_table
(
    `id` UUID,
    `timestamp` DateTime64(3),
    `value` Float64
)
ENGINE = MergeTree
ORDER BY (id, timestamp);

CREATE TABLE tags_for_my_table ...

CREATE TABLE metric_families_for_my_table ...

CREATE TABLE my_table ENGINE=TimeSeries SAMPLES samples_for_my_table TAGS tags_for_my_table METRIC FAMILIES metric_families_for_my_table;

يمكن أيضًا استخدام جدول خارجي كهدف للعينات الحديثة (العبارة RECENT SAMPLES my_recent_samples_table). يجب أن يحتوي هذا الجدول على الأعمدة نفسها الموجودة في جدول عينات خارجي، وأن يحتفظ ببيانات لمدة لا تقل عن recent_samples_ttl_seconds ثانية، وتقع مسؤولية ذلك على عاتق المستخدم.

يجب أن تتطابق أنواع أعمدة الجداول الخارجية (id وtimestamp وvalue وأعمدة <tag_value_column> المدرجة في tags_to_columns) مع ما كان جدول TimeSeries سيُنشئه داخليًا في الحالة العادية (راجع جدول العينات وجدول الوسوم وجدول عائلات المقاييس للاطلاع على قيود الأنواع). ويُبلَّغ عن أي عدم تطابق في الأنواع عند تنفيذ CREATE.

يُسجَّل نوع عمود id في جدول الوسوم الخارجي والتعبير المولِّد للمعرّفات في الإعدادين id_type وid_generator عند تنفيذ CREATE (بدءًا من الإصدار 2)، بحيث يحتفظ بهما تعريف جدول TimeSeries: على سبيل المثال، يقرأ CREATE TABLE ... AS my_table نوع id من تعريف my_table دون قراءة جداوله الهدف الخارجية. وإذا لم يُحدَّد الإعداد id_generator، فيُعيَّن إلى DEFAULT المعرَّف في عمود id للجدول الخارجي (إن وجد)، وإلا فإلى المولِّد القياسي المشتق من نوع id. ويُستخدَم التعبير المسجَّل لتوليد id حتى إذا تغيّرت قيمة DEFAULT في الجدول الخارجي لاحقًا — راجع عمود id للتفاصيل.

​

تعديل الإعدادات

يمكن تغيير إعدادَين بعد CREATE:

• id_generator
• filter_by_min_time_and_max_time

ALTER TABLE my_table MODIFY SETTING id_generator = 'sipHash64(tags)';
ALTER TABLE my_table MODIFY SETTING filter_by_min_time_and_max_time = 0;
ALTER TABLE my_table RESET SETTING filter_by_min_time_and_max_time;

لاحظ أن تغيير id_generator بعد وجود بيانات بالفعل في جدول الوسوم قد يؤدي إلى إنشاء معرّفات مختلفة لنفس تركيبة metric+tag — إذ تحتفظ الصفوف القديمة بمعرّفاتها القديمة، بينما تستخدم الصفوف الجديدة المولِّد الجديد.

ولا يمكن تغيير الإعدادات الأخرى باستخدام ALTER ... MODIFY SETTING: فمعظمها يكون مدمجًا في مخطط الجداول الداخلية عند CREATE، كما أن الإعداد version يُثبَّت تلقائيًا عند CREATE ويُعرِّف المخطط نفسه (انظر إصدارات المخطط).

​

الإعدادات

فيما يلي قائمة بالإعدادات التي يمكن تحديدها عند تعريف جدول TimeSeries:

الاسم	النوع	الافتراضي	الوصف
id_type	نوع البيانات	يعتمد على العمود id	نوع العمود id في جداول الهدف. عادةً يُعلَن النوع في عبارات INNER COLUMNS للجداول الداخلية أو في جدول وسوم خارجي؛ ويُسجّل الإعداد تلقائيًا وقت CREATE إذا لم يكن النوع محفوظًا في التعريف بطريقة أخرى: أي إذا كان هدف الوسوم جدولًا خارجيًا، أو إذا كان الإعداد id_generator معيّنًا. كما يمكن تحديد الإعداد صراحةً بدلًا من TAGS INNER COLUMNS (id <type>). يتطلب أن تكون version 2 على الأقل
id_generator	Expression	يعتمد على نوع id	تعبير يحسب معرّف (بصمة) السلسلة الزمنية من وسومها. إذا لم يتم تعيينه، فسيُستخدم التعبير الافتراضي للعمود id. وإذا كان التعبير الافتراضي للعمود id غير معيّن أيضًا، فسيُختار التعبير تلقائيًا. بالنسبة لجدول وسوم خارجي، يُسجَّل الإعداد تلقائيًا وقت CREATE إذا كانت version 2 على الأقل (راجع جداول الهدف الخارجية)
tags_to_columns	خريطة		قيمة خريطة تحدد الوسوم التي يجب وضعها في أعمدة منفصلة في جدول الوسوم. الصياغة: {'tag1': 'column1', 'tag2' : column2, ...}
use_all_tags_column_to_generate_id	Bool	false	إعداد متقادم، لا يفعل شيئًا
store_min_time_and_max_time	Bool	true	إذا تم تعيينه إلى true، فسيخزّن الجدول min_time وmax_time لكل سلسلة زمنية
aggregate_min_time_and_max_time	Bool	true	عند إنشاء جدول tags الداخلي الهدف، يتيح هذا الخيار استخدام SimpleAggregateFunction(min, Nullable(DateTime64(3))) بدلًا من Nullable(DateTime64(3)) فقط كنوع للعمود min_time، وينطبق الأمر نفسه على العمود max_time
filter_by_min_time_and_max_time	Bool	true	إذا تم تعيينه إلى true، فسيستخدم الجدول العمودين min_time وmax_time لتصفية السلاسل الزمنية
samples_index_granularity	UInt64	32768	يضبط index_granularity لجدول العينات الداخلي. عند تعيينه صراحةً، فإنه يتجاوز index_granularity من تعريف المحرك. يُتجاهل لجدول العينات خارجي ولمحرك غير MergeTree
recent_samples_ttl_seconds	UInt64	345600	مدة الاحتفاظ بجدول الهدف الإضافي recent samples، الذي تُكتب إليه أيضًا كل عينة مُدرجة. يحصل جدول العينات الحديثة الداخلي دائمًا على TTL toDateTime(timestamp) + toIntervalSecond(recent_samples_ttl_seconds) مشتق من هذا الإعداد (متجاوزًا أي TTL من تعريف المحرك)؛ ويجب أن يحتفظ جدول العينات الحديثة الخارجي ببيانات لهذه المدة من الثواني على الأقل. تفضّل الاستعلامات التي يقع نطاقها الزمني ضمن نافذة TTL جدول العينات الحديثة على جدول العينات الرئيسي (راجع الإعداد على مستوى الاستعلام time_series_prefer_recent_samples_table). القيمة الافتراضية هي 4 أيام؛ وتُثبّت القيمة الفعلية في تعريف الجدول وقت CREATE. عيّنه إلى 0 لتعطيل جدول العينات الحديثة
recent_samples_partition_by	Expression	toStartOfInterval(toDateTime(timestamp), toIntervalHour(5))	مفتاح التقسيم لجدول recent samples الداخلي، مثلًا toStartOfHour(timestamp). عند تعيينه صراحةً، فإنه يتجاوز مفتاح التقسيم من تعريف المحرك؛ وإذا لم يُعيّن أي منهما، فسيُستخدم قسم واحد لكل 5 ساعات. يُتجاهل لجدول العينات الحديثة خارجي. يتطلب أن تكون recent_samples_ttl_seconds غير صفرية
recent_samples_index_granularity	UInt64	8192	يضبط index_granularity لجدول recent samples الداخلي. عند تعيينه صراحةً، فإنه يتجاوز index_granularity من تعريف المحرك. يُتجاهل لجدول العينات الحديثة خارجي ولمحرك غير MergeTree. يتطلب أن تكون recent_samples_ttl_seconds غير صفرية
tags_index_granularity	UInt64	8192	يضبط index_granularity لجدول الوسوم الداخلي. عند تعيينه صراحةً، فإنه يتجاوز index_granularity من تعريف المحرك. يُتجاهل لجدول الوسوم خارجي ولمحرك غير MergeTree
version	UInt64	5	إصدار الجدول: يحدد مجموعة جداول الهدف وبنيتها. يُثبّت الإصدار تلقائيًا عند إنشاء الجدول ولا يمكن تغييره بعد ذلك، وعادةً ينبغي حذفه من استعلام CREATE TABLE (راجع إصدارات المخطط)

​

إصدارات المخطط

لا يزال محرك الجدول TimeSeries وطبقة تنفيذ PromQL قيد التطوير النشط: فمجموعة الجداول الهدف وبنيتها قد تتغيّر بين إصدارات ClickHouse. ولجعل مثل هذه التغييرات قابلة للاكتشاف، يخزّن كل جدول TimeSeries إصداره في الإعداد version. ويُثبَّت الإصدار تلقائيًا في استعلام CREATE عند إنشاء الجدول - وقيمته هي أحدث إصدار معروف للخادم (حاليًا 5) - ويبقى محفوظًا في بيانات الجدول الوصفية، ولا يمكن تغييره باستخدام ALTER. أما الجداول التي أُنشئت قبل أن يُضاف هذا الإعداد فتُعدّ من الإصدار 0. وفي الأحوال العادية يُستحسن إغفال هذا الإعداد في استعلام CREATE TABLE، فيحصل الجدول عندئذٍ على أحدث إصدار. ويُقبل تحديد version صراحةً إذا كان الخادم يدعم ذلك الإصدار؛ عندئذٍ يُعرَّف الجدول بالطريقة التي يعتمدها ذلك الإصدار (انظر سجل الإصدارات). ولا ينسخ CREATE TABLE ... AS other_table إصدار الجدول الآخر، انظر إنشاء جدول AS جدول موجود.

يدعم الخادم نطاقًا من الإصدارات، وقد يختلف الحد الأدنى للإصدار بين القراءة عبر SELECT، والكتابة عبر INSERT أو بروتوكول remote-write الخاص بـ Prometheus، وتقييم PromQL (دوال الجداول prometheusQuery وprometheusQueryRange وtimeSeriesSelector، ولهجة promql، وواجهة برمجة تطبيقات الاستعلام عبر HTTP الخاصة بـ Prometheus):

• إذا كان إصدار جدول TimeSeries أقدم مما يدعمه PromQL، تُرفض استعلامات PromQL التي تجري عليه. ويقترح الاستثناء إعادة إنشاء الجدول: أنشئ جدول TimeSeries جديدًا، وانسخ البيانات باستعلام INSERT ... SELECT، ثم استبدل الجدول القديم بالجديد.
• إذا كان الإصدار أقدم من أن يُكتب فيه، تُرفض استعلامات INSERT وبروتوكول remote-write الخاص بـ Prometheus، بينما تظل استعلامات SELECT تعمل.
• وإذا كان الإصدار أقدم من أن يدعمه الخادم أصلًا، يُرفض كل استعلام على الجدول (باستثناء SHOW CREATE TABLE وDETACH وDROP).

​

سجل الإصدارات

الإصدار	التغييرات
0	الجداول التي أُنشئت قبل إضافة الإعداد version، بما فيها جداول “prealpha” (التي كانت تُعلن أعمدة الجداول الهدف كـأعمدة خارجية) والجداول التي لا تحتوي على جدول العينات الحديثة
1	أُضيف الإعداد version
2	أُضيف الإعداد id_type: الجدول الذي له جدول الوسوم الخارجي يسجّل نوع العمود id في id_type، والتعبير المولِّد للمعرّفات في id_generator، بحيث لا يعتمد تعريفه على الجدول الخارجي. ويُسجَّل id_type أيضًا عند ضبط id_generator (انظر العمود id)
3	أُعيدت تسمية العمود الخارجي time_series إلى samples (انظر الأعمدة الخارجية). تحتفظ جداول الإصدارات الأقدم بالاسم القديم للعمود، وتُعيد دالتا الجداول prometheusQuery وprometheusQueryRange العمود بالاسم الذي يستخدمه الجدول. أما البيانات المخزَّنة فلم تتغيّر
4	أُعيدت تسمية جدول الهدف metrics إلى عائلة المقياس: يُسمّى الجدول الداخلي .inner_id.metricfamilies.<uuid> بدلًا من .inner_id.metrics.<uuid>، ويُكتب التعريف بالكلمة المفتاحية METRIC FAMILIES بدلًا من METRICS. أما البيانات المخزَّنة فلم تتغيّر
5	جداول الوسوم الداخلية الجديدة التي تستخدم محركًا من عائلة MergeTree تحصل افتراضيًا على فهرس نصي keyValuePairs على الخريطة tags (انظر جدول الوسوم)

​

الدوال

فيما يلي قائمة بالدوال التي تقبل جدول TimeSeries كوسيطة:

• timeSeriesSamples
• timeSeriesTags
• timeSeriesMetricFamilies