("created_at");
// Check for null
if (!reader.IsDBNull("optional_field"))
{
var value = reader.GetString("optional_field");
}
}
```
## أفضل الممارسات
### مدة الاتصال وتجميع الاتصالات
يستخدم `ClickHouse.Driver` المكوّن `System.Net.Http.HttpClient` في الخلفية. ويحتوي `HttpClient` على تجمّع اتصالات لكل `endpoint`. ونتيجة لذلك:
* تُمرَّر جلسات قاعدة البيانات عبر اتصالات HTTP التي يديرها تجمّع الاتصالات.
* يُعيد التجمّع استخدام اتصالات HTTP تلقائيًا.
* قد تظل الاتصالات مفتوحة حتى بعد التخلّص من الكائنات `ClickHouseClient` أو `ClickHouseConnection`.
**الأنماط الموصى بها:**
| السيناريو | النهج الموصى به |
| --------------- | ---------------------------------------------------------------------------------------- |
| الاستخدام العام | استخدم `ClickHouseClient` بنمط singleton |
| ADO.NET / ORMs | استخدم `ClickHouseDataSource` (ينشئ اتصالات تشترك في تجمّع الاتصالات نفسه) |
| بيئات DI | سجّل `ClickHouseClient` أو `ClickHouseDataSource` بنمط singleton مع `IHttpClientFactory` |
عند استخدام `HttpClient` أو `HttpClientFactory` مخصّص، تأكد من ضبط `PooledConnectionIdleTimeout` على قيمة أقل من `keep_alive_timeout` الخاص بالخادم، لتجنّب الأخطاء الناتجة عن الاتصالات نصف المغلقة. القيمة الافتراضية لـ `keep_alive_timeout` في Cloud deployments هي 10 ثوانٍ.
تجنّب إنشاء عدة مثيلات من `ClickHouseClient` أو مثيلات `ClickHouseConnection` مستقلة من دون `HttpClient` مشترك. فكل مثيل ينشئ تجمّع الاتصالات الخاص به.
***
### التعامل مع DateTime
1. **استخدم UTC كلما أمكن.** خزّن الطوابع الزمنية في أعمدة `DateTime('UTC')` واستخدم `DateTimeKind.Utc` في الشيفرة الخاصة بك. هذا يزيل أي التباس متعلق بالمنطقة الزمنية.
2. **استخدم `DateTimeOffset` للتعامل الصريح مع المنطقة الزمنية.** فهو يمثّل دائمًا لحظة زمنية محددة ويتضمن معلومات الإزاحة.
3. **حدّد المنطقة الزمنية في تلميحات النوع في SQL.** عند استخدام المعلمات مع قيم DateTime من النوع `Unspecified` والموجّهة إلى أعمدة غير UTC، ضمّن المنطقة الزمنية في SQL:
```csharp theme={null}
var parameters = new ClickHouseParameterCollection();
parameters.AddParameter("dt", myDateTime);
await client.ExecuteNonQueryAsync(
"INSERT INTO table (dt) VALUES ({dt:DateTime('Europe/Amsterdam')})",
parameters
);
```
***
### عمليات الإدراج غير المتزامنة
تنقل [عمليات الإدراج غير المتزامنة](/ar/concepts/features/operations/insert/asyncinserts) مسؤولية التجميع من العميل إلى الخادم. فبدلًا من اشتراط التجميع من جهة العميل، يخزّن الخادم البيانات الواردة مؤقتًا ثم يفرّغها إلى التخزين وفقًا لعتبات قابلة للتهيئة. ويكون هذا مفيدًا في السيناريوهات عالية التزامن، مثل أحمال عمل observability، حيث يرسل العديد من الوكلاء حمولات صغيرة.
فعِّل عمليات الإدراج غير المتزامنة عبر `CustomSettings` أو سلسلة الاتصال:
```csharp theme={null}
// Using CustomSettings
var settings = new ClickHouseClientSettings("Host=localhost");
settings.CustomSettings["async_insert"] = 1;
settings.CustomSettings["wait_for_async_insert"] = 1; // Recommended: wait for flush acknowledgment
// Or via connection string
// "Host=localhost;set_async_insert=1;set_wait_for_async_insert=1"
```
**وضعان** (يحددهما `wait_for_async_insert`):
| الوضع | السلوك | حالة الاستخدام |
| ------------------------- | --------------------------------------------------------------------------------- | ------------------------------------- |
| `wait_for_async_insert=1` | تعود عملية الإدراج بعد كتابة البيانات إلى القرص. وتُعاد الأخطاء إلى العميل. | **موصى به** لمعظم أحمال العمل |
| `wait_for_async_insert=0` | تعود عملية الإدراج فورًا عند تخزين البيانات مؤقتًا. لا يوجد ما يضمن حفظ البيانات. | فقط عندما يكون فقدان البيانات مقبولًا |
مع `wait_for_async_insert=0`، لا تظهر الأخطاء إلا أثناء التفريغ ولا يمكن ربطها بعملية الإدراج الأصلية. كما أن العميل لا يوفّر ضغطًا عكسيًا، مما يعرّض الخادم لخطر زيادة الحمل.
**الإعدادات الأساسية:**
| الإعداد | الوصف |
| ------------------------------- | ------------------------------------------------ |
| `async_insert_max_data_size` | فرّغ عند وصول المخزن المؤقت إلى هذا الحجم (بايت) |
| `async_insert_busy_timeout_ms` | فرّغ بعد انقضاء هذه المهلة (مللي ثانية) |
| `async_insert_max_query_number` | فرّغ بعد تراكم هذا العدد من الاستعلامات |
***
### الجلسات
لا تُفعِّل الجلسات إلا عند الحاجة إلى ميزات من جهة الخادم تحتفظ بالحالة، مثل:
* الجداول المؤقتة (`CREATE TEMPORARY TABLE`)
* الحفاظ على سياق الاستعلام عبر عدة تعليمات
* إعدادات على مستوى الجلسة (`SET max_threads = 4`)
عند تفعيل الجلسات، تُعالَج الطلبات تسلسليًا لمنع الاستخدام المتزامن للجلسة نفسها. ويضيف ذلك حملًا إضافيًا إلى أحمال العمل التي لا تتطلب حالة الجلسة.
```csharp theme={null}
var settings = new ClickHouseClientSettings
{
Host = "localhost",
UseSession = true,
SessionId = "my-session", // Optional -- will be auto-generated if not provided
};
using var client = new ClickHouseClient(settings);
await client.ExecuteNonQueryAsync("CREATE TEMPORARY TABLE temp_ids (id UInt64)");
await client.ExecuteNonQueryAsync("INSERT INTO temp_ids VALUES (1), (2), (3)");
var reader = await client.ExecuteReaderAsync(
"SELECT * FROM users WHERE id IN (SELECT id FROM temp_ids)"
);
```
**استخدام ADO.NET (للتوافق مع أطر ORM):**
```csharp theme={null}
var settings = new ClickHouseClientSettings
{
Host = "localhost",
UseSession = true,
SessionId = "my-session",
};
var dataSource = new ClickHouseDataSource(settings);
await using var connection = await dataSource.OpenConnectionAsync();
await using var cmd1 = connection.CreateCommand("CREATE TEMPORARY TABLE temp_ids (id UInt64)");
await cmd1.ExecuteNonQueryAsync();
await using var cmd2 = connection.CreateCommand("INSERT INTO temp_ids VALUES (1), (2), (3)");
await cmd2.ExecuteNonQueryAsync();
await using var cmd3 = connection.CreateCommand("SELECT * FROM users WHERE id IN (SELECT id FROM temp_ids)");
await using var reader = await cmd3.ExecuteReaderAsync();
```
## أنواع البيانات المدعومة
يدعم `ClickHouse.Driver` جميع أنواع بيانات ClickHouse. تُبيّن الجداول أدناه أوجه التوافق بين أنواع ClickHouse وأنواع .NET الأصلية عند قراءة البيانات من قاعدة البيانات.
### تعيين الأنواع: عند القراءة من ClickHouse
#### أنواع الأعداد الصحيحة
| نوع ClickHouse | نوع .NET |
| -------------- | ------------ |
| Int8 | `sbyte` |
| UInt8 | `byte` |
| Int16 | `short` |
| UInt16 | `ushort` |
| Int32 | `int` |
| UInt32 | `uint` |
| Int64 | `long` |
| UInt64 | `ulong` |
| Int128 | `BigInteger` |
| UInt128 | `BigInteger` |
| Int256 | `BigInteger` |
| UInt256 | `BigInteger` |
***
#### أنواع الأعداد ذات الفاصلة العائمة
| نوع ClickHouse | نوع .NET |
| -------------- | -------- |
| Float32 | `float` |
| Float64 | `double` |
| BFloat16 | `float` |
***
#### الأنواع العشرية
| نوع ClickHouse | نوع .NET |
| -------------- | ------------------------------- |
| Decimal(P, S) | `decimal` / `ClickHouseDecimal` |
| Decimal32(S) | `decimal` / `ClickHouseDecimal` |
| Decimal64(S) | `decimal` / `ClickHouseDecimal` |
| Decimal128(S) | `decimal` / `ClickHouseDecimal` |
| Decimal256(S) | `decimal` / `ClickHouseDecimal` |
يُتحكَّم في تحويل النوع Decimal من خلال الإعداد UseCustomDecimals.
***
#### نوع Boolean
| نوع ClickHouse | نوع .NET |
| -------------- | -------- |
| Bool | `bool` |
***
#### أنواع السلاسل النصية
| نوع ClickHouse | نوع .NET |
| -------------- | -------- |
| String | `string` |
| FixedString(N) | `string` |
افتراضيًا، يُرجَع كلٌّ من العمودين `String` و`FixedString(N)` على هيئة `string`. عيّن `ReadStringsAsByteArrays=true` في سلسلة الاتصال لقراءتهما على هيئة `byte[]` بدلًا من ذلك. يفيد هذا عند تخزين بيانات ثنائية قد لا تكون بتنسيق UTF-8 صالح.
***
#### أنواع التاريخ والوقت
| نوع ClickHouse | نوع .NET |
| -------------- | ---------- |
| Date | `DateTime` |
| Date32 | `DateTime` |
| DateTime | `DateTime` |
| DateTime32 | `DateTime` |
| DateTime64 | `DateTime` |
| Time | `TimeSpan` |
| Time64 | `TimeSpan` |
يخزّن ClickHouse قيم `DateTime` و`DateTime64` داخليًا على هيئة طوابع زمنية Unix (بالثواني أو بوحدات أصغر من الثانية منذ حقبة Unix). وعلى الرغم من أن التخزين يكون دائمًا بتوقيت UTC، فقد تكون للأعمدة منطقة زمنية مرتبطة بها تؤثر في كيفية عرض القيم وتفسيرها.
عند قراءة قيم `DateTime`، تُضبط الخاصية `DateTime.Kind` بناءً على المنطقة الزمنية للعمود:
| تعريف العمود | قيمة `DateTime.Kind` المُعادة | ملاحظات |
| ------------------------------ | ----------------------------- | ---------------------------- |
| `DateTime('UTC')` | `Utc` | منطقة UTC زمنية محددة صراحةً |
| `DateTime('Europe/Amsterdam')` | `Unspecified` | تُطبَّق الإزاحة |
| `DateTime` | `Unspecified` | يُحفَظ الوقت المحلي كما هو |
بالنسبة إلى الأعمدة التي لا تستخدم UTC، تمثل قيمة `DateTime` المُعادة الوقت المحلي في تلك المنطقة الزمنية. استخدم `ClickHouseDataReader.GetDateTimeOffset()` للحصول على `DateTimeOffset` مع الإزاحة الصحيحة لتلك المنطقة الزمنية:
```csharp theme={null}
var reader = (ClickHouseDataReader)await connection.ExecuteReaderAsync(
"SELECT toDateTime('2024-06-15 14:30:00', 'Europe/Amsterdam')");
reader.Read();
var dt = reader.GetDateTime(0); // 2024-06-15 14:30:00, Kind=Unspecified
var dto = reader.GetDateTimeOffset(0); // 2024-06-15 14:30:00 +02:00 (CEST)
```
بالنسبة إلى الأعمدة **التي لا تتضمن** منطقة زمنية صريحة (أي `DateTime` بدلًا من `DateTime('Europe/Amsterdam')`)، يعيد برنامج التشغيل قيمة `DateTime` مع `Kind=Unspecified`. وهذا يحافظ على الوقت المحلي كما تظهره الساعة تمامًا كما هو مخزّن، من دون افتراض أي منطقة زمنية.
إذا كنت بحاجة إلى سلوكٍ مدركٍ للمنطقة الزمنية للأعمدة التي لا تتضمن مناطق زمنية صريحة، فإما أن:
1. تستخدم مناطق زمنية صريحة في تعريفات الأعمدة: `DateTime('UTC')` أو `DateTime('Europe/Amsterdam')`
2. تطبّق المنطقة الزمنية بنفسك بعد القراءة.
***
#### نوع JSON
| نوع ClickHouse | نوع .NET | ملاحظات |
| -------------- | ------------ | --------------------------------- |
| Json | `JsonObject` | الافتراضي (`JsonReadMode=Binary`) |
| Json | `string` | عند استخدام `JsonReadMode=String` |
يُحدَّد نوع الإرجاع لأعمدة JSON من خلال الإعداد `JsonReadMode`:
* **`Binary` (الافتراضي)**: يعيد `System.Text.Json.Nodes.JsonObject`. يوفّر وصولًا منظّمًا إلى بيانات JSON، لكن أنواع ClickHouse المتخصصة (مثل عناوين IP وUUIDs والقيم العشرية الكبيرة) تُحوَّل إلى تمثيلاتها النصية داخل بنية JSON.
* **`String`**: يعيد JSON الخام كسلسلة `string`. ويحافظ على تمثيل JSON كما هو تمامًا من ClickHouse، وهو ما يكون مفيدًا عندما تحتاج إلى تمرير JSON كما هو دون تحليله، أو عندما تريد التعامل مع فك التسلسل بنفسك.
```csharp theme={null}
// Configure string mode via settings
var settings = new ClickHouseClientSettings("Host=localhost")
{
JsonReadMode = JsonReadMode.String
};
// Or via connection string
// "Host=localhost;JsonReadMode=String"
```
***
#### أنواع أخرى
| نوع ClickHouse | نوع .NET |
| ----------------------- | ----------------------------------- |
| UUID | `Guid` |
| IPv4 | `IPAddress` |
| IPv6 | `IPAddress` |
| Nothing | `DBNull` |
| Dynamic | انظر الملاحظة |
| Array(T) | `T[]` |
| Tuple(T1, T2, ...) | `Tuple` / `LargeTuple` |
| Map(K, V) | `Dictionary` |
| Nullable(T) | `T?` |
| Enum8 | `string` |
| Enum16 | `string` |
| LowCardinality(T) | نفس T |
| SimpleAggregateFunction | نفس النوع الأساسي |
| Nested(...) | `Tuple[]` |
| Variant(T1, T2, ...) | انظر الملاحظة |
| QBit(T, dimension) | `T[]` |
سيُحوَّل النوعان Dynamic وVariant إلى النوع المقابل للنوع الأساسي الفعلي في كل صف.
***
#### أنواع Geometry
| نوع ClickHouse | نوع .NET |
| --------------- | ------------------------- |
| Point | `Tuple` |
| Ring | `Tuple[]` |
| LineString | `Tuple[]` |
| Polygon | `Ring[]` |
| MultiLineString | `LineString[]` |
| MultiPolygon | `Polygon[]` |
| Geometry | راجع الملاحظة |
نوع Geometry هو نوع Variant يمكن أن يحتوي على أيٍّ من أنواع Geometry. وسيُحوَّل إلى النوع المقابل.
***
### تعيين الأنواع: الكتابة إلى ClickHouse
عند إدراج البيانات، يحوّل برنامج التشغيل أنواع .NET إلى أنواع ClickHouse المقابلة لها. وتبيّن الجداول أدناه أنواع .NET المقبولة لكل نوع عمود في ClickHouse.
#### أنواع الأعداد الصحيحة
| نوع ClickHouse | أنواع .NET المقبولة | ملاحظات |
| -------------- | ----------------------------------------------------------------------------------------------------------------- | ------- |
| Int8 | `sbyte`، وأي نوع متوافق مع `Convert.ToSByte()` | |
| UInt8 | `byte`، وأي نوع متوافق مع `Convert.ToByte()` | |
| Int16 | `short`، وأي نوع متوافق مع `Convert.ToInt16()` | |
| UInt16 | `ushort`، وأي نوع متوافق مع `Convert.ToUInt16()` | |
| Int32 | `int`، وأي نوع متوافق مع `Convert.ToInt32()` | |
| UInt32 | `uint`، وأي نوع متوافق مع `Convert.ToUInt32()` | |
| Int64 | `long`، وأي نوع متوافق مع `Convert.ToInt64()` | |
| UInt64 | `ulong`، وأي نوع متوافق مع `Convert.ToUInt64()` | |
| Int128 | `BigInteger`، `decimal`، `double`، `float`، `int`، `uint`، `long`، `ulong`، وأي نوع متوافق مع `Convert.ToInt64()` | |
| UInt128 | `BigInteger`، `decimal`، `double`، `float`، `int`، `uint`، `long`، `ulong`، وأي نوع متوافق مع `Convert.ToInt64()` | |
| Int256 | `BigInteger`، `decimal`، `double`، `float`، `int`، `uint`، `long`، `ulong`، وأي نوع متوافق مع `Convert.ToInt64()` | |
| UInt256 | `BigInteger`، `decimal`، `double`، `float`، `int`، `uint`، `long`، `ulong`، وأي نوع متوافق مع `Convert.ToInt64()` | |
***
#### أنواع الأعداد ذات الفاصلة العائمة
| نوع ClickHouse | أنواع .NET المقبولة | ملاحظات |
| -------------- | ------------------------------------------------ | -------------------------------------------------- |
| Float32 | `float`، وأي نوع متوافق مع `Convert.ToSingle()` | |
| Float64 | `double`، وأي نوع متوافق مع `Convert.ToDouble()` | |
| BFloat16 | `float`، وأي نوع متوافق مع `Convert.ToSingle()` | يُقتطع إلى تنسيق bfloat16 (brain float) ذي 16 بت |
***
#### النوع المنطقي
| نوع ClickHouse | أنواع .NET المقبولة | ملاحظات |
| -------------- | ------------------- | ------- |
| Bool | `bool` | |
***
#### أنواع String
| نوع ClickHouse | أنواع .NET المقبولة | ملاحظات |
| -------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
| String | `string`, `byte[]`, `ReadOnlyMemory`, `Stream` | تُكتب الأنواع الثنائية مباشرةً؛ ويمكن أن تكون التدفقات قابلةً لـ seek أو غير قابلة له |
| FixedString(N) | `string`, `byte[]`, `ReadOnlyMemory`, `Stream` | يُرمَّز String بترميز UTF-8 ويُحشّى؛ ويجب أن تكون الأنواع الثنائية بطول N بايتات بالضبط |
***
#### أنواع التاريخ والوقت
| نوع ClickHouse | أنواع .NET المقبولة | ملاحظات |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Date | `DateTime`, `DateTimeOffset`, `DateOnly`, أنواع NodaTime | تُحوَّل إلى أيام Unix بصيغة UInt16 |
| Date32 | `DateTime`, `DateTimeOffset`, `DateOnly`, أنواع NodaTime | تُحوَّل إلى أيام Unix بصيغة Int32 |
| DateTime | `DateTime`, `DateTimeOffset`, `DateOnly`, أنواع NodaTime | انظر أدناه للاطّلاع على التفاصيل |
| DateTime32 | `DateTime`, `DateTimeOffset`, `DateOnly`, أنواع NodaTime | مثل DateTime |
| DateTime64 | `DateTime`, `DateTimeOffset`, `DateOnly`, أنواع NodaTime | تعتمد الدقة على معلمة Scale |
| Time | `TimeSpan`, `int` | تُقيَّد إلى ±999:59:59؛ ويُتعامل مع `int` على أنه ثوانٍ |
| Time64 | `TimeSpan`, `decimal`, `double`, `float`, `int`, `long`, `string` | تُحلَّل السلسلة النصية بالصيغة `[-]HHH:MM:SS[.fraction]`؛ وتُقيَّد إلى ±999:59:59.999999999 |
يراعي برنامج التشغيل `DateTime.Kind` عند كتابة القيم:
| DateTime.Kind | معلمات HTTP | Bulk |
| ------------- | --------------------------------------------------------------------- | ----------------------------------------------- |
| Utc | تُحفَظ اللحظة الزمنية كما هي | تُحفَظ اللحظة الزمنية كما هي |
| Local | تُحفَظ اللحظة الزمنية كما هي | تُحفَظ اللحظة الزمنية كما هي |
| Unspecified | يُتعامل معه كوقت محلي في المنطقة الزمنية لنوع المعلمة (UTC افتراضيًا) | يُتعامل معه كوقت محلي في المنطقة الزمنية للعمود |
تحافظ قيم `DateTimeOffset` دائمًا على اللحظة الزمنية الدقيقة.
**مثال: DateTime بتوقيت UTC (تُحفَظ اللحظة الزمنية كما هي)**
```csharp theme={null}
var utcTime = new DateTime(2024, 1, 15, 12, 0, 0, DateTimeKind.Utc);
// Stored as 12:00 UTC
// Read from DateTime('Europe/Amsterdam') column: 13:00 (UTC+1)
// Read from DateTime('UTC') column: 12:00 UTC
```
**مثال: DateTime غير محدد (التوقيت المحلي)**
```csharp theme={null}
var wallClock = new DateTime(2024, 1, 15, 14, 30, 0, DateTimeKind.Unspecified);
// Written to DateTime('Europe/Amsterdam') column: stored as 14:30 Amsterdam time
// Read back from DateTime('Europe/Amsterdam') column: 14:30
```
**التوصية:** للحصول على أبسط سلوك وأكثره قابلية للتنبؤ، استخدم `DateTimeKind.Utc` أو `DateTimeOffset` في جميع عمليات DateTime. يضمن ذلك أن تعمل شيفرتك بشكل متسق بغض النظر عن المنطقة الزمنية للخادم أو العميل أو العمود.
#### معلمات HTTP مقابل Bulk Copy
يوجد فرق مهم بين ربط معلمات HTTP وBulk Copy عند كتابة قيم DateTime من النوع `Unspecified`:
**Bulk Copy** يعرف المنطقة الزمنية للعمود المستهدف ويفسّر قيم `Unspecified` بشكل صحيح وفقًا لتلك المنطقة الزمنية.
**HTTP Parameters** لا تعرف تلقائيًا المنطقة الزمنية للعمود. يجب تحديدها في تلميح نوع SQL:
```csharp theme={null}
// CORRECT: Timezone in SQL type hint - type is extracted automatically
command.CommandText = "INSERT INTO table (dt_amsterdam) VALUES ({dt:DateTime('Europe/Amsterdam')})";
command.AddParameter("dt", myDateTime);
// INCORRECT: Without timezone hint, interpreted as UTC
command.CommandText = "INSERT INTO table (dt_amsterdam) VALUES ({dt:DateTime})";
command.AddParameter("dt", myDateTime);
// String value "2024-01-15 14:30:00" interpreted as UTC, not Amsterdam time!
```
| `DateTime.Kind` | العمود المستهدف | معلمة HTTP (مع تلميح المنطقة الزمنية) | معلمة HTTP (من دون تلميح المنطقة الزمنية) | النسخ المجمّع |
| --------------- | ---------------- | ------------------------------------- | ----------------------------------------- | -------------------------------- |
| `Utc` | UTC | تبقى اللحظة الزمنية كما هي | تبقى اللحظة الزمنية كما هي | تبقى اللحظة الزمنية كما هي |
| `Utc` | Europe/Amsterdam | تبقى اللحظة الزمنية كما هي | تبقى اللحظة الزمنية كما هي | تبقى اللحظة الزمنية كما هي |
| `Local` | أيّ قيمة | تبقى اللحظة الزمنية كما هي | تبقى اللحظة الزمنية كما هي | تبقى اللحظة الزمنية كما هي |
| `Unspecified` | UTC | يُعامَل على أنه UTC | يُعامَل على أنه UTC | يُعامَل على أنه UTC |
| `Unspecified` | Europe/Amsterdam | يُعامَل على أنه بتوقيت Amsterdam | **يُعامَل على أنه UTC** | يُعامَل على أنه بتوقيت Amsterdam |
***
#### أنواع Decimal
| نوع ClickHouse | أنواع .NET المقبولة | ملاحظات |
| -------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
| Decimal(P,S) | `decimal`، `ClickHouseDecimal`، وأي نوع متوافق مع `Convert.ToDecimal()` | يتم طرح `OverflowException` إذا تجاوزت القيمة الدقة |
| Decimal32 | `decimal`، `ClickHouseDecimal`، وأي نوع متوافق مع `Convert.ToDecimal()` | الحد الأقصى للدقة هو 9 |
| Decimal64 | `decimal`، `ClickHouseDecimal`، وأي نوع متوافق مع `Convert.ToDecimal()` | الحد الأقصى للدقة هو 18 |
| Decimal128 | `decimal`، `ClickHouseDecimal`، وأي نوع متوافق مع `Convert.ToDecimal()` | الحد الأقصى للدقة هو 38 |
| Decimal256 | `decimal`، `ClickHouseDecimal`، وأي نوع متوافق مع `Convert.ToDecimal()` | الحد الأقصى للدقة هو 76 |
***
#### نوع JSON
| ClickHouse Type | أنواع .NET المقبولة | ملاحظات |
| --------------- | ------------------------------------------- | -------------------------------------- |
| Json | `string`, `JsonObject`, `JsonNode`, أي كائن | يعتمد السلوك على إعداد `JsonWriteMode` |
يتحكم إعداد `JsonWriteMode` في السلوك عند كتابة JSON:
| نوع الإدخال | `JsonWriteMode.String` (الافتراضي) | `JsonWriteMode.Binary` |
| --------------------------- | ---------------------------------------- | ----------------------------------------------------- |
| `string` | يُمرَّر كما هو | يطرح `ArgumentException` |
| `JsonObject` | يُسلسَل عبر `ToJsonString()` | يطرح `ArgumentException` |
| `JsonNode` | يُسلسَل عبر `ToJsonString()` | يطرح `ArgumentException` |
| POCO مسجّل | يُسلسَل عبر `JsonSerializer.Serialize()` | ترميز ثنائي مع دعم تلميحات النوع وسمات المسار المخصصة |
| POCO غير مسجّل / كائن مجهول | يُسلسَل عبر `JsonSerializer.Serialize()` | يطرح `ClickHouseJsonSerializationException` |
* **`String` (الافتراضي)**: يقبل `string` و`JsonObject` و`JsonNode` أو أي كائن. تُسلسَل جميع المدخلات عبر `System.Text.Json.JsonSerializer` وتُرسل كسلاسل JSON لتحليلها على جهة الخادم. هذا هو الوضع الأكثر مرونة ويعمل من دون تسجيل النوع.
* **`Binary`**: لا يقبل إلا أنواع POCO المسجّلة. تُحوَّل البيانات إلى تنسيق JSON الثنائي الخاص بـ ClickHouse على جهة العميل مع دعم كامل لتلميحات النوع. ويتطلب استدعاء `connection.RegisterJsonSerializationType()` قبل الاستخدام. وتؤدي كتابة قيم `string` أو `JsonNode` في هذا الوضع إلى طرح `ArgumentException`.
```csharp theme={null}
// Default String mode works with any input
await client.InsertBinaryAsync(
"my_table",
new[] { "id", "data" },
new[] { new object[] { 1u, new { name = "test", value = 42 } } }
);
// Binary mode requires explicit opt-in and type registration
var settings = new ClickHouseClientSettings("Host=localhost")
{
JsonWriteMode = JsonWriteMode.Binary
};
using var client = new ClickHouseClient(settings);
client.RegisterJsonSerializationType();
```
##### أعمدة JSON محددة الأنواع
عندما يحتوي عمود JSON على تلميحات للأنواع (مثل `JSON(id UInt64, price Decimal128(2))`)، يستخدم برنامج التشغيل هذه التلميحات لتسلسل القيم مع الحفاظ الكامل على سلامة الأنواع. وهذا يحافظ على الدقة في أنواع مثل `UInt64` و`Decimal` و`UUID` و`DateTime64`، والتي قد تفقد دقتها لولا ذلك عند تسلسلها بصيغة JSON عامة.
##### تسلسل كائنات POCO
يمكن كتابة كائنات POCO في أعمدة JSON بطريقتين وفقًا لـ `JsonWriteMode`:
**String mode (الافتراضي)**: تُسلسَل كائنات POCO عبر `System.Text.Json.JsonSerializer`. لا يتطلب ذلك تسجيل الأنواع. هذا هو النهج الأبسط، كما أنه يعمل مع الكائنات المجهولة.
**Binary mode**: تُسلسَل كائنات POCO باستخدام تنسيق JSON الثنائي الخاص ببرنامج التشغيل مع دعم كامل لتلميحات النوع. يجب تسجيل الأنواع باستخدام `connection.RegisterJsonSerializationType()` قبل الاستخدام. يدعم هذا الوضع تعيينات مسارات مخصّصة عبر السمات:
* **`[ClickHouseJsonPath("path")]`**: يربط خاصيةً بمسار JSON مخصّص. ويكون ذلك مفيدًا مع البُنى المتداخلة أو عندما يختلف اسم الخاصية عن مفتاح JSON المطلوب. **يعمل فقط في Binary mode.**
* **`[ClickHouseJsonIgnore]`**: يستبعد خاصيةً من التسلسل. **يعمل فقط في Binary mode.**
```sql theme={null}
CREATE TABLE events (
id UInt32,
data JSON(`user.id` Int64, `user.name` String, Timestamp DateTime64(3))
) ENGINE = MergeTree() ORDER BY id
```
```csharp theme={null}
using ClickHouse.Driver.Json;
public class UserEvent
{
[ClickHouseJsonPath("user.id")]
public long UserId { get; set; }
[ClickHouseJsonPath("user.name")]
public string UserName { get; set; }
public DateTime Timestamp { get; set; }
[ClickHouseJsonIgnore]
public string InternalData { get; set; } // Not serialized
}
// For Binary mode: Register the type and enable Binary mode
var settings = new ClickHouseClientSettings("Host=localhost") { JsonWriteMode = JsonWriteMode.Binary };
using var client = new ClickHouseClient(settings);
client.RegisterJsonSerializationType();
// Insert POCO - serialized to JSON with nested structure via custom path attributes
await client.InsertBinaryAsync(
"events",
new[] { "id", "data" },
new[] { new object[] { 1u, new UserEvent { UserId = 123, UserName = "Alice", Timestamp = DateTime.UtcNow } } }
);
// Resulting JSON: {"user": {"id": 123, "name": "Alice"}, "Timestamp": "2024-01-15T..."}
```
مطابقة أسماء الخصائص مع تلميحات نوع العمود حسّاسة لحالة الأحرف. فالخاصية `UserId` لن تتطابق إلا مع تلميح مُعرَّف باسم `UserId`، وليس `userid`. وهذا يتوافق مع سلوك ClickHouse الذي يسمح بوجود مسارات مثل `userName` و`UserName` معًا كحقول منفصلة.
**القيود (في Binary mode فقط):**
* يجب تسجيل أنواع POCO على الاتصال باستخدام `connection.RegisterJsonSerializationType()` قبل إجراء التسلسل. وستؤدي محاولة تسلسل نوع غير مسجّل إلى ظهور الاستثناء `ClickHouseJsonSerializationException`.
* تتطلب خصائص القاموس والمصفوفة/القائمة تلميحات نوع في تعريف العمود لكي تُسلسَل بشكل صحيح. ومن دون هذه التلميحات، استخدم String mode بدلًا من ذلك.
* لا تُكتَب القيم الخالية في خصائص POCO إلا إذا كان للمسار تلميح نوع `Nullable(T)` في تعريف العمود. ولا يسمح ClickHouse بأنواع `Nullable` داخل مسارات JSON الديناميكية، لذلك يتم تخطي الخصائص الخالية غير المزوّدة بتلميحات.
* يتم تجاهل السمات `ClickHouseJsonPath` و`ClickHouseJsonIgnore` في String mode (إذ لا تعمل إلا في Binary mode).
***
#### أنواع أخرى
| نوع ClickHouse | أنواع .NET المقبولة | ملاحظات |
| ----------------------- | ------------------------------------------ | ---------------------------------------------------------------------- |
| UUID | `Guid`, `string` | تُحلَّل السلسلة النصية باعتبارها Guid |
| IPv4 | `IPAddress`, `string` | يجب أن يكون IPv4؛ وتُحلَّل السلسلة النصية باستخدام `IPAddress.Parse()` |
| IPv6 | `IPAddress`, `string` | يجب أن يكون IPv6؛ وتُحلَّل السلسلة النصية باستخدام `IPAddress.Parse()` |
| Nothing | أيّ نوع | لا يكتب شيئًا (no-op) |
| Dynamic | — | **غير مدعوم** (throws `NotImplementedException`) |
| Array(T) | `IList`, `null` | تؤدي القيمة null إلى كتابة مصفوفة فارغة |
| Tuple(T1, T2, ...) | `ITuple`, `IList` | يجب أن يتطابق عدد العناصر مع رتبة Tuple |
| Map(K, V) | `IDictionary` | |
| Nullable(T) | `null`, `DBNull`, أو الأنواع المقبولة لـ T | يكتب بايت علامة null قبل القيمة |
| Enum8 | `string`, `sbyte`, أنواع رقمية | يُبحث عن السلسلة النصية في قاموس enum |
| Enum16 | `string`, `short`, أنواع رقمية | يُبحث عن السلسلة النصية في قاموس enum |
| LowCardinality(T) | الأنواع المقبولة لـ T | يُفوَّض إلى النوع الأساسي |
| SimpleAggregateFunction | الأنواع المقبولة للنوع الأساسي | يُفوَّض إلى النوع الأساسي |
| Nested(...) | `IList` من tuples | يجب أن يتطابق عدد العناصر مع عدد الحقول |
| Variant(T1, T2, ...) | قيمة تطابق أحد T1 أو T2 أو ... | Throws `ArgumentException` إذا لم يطابق أي نوع |
| QBit(T, dim) | `IList` | يُفوَّض إلى Array؛ والبُعد بيانات وصفية فقط |
***
#### أنواع Geometry
| نوع ClickHouse | أنواع .NET المقبولة | ملاحظات |
| --------------- | -------------------------------------------------- | ---------------------------- |
| Point | `System.Drawing.Point`, `ITuple`, `IList` (عنصران) | |
| Ring | `IList` من عناصر Point | |
| LineString | `IList` من عناصر Point | |
| Polygon | `IList` من عناصر Ring | |
| MultiLineString | `IList` من عناصر LineString | |
| MultiPolygon | `IList` من عناصر Polygon | |
| Geometry | أي نوع من أنواع Geometry أعلاه | Variant لجميع أنواع Geometry |
***
#### غير مدعوم عند الكتابة
| نوع ClickHouse | ملاحظات |
| ----------------- | ------------------------------------------- |
| Dynamic | يؤدي إلى إطلاق `NotImplementedException` |
| AggregateFunction | يؤدي إلى إطلاق `AggregateFunctionException` |
***
### التعامل مع النوع Nested
يمكن قراءة النوع Nested في ClickHouse (`Nested(...)`) وكتابته باستخدام دلالات المصفوفات.
```sql theme={null}
CREATE TABLE test.nested (
id UInt32,
params Nested (param_id UInt8, param_val String)
) ENGINE = Memory
```
```csharp theme={null}
var row1 = new object[] { 1, new[] { 1, 2, 3 }, new[] { "v1", "v2", "v3" } };
var row2 = new object[] { 2, new[] { 4, 5, 6 }, new[] { "v4", "v5", "v6" } };
await client.InsertBinaryAsync(
"test.nested",
new[] { "id", "params.param_id", "params.param_val" },
new[] { row1, row2 }
);
```
## التسجيل والتشخيص
يتكامل عميل ClickHouse لـ .NET مع تجريدات `Microsoft.Extensions.Logging` لتوفير تسجيل خفيف الوزن يُفعَّل عند الحاجة. وعند تمكينه، يُصدر برنامج التشغيل رسائل منظَّمة لأحداث دورة حياة الاتصال، وتنفيذ الأوامر، وعمليات النقل، وعمليات الإدراج المجمّع. ويظل التسجيل اختياريًا بالكامل—فالتطبيقات التي لا تُعدّ مُسجِّلًا تواصل العمل دون أي عبء إضافي.
### البدء السريع
```csharp theme={null}
using ClickHouse.Driver;
using Microsoft.Extensions.Logging;
var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConsole()
.SetMinimumLevel(LogLevel.Information);
});
var settings = new ClickHouseClientSettings("Host=localhost;Port=8123")
{
LoggerFactory = loggerFactory
};
using var client = new ClickHouseClient(settings);
```
#### استخدام appsettings.json
يمكنك ضبط مستويات التسجيل باستخدام إعدادات .NET القياسية:
```csharp theme={null}
using ClickHouse.Driver;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;
var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json")
.Build();
var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConfiguration(configuration.GetSection("Logging"))
.AddConsole();
});
var settings = new ClickHouseClientSettings("Host=localhost;Port=8123")
{
LoggerFactory = loggerFactory
};
using var client = new ClickHouseClient(settings);
```
#### استخدام تهيئة داخل الذاكرة
يمكنك أيضًا ضبط مستوى تفصيل التسجيل لكل فئة في الشيفرة:
```csharp theme={null}
using ClickHouse.Driver;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;
var categoriesConfiguration = new Dictionary
{
{ "LogLevel:Default", "Warning" },
{ "LogLevel:ClickHouse.Driver.Connection", "Information" },
{ "LogLevel:ClickHouse.Driver.Command", "Debug" }
};
var config = new ConfigurationBuilder()
.AddInMemoryCollection(categoriesConfiguration)
.Build();
using var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConfiguration(config)
.AddSimpleConsole();
});
var settings = new ClickHouseClientSettings("Host=localhost;Port=8123")
{
LoggerFactory = loggerFactory
};
using var client = new ClickHouseClient(settings);
```
### الفئات والبواعث
يستخدم برنامج التشغيل فئات مخصّصة بحيث يمكنك ضبط مستويات السجل بدقة لكل مكوّن:
| الفئة | المصدر | أبرز الجوانب |
| ------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------- |
| `ClickHouse.Driver.Connection` | `ClickHouseConnection` | دورة حياة الاتصال، واختيار HTTP client factory، وفتح الاتصال وإغلاقه، وإدارة الجلسات. |
| `ClickHouse.Driver.Command` | `ClickHouseCommand` | بدء تنفيذ الاستعلام واكتماله، والتوقيت، ومعرّفات الاستعلام، وإحصاءات الخادم، وتفاصيل الخطأ. |
| `ClickHouse.Driver.Transport` | `ClickHouseConnection` | طلبات HTTP streaming منخفضة المستوى، وعلامات الضغط، ورموز حالة الاستجابة، وإخفاقات النقل. |
| `ClickHouse.Driver.Client` | `ClickHouseClient` | عمليات insert الثنائية، والاستعلامات، والعمليات الأخرى |
| `ClickHouse.Driver.NetTrace` | `TraceHelper` | تتبّع الشبكة، فقط عند تمكين وضع التصحيح |
#### مثال: تشخيص مشكلات الاتصال
```json theme={null}
{
"Logging": {
"LogLevel": {
"ClickHouse.Driver.Connection": "Trace",
"ClickHouse.Driver.Transport": "Trace"
}
}
}
```
سيُسجِّل هذا ما يلي:
* اختيار HTTP client factory (التجمّع default مقابل اتصال واحد)
* تهيئة HTTP handler (SocketsHttpHandler أو HttpClientHandler)
* إعدادات connection pool (MaxConnectionsPerServer وPooledConnectionLifetime وما إلى ذلك)
* إعدادات timeout (ConnectTimeout وExpect100ContinueTimeout وما إلى ذلك)
* تهيئة SSL/TLS
* أحداث فتح الاتصال وإغلاقه
* تتبّع معرّف الجلسة
### وضع Debug: تتبّع الشبكة والتشخيص
للمساعدة في تشخيص مشكلات الشبكة، تتضمن مكتبة برنامج التشغيل أداة مساعدة تُمكّن التتبّع منخفض المستوى للمكوّنات الداخلية للشبكات في .NET. ولتمكينه، يجب تمرير LoggerFactory مع تعيين المستوى إلى Trace، وضبط EnableDebugMode على true (أو تمكينه يدويًا عبر الصنف `ClickHouse.Driver.Diagnostic.TraceHelper`). ستُسجَّل الأحداث ضمن الفئة `ClickHouse.Driver.NetTrace`. تحذير: سيؤدي ذلك إلى إنشاء سجلات شديدة التفصيل، وسيؤثر في الأداء. لا يُنصح بتمكين وضع Debug في بيئة الإنتاج.
```csharp theme={null}
var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConsole()
.SetMinimumLevel(LogLevel.Trace); // Must be Trace level to see network events
});
var settings = new ClickHouseClientSettings()
{
LoggerFactory = loggerFactory,
EnableDebugMode = true, // Enable low-level network tracing
};
```
## OpenTelemetry
يوفّر برنامج التشغيل دعمًا مدمجًا للتتبّع الموزّع في OpenTelemetry عبر واجهة برمجة تطبيقات .NET [`System.Diagnostics.Activity`](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing). وعند تمكينه، يُنشئ برنامج التشغيل spans لعمليات قاعدة البيانات يمكن تصديرها إلى أنظمة observability الخلفية مثل Jaeger أو ClickHouse نفسه (عبر [OpenTelemetry Collector](/ar/guides/use-cases/observability/build-your-own/integrating-opentelemetry)).
### تمكين التتبّع
في تطبيقات ASP.NET Core، أضِف `ActivitySource` الخاص ببرنامج تشغيل ClickHouse إلى تهيئة OpenTelemetry:
```csharp theme={null}
builder.Services.AddOpenTelemetry()
.WithTracing(tracing => tracing
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName) // Subscribe to ClickHouse driver spans
.AddAspNetCoreInstrumentation()
.AddOtlpExporter()); // Or AddJaegerExporter(), etc.
```
لتطبيقات سطر الأوامر، أو للاختبار، أو للإعداد اليدوي:
```csharp theme={null}
using OpenTelemetry;
using OpenTelemetry.Trace;
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName)
.AddConsoleExporter()
.Build();
```
### سمات span
يتضمن كل span سمات قاعدة البيانات القياسية في OpenTelemetry، بالإضافة إلى إحصاءات query الخاصة بـ ClickHouse التي يمكن استخدامها في debugging.
| السمة | الوصف |
| ----------------------------- | ------------------------------------------ |
| `db.system` | تكون دائمًا `"clickhouse"` |
| `db.name` | اسم قاعدة البيانات |
| `db.user` | اسم المستخدم |
| `db.statement` | SQL query (إذا كان enabled) |
| `db.clickhouse.read_rows` | الصفوف التي قرأها الـ query |
| `db.clickhouse.read_bytes` | البايتات التي قرأها الـ query |
| `db.clickhouse.written_rows` | الصفوف التي كتبها الـ query |
| `db.clickhouse.written_bytes` | البايتات التي كتبها الـ query |
| `db.clickhouse.elapsed_ns` | execution time على جهة الخادم بالنانوثانية |
### خيارات التكوين
تحكَّم في سلوك التتبّع باستخدام `ClickHouseDiagnosticsOptions`:
```csharp theme={null}
using ClickHouse.Driver.Diagnostic;
// Include SQL statements in spans (default: false for security)
ClickHouseDiagnosticsOptions.IncludeSqlInActivityTags = true;
// Truncate long SQL statements (default: 1000 characters)
ClickHouseDiagnosticsOptions.StatementMaxLength = 500;
```
قد يؤدي تفعيل `IncludeSqlInActivityTags` إلى كشف بيانات حساسة ضمن التتبعات الخاصة بك. استخدمه بحذر في بيئات الإنتاج.
## إعدادات TLS
عند الاتصال بـ ClickHouse عبر HTTPS، يمكنك تهيئة سلوك TLS/SSL بعدة طرق.
### التحقق المخصص من الشهادات
بالنسبة إلى بيئات الإنتاج التي تتطلب منطقًا مخصصًا للتحقق من الشهادات، وفّر `HttpClient` خاصًا بك مع معالج `ServerCertificateCustomValidationCallback` مُعدّ:
```csharp theme={null}
using System.Net;
using System.Net.Security;
using ClickHouse.Driver;
var handler = new HttpClientHandler
{
// Required when compression is enabled (default)
AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate,
ServerCertificateCustomValidationCallback = (message, cert, chain, sslPolicyErrors) =>
{
// Example: Accept a specific certificate thumbprint
if (cert?.Thumbprint == "YOUR_EXPECTED_THUMBPRINT")
return true;
// Example: Accept certificates from a specific issuer
if (cert?.Issuer.Contains("YourOrganization") == true)
return true;
// Default: Use standard validation
return sslPolicyErrors == SslPolicyErrors.None;
},
};
var httpClient = new HttpClient(handler) { Timeout = TimeSpan.FromMinutes(5) };
var settings = new ClickHouseClientSettings
{
Host = "my.clickhouse.server",
Protocol = "https",
HttpClient = httpClient,
};
using var client = new ClickHouseClient(settings);
```
اعتبارات مهمة عند استخدام `HttpClient` مخصّص
* **فك الضغط التلقائي**: يجب تمكين `AutomaticDecompression` إذا لم يكن الضغط معطّلًا (فالضغط مفعّل افتراضيًا).
* **مهلة الخمول**: اضبط `PooledConnectionIdleTimeout` على قيمة أقل من `keep_alive_timeout` الخاص بالخادم (10 ثوانٍ في ClickHouse Cloud) لتجنّب أخطاء الاتصال الناتجة عن الاتصالات شبه المفتوحة.
## دعم ORM
تتطلب أطر ORM واجهة ADO.NET (`ClickHouseConnection`). ولإدارة دورة حياة الاتصالات على النحو الصحيح، أنشئ الاتصالات باستخدام `ClickHouseDataSource`:
```csharp theme={null}
// Register DataSource as singleton
var dataSource = new ClickHouseDataSource("Host=localhost;Username=default");
// Create connections for ORM use
await using var connection = await dataSource.OpenConnectionAsync();
// Pass connection to your ORM...
```
### Dapper
يعمل `ClickHouse.Driver` مع Dapper. ويحوّل برنامج التشغيل تلقائيًا صياغة `@parameter` الخاصة بـ Dapper إلى الصياغة الأصلية في ClickHouse `{parameter:Type}`، مع استنتاج الأنواع من قيم .NET.
استخدم `ClickHouseDataSource` لإدارة مدة بقاء الاتصال على نحو صحيح:
```csharp theme={null}
var dataSource = new ClickHouseDataSource("Host=localhost");
services.AddSingleton(dataSource); // Register as singleton in DI
using var connection = dataSource.CreateConnection();
```
#### أنماط تمرير المَعلمات
جميع أنماط مَعلمات Dapper القياسية مدعومة:
**الكائنات المجهولة:**
```csharp theme={null}
await connection.ExecuteAsync(
"INSERT INTO users (id, name, balance) VALUES (@Id, @Name, @Balance)",
new { Id = 1, Name = "alice", Balance = 3.14 });
```
**فئات POCO:**
```csharp theme={null}
class InsertParams
{
public int Id { get; set; }
public string Name { get; set; }
public double Balance { get; set; }
}
var param = new InsertParams { Id = 42, Name = "bob", Balance = 99.9 };
await connection.ExecuteAsync(
"INSERT INTO users (id, name, balance) VALUES (@Id, @Name, @Balance)", param);
```
**القاموس:**
```csharp theme={null}
var parameters = new Dictionary { { "Id", 2 } };
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id = @Id", parameters);
```
**`DynamicParameters` (من قاموس أو كائن مجهول الاسم):**
```csharp theme={null}
var dynParams = new DynamicParameters(new { Id = 1 });
// or: new DynamicParameters(new Dictionary { { "Id", 1 } });
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id = @Id", dynParams);
```
#### الاستعلام عن POCOs
يربط Dapper الأعمدة بالخصائص حسب الاسم (من دون حساسية لحالة الأحرف):
```csharp theme={null}
class User
{
public int Id { get; set; }
public string Name { get; set; }
public double Balance { get; set; }
}
// From a table
var users = (await connection.QueryAsync("SELECT id, name, balance FROM users")).ToList();
// From a literal
var row = (await connection.QueryAsync("SELECT 1 as id, 'hello' as name, 2.5 as balance")).Single();
```
#### صياغة المعلمات الأصلية في ClickHouse
عندما تحتاج إلى تحكم صريح في النوع، استخدم مباشرةً في SQL صياغة `{param:Type}` الخاصة بـ ClickHouse مع `Dictionary` لقيم المعلمات. لا تجمع بين صياغة `@param` وصياغة `{param:Type}` للمعلمة نفسها.
```csharp theme={null}
var parameters = new Dictionary { { "value", 42 } };
var result = await connection.QueryAsync("SELECT {value:Int32}", parameters);
```
#### WHERE IN
**تعمل ميزة توسيع IN المدمجة في Dapper:**
```csharp theme={null}
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id IN @Ids ORDER BY id",
new { Ids = new[] { 1, 3, 5 } });
```
يعيد Dapper صياغة ذلك إلى `WHERE id IN (@Ids1, @Ids2, @Ids3)`، ويحوّل برنامج التشغيل كل معلمة موسَّعة.
**كما تعمل الدالة `has()` في ClickHouse أيضًا مع معلمة من النوع Array:**
```csharp theme={null}
var parameters = new Dictionary { { "ids", new[] { 1, 3, 5 } } };
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE has({ids:Array(Int32)}, id) ORDER BY id",
parameters);
```
#### معالِجات الأنواع المخصّصة
تتطلّب بعض أنواع ClickHouse، مثل `ITuple` و`BigInteger` و`ClickHouseDecimal`، تسجيل معالِجات عند بدء التشغيل:
```csharp theme={null}
// ClickHouseDecimal (for Decimal64/128/256 columns)
SqlMapper.AddTypeHandler(new ClickHouseDecimalHandler());
// BigInteger (for Int128/Int256/UInt128/UInt256 columns)
SqlMapper.AddTypeHandler(new BigIntegerHandler());
// IPAddress (for IPv4/IPv6 columns)
SqlMapper.AddTypeHandler(new IpAddressHandler());
```
راجع [مثال Dapper](https://github.com/ClickHouse/clickhouse-cs/blob/main/examples/ORM/ORM_001_Dapper.cs) للاطلاع على مثال لتنفيذ معالج أنواع.
#### Dapper.Contrib
يعمل كلٌّ من `GetAll()` و`Get(id)`. أما `Insert()` فلا يعمل، إذ يولّد صياغة SQL Server (`SCOPE_IDENTITY`, `[]`). ويُوصى باستخدام الطريقة الأصلية `InsertBinaryAsync` في `ClickHouseClient` بدلًا من ذلك.
```csharp theme={null}
[Table("test.users")]
record class UserRecord(int Id, string Name, DateTime Timestamp);
var all = await connection.GetAllAsync();
var one = await connection.GetAsync(1);
```
يجب أن تتطابق أسماء الخصائص تمامًا مع أسماء أعمدة ClickHouse (تراعي حالة الأحرف).
#### القيود
| العنصر | الحالة | التفاصيل |
| ---------------------------- | --------- | ---------------------------------------------------------------------- |
| Tuple كـ **نتيجة** | يعمل | يتطلب تسجيل `SqlMapper.TypeHandler` |
| Tuple كـ **معلمة** | غير مدعوم | لا يستطيع Dapper إجراء تسلسل لـ `ITuple`/`Tuple<>` كقيمة `DbParameter` |
| أنواع Nested كمعلمة | غير مدعوم | للسبب نفسه — يرفض Dapper الأنواع المعقدة كقيم للمعلمات |
| أنواع Geo كمعلمة | غير مدعوم | Point, Ring, Polygon, LineString, MultiLineString, MultiPolygon |
| `Dapper.Contrib.Insert()` | غير مدعوم | يُنشئ صياغة خاصة بـ SQL Server |
| النوع `Nothing` | غير مدعوم | لا يوجد له تمثيل ذو معنى في .NET |
### Linq2db
يتوافق برنامج التشغيل هذا مع [linq2db](https://github.com/linq2db/linq2db)، وهو ORM خفيف الوزن وموفّر LINQ لـ .NET. راجع موقع المشروع للاطلاع على وثائق تفصيلية.
**مثال على الاستخدام:**
أنشئ `DataConnection` باستخدام موفّر ClickHouse:
```csharp theme={null}
using LinqToDB;
using LinqToDB.Data;
using LinqToDB.DataProvider.ClickHouse;
var connectionString = "Host=localhost;Port=8123;Database=default";
var options = new DataOptions()
.UseClickHouse(connectionString, ClickHouseProvider.ClickHouseDriver);
await using var db = new DataConnection(options);
```
يمكن تحديد تعيينات الجداول باستخدام السمات أو التهيئة بأسلوب Fluent. إذا كانت أسماء الفئة والخاصية لديك تطابق تمامًا أسماء الجدول والعمود، فلا حاجة إلى أي تهيئة:
```csharp theme={null}
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
}
```
**الاستعلام عن:**
```csharp theme={null}
await using var db = new DataConnection(options);
var products = await db.GetTable()
.Where(p => p.Price > 100)
.OrderByDescending(p => p.Name)
.ToListAsync();
```
**النسخ المجمّع:**
استخدم `BulkCopyAsync` لإجراء عمليات إدراج مجمّعة بكفاءة.
```csharp theme={null}
await using var db = new DataConnection(options);
var table = db.GetTable();
var options = new BulkCopyOptions
{
MaxBatchSize = 100000,
MaxDegreeOfParallelism = 1,
WithoutSession = true
};
await table.BulkCopyAsync(options, products);
```
### Entity Framework Core
موفّر Entity Framework Core الرسمي لـ ClickHouse. اربط فئات C# بجداول ClickHouse، ونفّذ الاستعلامات باستخدام LINQ، وأدرِج البيانات عبر `SaveChanges` — وكل ذلك باستخدام أنماط EF Core المألوفة.
* **NuGet**: [`ClickHouse.EntityFrameworkCore`](https://www.nuget.org/packages/ClickHouse.EntityFrameworkCore)
* **المصدر**: [GitHub](https://github.com/ClickHouse/ClickHouse.EntityFrameworkCore)
هذا الموفّر قيد التطوير النشط. يدعم الإصدار الحالي استعلامات LINQ (بما في ذلك عمليات JOIN، والاستعلامات الفرعية، وعمليات المجموعات)، و`INSERT` عبر `SaveChanges` / `BulkInsertAsync`، وعمليات الترحيل مع دعم DDL الكامل (CREATE / ALTER / DROP)، وتهيئة محرك الجدول الخاصة بـ ClickHouse. لا يدعم `UPDATE` / `DELETE`.
#### التثبيت
```bash theme={null}
dotnet add package ClickHouse.EntityFrameworkCore
```
يتطلب .NET 10.0 وEF Core 10.
#### البدء السريع
عرّف الكيان و`DbContext`، ثم أجرِ استعلامًا باستخدام LINQ:
```csharp theme={null}
using Microsoft.EntityFrameworkCore;
public class PageView
{
public long Id { get; set; }
public string Path { get; set; }
public DateOnly Date { get; set; }
public string UserAgent { get; set; }
}
public class AnalyticsContext : DbContext
{
public DbSet PageViews { get; set; }
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
=> optionsBuilder.UseClickHouse("Host=localhost;Database=analytics");
}
// Query
await using var ctx = new AnalyticsContext();
var topPages = await ctx.PageViews
.Where(v => v.Date >= new DateOnly(2024, 1, 1))
.GroupBy(v => v.Path)
.Select(g => new { Path = g.Key, Views = g.Count() })
.OrderByDescending(x => x.Views)
.Take(10)
.ToListAsync();
```
#### الأنواع المدعومة
| الفئة | أنواع ClickHouse | أنواع CLR |
| ------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **الأعداد الصحيحة** | `Int8`–`Int64`, `UInt8`–`UInt64` | `sbyte`, `short`, `int`, `long`, `byte`, `ushort`, `uint`, `ulong` |
| **الأعداد الصحيحة الكبيرة** | `Int128`, `Int256`, `UInt128`, `UInt256` | `BigInteger` |
| **الأعداد ذات الفاصلة العائمة** | `Float32`, `Float64`, `BFloat16` | `float`, `double` |
| **الأعداد العشرية** | `Decimal(P,S)`, `Decimal32(S)`, `Decimal64(S)`, `Decimal128(S)` | `decimal` أو `ClickHouseDecimal` |
| **Bool** | `Bool` | `bool` |
| **السلاسل النصية** | `String`, `FixedString(N)` | `string` |
| **التعدادات** | `Enum8(...)`, `Enum16(...)` | `string` أو `enum` في C# |
| **التاريخ/الوقت** | `Date`, `Date32`, `DateTime`, `DateTime64(P, 'TZ')` | `DateOnly`, `DateTime` |
| **الوقت** | `Time`, `Time64(N)` | `TimeSpan` |
| **UUID** | `UUID` | `Guid` |
| **الشبكة** | `IPv4`, `IPv6` | `IPAddress` |
| **المصفوفات** | `Array(T)` | `T[]`, `List`, `IList`, `ICollection`, `IReadOnlyList`, `IReadOnlyCollection`, `IEnumerable` |
| **الخرائط** | `Map(K, V)` | `Dictionary` |
| **Tuples** | `Tuple(T1, ...)` | `Tuple<...>` أو `ValueTuple<...>` |
| **Variant** | `Variant(T1, T2, ...)` | `object` |
| **Dynamic** | `Dynamic` | `object` |
| **JSON** | `Json` | `JsonNode` أو `string` |
| **الأنواع الجغرافية** | `Point`, `Ring`, `LineString`, `Polygon`, `MultiLineString`, `MultiPolygon`, `Geometry` | `Tuple` ومصفوفات منها؛ و`object` لـ `Geometry` |
| **المغلِّفات** | `Nullable(T)`, `LowCardinality(T)` | تُفك تلقائيًا |
استخدم `ClickHouseDecimal` (من `ClickHouse.Driver.Numerics`) بدلًا من `decimal` عندما تحتاج إلى الدقة الكاملة لأعمدة `Decimal128`/`Decimal256`، لأن `decimal` في .NET يقتصر على 28–29 رقمًا معنويًا.
#### عمليات LINQ المدعومة
**الاستعلامات:** `Where`, `OrderBy`, `Take`, `Skip`, `Select`, `First`, `Single`, `Any`, `All`, `Count`, `Distinct`, `AsNoTracking`
**GROUP BY والتجميع:** `GroupBy` مع `Count`, `LongCount`, `Sum`, `Average`, `Min`, `Max` — بما في ذلك `HAVING` (استخدام `.Where()` بعد `.GroupBy()`)، وإجراء عدة عمليات تجميع ضمن إسقاط واحد، واستخدام `OrderBy` على نتائج التجميع.
**عمليات JOIN:** `Join` (INNER)، وأنماط `GroupJoin`/`SelectMany` (LEFT وCROSS). تُرجِع LEFT JOIN قيمة `null` فعلية للصفوف غير المتطابقة (راجع [دلالات null في LEFT JOIN](#ef-core-join-nulls) أدناه).
**الاستعلامات الفرعية:** `Contains` / `IN` المترابطة، و`Any` / `EXISTS`، و`All`، والاستعلامات الفرعية scalar ضمن الإسقاطات.
**عمليات المجموعات:** `Concat` (→ `UNION ALL`)، و`Union` (→ `UNION DISTINCT`)، و`Intersect`، و`Except`.
**المجموعات المحلية المضمنة:** تُترجَم عمليات join و`Contains` على المجموعات الموجودة في الذاكرة (`int[]`, `List`, إلخ) إلى سلسلة من عمليات UNION.
**طرق String:** `Contains`, `StartsWith`, `EndsWith`, `IndexOf`, `Replace`, `Substring`, `Trim`/`TrimStart`/`TrimEnd`, `ToLower`, `ToUpper`, `Length`, `IsNullOrEmpty`, `Concat` (والمعامل `+`).
**الدوال الرياضية:** تُترجَم طرق `Math` و`MathF` القياسية إلى ما يقابلها في ClickHouse — بما يشمل الدوال الحسابية واللوغاريتمية والمثلثية ودوال الأدوات المساعدة.
##### دلالات NULL في LEFT JOIN
يحقن الموفّر `set_join_use_nulls=1` تلقائيًا في كل مسار اتصال لمواءمة توقّعات Entity Framework بشأن سلوك JOIN.
إذا كان خادم ClickHouse أو ملف التعريف لديك يمنع تغيير هذا الإعداد (على سبيل المثال، ملف تعريف بقيمة `readonly=1`)، فأوقِف هذا السلوك باستخدام:
```csharp theme={null}
optionsBuilder.UseClickHouse(connectionString, o => o.DisableJoinNullSemantics());
```
عند تفعيل خيار إلغاء الاشتراك، يعيد LEFT JOIN القيم الافتراضية لأعمدة ClickHouse، ولا يعود اكتشاف التنقل في EF المعتمد على `null` يعمل كما هو متوقع. استخدم مقارنات صريحة مع `0` / `""` بدلًا من `== null`.
#### إدراج البيانات
يستخدم `SaveChanges` واجهة برمجة تطبيقات `InsertBinaryAsync` الأصلية لبرنامج التشغيل — بترميز RowBinary مع ضغط GZip، وهو أكثر كفاءة بكثير من عبارات SQL ذات المعلمات:
```csharp theme={null}
await using var ctx = new AnalyticsContext();
ctx.PageViews.Add(new PageView
{
Id = 1,
Path = "/home",
Date = new DateOnly(2024, 6, 15),
UserAgent = "Mozilla/5.0"
});
await ctx.SaveChangesAsync();
```
تنتقل الكيانات من `Added` إلى `Unchanged` بعد الحفظ، تمامًا كما يحدث مع أي موفّر آخر لـ EF Core.
يمكن ضبط **حجم الدفعة** (الافتراضي 1000):
```csharp theme={null}
optionsBuilder.UseClickHouse("Host=localhost", o => o.MaxBatchSize(5000));
```
#### الإدراج المجمّع
لعمليات التحميل عالية الإنتاجية، استخدم `BulkInsertAsync` بدلًا من `SaveChanges`. هذه طريقة امتداد لـ `DbContext` تتجاوز بالكامل متتبّع التغييرات في EF Core، وآلية حلّ الهوية، وإدارة الحالة — إذ تستدعي مباشرةً `InsertBinaryAsync` الخاصة ببرنامج التشغيل باستخدام ترميز RowBinary وضغط GZip.
وهذا يجعلها مناسبة لتحميل مجموعات بيانات كبيرة عندما لا تحتاج إلى تتبّع الكيانات بعد الإدراج:
```csharp theme={null}
var events = Enumerable.Range(0, 100_000)
.Select(i => new PageView
{
Id = i,
Path = $"/page/{i}",
Date = DateOnly.FromDateTime(DateTime.Today)
});
long rowsInserted = await ctx.BulkInsertAsync(events);
```
يمكن أن يكون الإدخال أي `IEnumerable` — إذ يمر عبر الكيانات دون تحميلها جميعًا إلى الذاكرة. قيمة الإرجاع هي عدد الصفوف المُدرجة. لا تُرفَق الكيانات بـ `DbContext` بعد الإدراج، لذلك لا يحدث انتقال في الحالة من `Added` إلى `Unchanged`.
#### التعدادات
يمكن تعيين أعمدة `Enum8`/`Enum16` في ClickHouse كخصائص `string` أو كأنواع `enum` في C#. وعند استخدام تعدادات C#، يُجري الموفّر التحويل تلقائيًا بين التعداد وتمثيله النصي:
```csharp theme={null}
public enum Status { Active, Inactive, Pending }
public class User
{
public long Id { get; set; }
public Status Status { get; set; }
}
// Query with enum values
var active = await ctx.Users
.Where(u => u.Status == Status.Active)
.ToListAsync();
```
#### تحويلات الأنواع المخصّصة
يتيح لك نظام `ValueConverter` في EF Core تعيين الأنواع المخصّصة إلى أنواع يدعمها الموفّر بالفعل. ولا يرى الموفّر نوعك المخصّص مطلقًا، إذ يتولّى EF Core التحويل عند نقطة الفصل.
**التحويل على مستوى كل خاصية:**
```csharp theme={null}
public class Money
{
public decimal Amount { get; set; }
public string Currency { get; set; }
}
public class Order
{
public long Id { get; set; }
public Money Price { get; set; }
}
// In OnModelCreating:
modelBuilder.Entity()
.Property(o => o.Price)
.HasConversion(
m => $"{m.Amount}|{m.Currency}",
s => new Money
{
Amount = decimal.Parse(s.Split('|')[0]),
Currency = s.Split('|')[1]
})
.HasColumnType("String");
```
**فئة مُحوِّل قابلة لإعادة الاستخدام:**
```csharp theme={null}
public class MoneyConverter : ValueConverter
{
public MoneyConverter() : base(
m => $"{m.Amount}|{m.Currency}",
s => Parse(s)) { }
private static Money Parse(string s)
{
var parts = s.Split('|');
return new Money { Amount = decimal.Parse(parts[0]), Currency = parts[1] };
}
}
// Apply to a single property:
.HasConversion()
// Or apply to all properties of a type via conventions:
protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
configurationBuilder.Properties()
.HaveConversion();
}
```
#### تعليقات توضيحية لنوع العمود
بالنسبة إلى الأنواع القياسية مثل `string` و`int` و`DateTime` وغيرها، يستنتج الموفّر نوع ClickHouse تلقائيًا. أمّا الأنواع ذات المعلمات والأغلفة، فيلزم تحديد نوع ClickHouse صراحةً.
**استخدام التعليقات التوضيحية للبيانات (السمات):**
```csharp theme={null}
using System.ComponentModel.DataAnnotations.Schema;
using Microsoft.EntityFrameworkCore;
[Table("sensor_readings")]
public class SensorReading
{
public long Id { get; set; }
[Column(TypeName = "Array(String)")]
public string[] Tags { get; set; }
[Column(TypeName = "Map(String, String)")]
public Dictionary Metadata { get; set; }
[Column(TypeName = "Nullable(Float64)")]
public double? Value { get; set; }
[Column(TypeName = "Decimal128(18)")]
public decimal HighPrecision { get; set; }
}
```
**استخدام أسلوب fluent API في `OnModelCreating`:**
```csharp theme={null}
modelBuilder.Entity(e =>
{
e.ToTable("sensor_readings");
e.Property(x => x.Tags).HasColumnType("Array(String)");
e.Property(x => x.Metadata).HasColumnType("Map(String, String)");
e.Property(x => x.Value).HasColumnType("Nullable(Float64)");
e.Property(x => x.Category).HasColumnType("LowCardinality(String)");
e.Property(x => x.HighPrecision).HasColumnType("Decimal128(18)");
});
```
الأغلفة المتداخلة مثل `Array(Nullable(Int32))` و`LowCardinality(Nullable(String))` مدعومة — إذ يفكّ الموفّر تغليف `Nullable` و`LowCardinality` تلقائيًا عند كل مستوى من مستويات التداخل.
#### أعمدة Variant وDynamic
تُقابِل أعمدة ClickHouse `Variant(T1, T2, ...)` و`Dynamic` النوع `object` في .NET. وبما أن `object` عام جدًا بحيث لا يتيح استنتاج النوع تلقائيًا، يجب التصريح بنوع التخزين صراحةً باستخدام `.HasColumnType()`:
```csharp theme={null}
public class Event
{
public long Id { get; set; }
public object? Payload { get; set; }
}
// In OnModelCreating:
entity.Property(e => e.Payload).HasColumnType("Variant(String, UInt64, Array(UInt64))");
// or:
entity.Property(e => e.Payload).HasColumnType("Dynamic");
```
عند القراءة، يُفك تسلسل القيمة تلقائيًا إلى نوع .NET الموافق للمميِّز المخزَّن (مثل `string` و`ulong` و`ulong[]`).
#### أعمدة JSON
يدعم المزوّد نوع العمود `Json` في ClickHouse، ويعيّنه إلى `System.Text.Json.Nodes.JsonNode` (بشكل أساسي) أو `string` (عبر `ValueConverter` تلقائي):
```csharp theme={null}
using System.Text.Json.Nodes;
public class Event
{
public long Id { get; set; }
public JsonNode? Data { get; set; }
}
// In OnModelCreating:
entity.Property(e => e.Data).HasColumnType("Json");
```
تتم قراءة JSON وكتابته من خلال كلٍّ من `SaveChanges` و`BulkInsertAsync`:
```csharp theme={null}
ctx.Events.Add(new Event
{
Id = 1,
Data = JsonNode.Parse("""{"action": "click", "x": 100, "y": 200}""")
});
await ctx.SaveChangesAsync();
var ev = await ctx.Events.Where(e => e.Id == 1).SingleAsync();
string action = ev.Data!["action"]!.GetValue(); // "click"
```
إذا كنت تفضّل سلاسل JSON الخام، فاضبط الخاصية لتكون `string` مع نوع عمود `Json` — يطبّق الموفّر `ValueConverter` تلقائيًا:
```csharp theme={null}
public class Event
{
public long Id { get; set; }
public string? Data { get; set; } // raw JSON string
}
entity.Property(e => e.Data).HasColumnType("Json");
```
* **عدم ترجمة JSON path** — لا يُترجَم `entity.Data["name"]` في LINQ إلى صياغة SQL `data.name` الخاصة بـ ClickHouse. طبّق عامل التصفية على الأعمدة غير JSON وافحص JSON في الذاكرة.
* **دلالات NULL** — يعيد JSON type في ClickHouse القيمة `{}` (كائنًا فارغًا) لقيم NULL بدلًا من SQL NULL.
* **دقة الأعداد الصحيحة** — يخزّن JSON في ClickHouse جميع الأعداد الصحيحة بصيغة `Int64`. عند القراءة عبر `JsonNode`، استخدم `GetValue()` بدلًا من `GetValue()`.
#### محركات الجداول
اضبط محركات جداول ClickHouse والعبارات الخاصة بكل محرك عبر واجهة `ToTable(name, t => ...)` بأسلوب الاستدعاءات المتسلسلة. عند عدم ضبط أي محرك، يستخدم الموفّر `MergeTree` افتراضيًا، مع استمداد `ORDER BY` من المفتاح الأساسي للكيان.
```csharp theme={null}
modelBuilder.Entity(e =>
{
e.ToTable("events", t => t
.HasMergeTreeEngine()
.WithOrderBy("UserId", "Timestamp")
.WithPartitionBy("toYYYYMM(Timestamp)")
.WithPrimaryKey("UserId")
.WithSettings("index_granularity = 8192"));
});
```
عائلات المحركات المدعومة:
| المحرّك | الأسلوب المتسلسل | ملاحظات |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `MergeTree` | `HasMergeTreeEngine()` | الافتراضي عند عدم تكوين أي شيء |
| `ReplacingMergeTree` | `HasReplacingMergeTreeEngine("Version", "IsDeleted")` or `HasReplacingMergeTreeEngine(e => e.Version)` | عمودا Version وIsDeleted اختياريان |
| `SummingMergeTree` | `HasSummingMergeTreeEngine(…)` or `HasSummingMergeTreeEngine(e => new { … })` | أعمدة الجمع اختيارية |
| `AggregatingMergeTree` | `HasAggregatingMergeTreeEngine()` | — |
| `CollapsingMergeTree` | `HasCollapsingMergeTreeEngine("Sign")` or `HasCollapsingMergeTreeEngine(e => e.Sign)` | يجب أن يكون العمود `Sign` من النوع `Int8` |
| `VersionedCollapsingMergeTree` | `HasVersionedCollapsingMergeTreeEngine("Sign", "Version")` or `(e => e.Sign, e => e.Version)` | — |
| `GraphiteMergeTree` | `HasGraphiteMergeTreeEngine("config_section")` | — |
| `Log`, `TinyLog`, `StripeLog`, `Memory` | `HasLogEngine()`, `HasTinyLogEngine()`, `HasStripeLogEngine()`, `HasMemoryEngine()` | بدون ORDER BY / PARTITION BY |
**بنود المحرّك:** `WithOrderBy`, `WithPartitionBy`, `WithPrimaryKey`, `WithSampleBy`, `WithTtl`, `WithSettings`. ترتبط جميعها بمنشئ المحرّك المُعاد من `HasXxxEngine()`.
**ميزات على مستوى العمود:** `HasCodec`, `HasTtl`, `HasComment`, `HasDefault` — جميعها تدخل في عمليات الترحيل.
**فهارس تخطي البيانات** — عبر `HasIndex(...).HasSkippingIndexType(...)`:
```csharp theme={null}
modelBuilder.Entity()
.HasIndex(e => e.UserId)
.HasSkippingIndexType("minmax")
.HasGranularity(4);
// Index with parameters (e.g. bloom_filter, tokenbf_v1):
modelBuilder.Entity()
.HasIndex(e => e.Tag)
.HasSkippingIndexType("bloom_filter")
.HasSkippingIndexParams("0.01")
.HasGranularity(1);
```
يُتجاهَل الفهرس القياسي (غير القائم على تخطي البيانات) بصمت، إذ لا يوجد في ClickHouse ما يقابله. أما الفهارس الفريدة فتؤدي إلى ظهور استثناء، لأن ClickHouse لا يفرض التفرد.
#### عمليات الترحيل
سير العمل القياسي لعمليات الترحيل في EF Core:
```bash theme={null}
dotnet ef migrations add InitialCreate
dotnet ef database update
```
العمليات المدعومة:
| العملية | الناتج |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `CREATE TABLE` | يتضمن عبارة engine، وORDER BY، وPARTITION BY، وSETTINGS، ومرمّزات الأعمدة/TTL/التعليقات/القيم الافتراضية |
| `ALTER TABLE ADD COLUMN` | — |
| `ALTER TABLE DROP COLUMN` | — |
| `ALTER TABLE MODIFY COLUMN` | يعالج تغيير النوع، بالإضافة إلى إضافة/إزالة السمات (CODEC, TTL, COMMENT, DEFAULT) |
| `ALTER TABLE RENAME COLUMN` | — |
| `RENAME TABLE` | — |
| `ALTER TABLE ADD INDEX` / `DROP INDEX` | فهارس تخطي البيانات فقط |
| `CREATE DATABASE` / `DROP DATABASE` | عبر `EnsureCreated` / `EnsureDeleted` وعمليات الترحيل |
#### قيود الترحيل
| الميزة | السبب |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| المفاتيح الخارجية | لا يفرض ClickHouse المفاتيح الخارجية. ترفض عمليات الترحيل `AddForeignKey`، ويُصدر مدقق النموذج تحذيرًا عند بناء النموذج. |
| القيود الفريدة / الفهارس الفريدة | لا يفرض ClickHouse التفرد. وتؤدي الفهارس الفريدة إلى إطلاق استثناء أثناء الترحيل. |
| القيم التي ينشئها الخادم (الزيادة التلقائية / `IDENTITY`) | لا يوجد ما يقابلها في ClickHouse. |
| أعمدة `Nested(…)` | غير مدعومة بعد كنوع CLR مُعيَّن. |
| الكيانات المملوكة بصيغة JSON (`.ToJson()`) | لم يُنفَّذ بعد التعيين البنيوي لـ JSON للكيانات المملوكة. استخدم `JsonNode` / `string` في عمود `Json` بدلًا من ذلك (راجع [أعمدة JSON](#ef-core-json)). |
وبالإضافة إلى عمليات الترحيل، لا يزال الموفّر لا يدعم أيضًا ما يلي:
* **`UPDATE` / `DELETE`**
* **المعاملات**: `BeginTransaction` عملية no-op. لا يوجد دعم لمعاملات ACID في ClickHouse.
* **ترجمة استعلامات JSON path**: `entity.Data["key"]` في LINQ لا يُترجم إلى صياغة SQL الخاصة بـ ClickHouse، أي `data.key`. استخدم التصفية على أعمدة غير JSON وافحص JSON في الذاكرة.
## القيود
### أعمدة AggregateFunction
لا يمكن الاستعلام عن الأعمدة من النوع `AggregateFunction(...)` أو الإدراج فيها مباشرةً.
للإدراج:
```sql theme={null}
INSERT INTO t VALUES (uniqState(1));
```
للاختيار:
```sql theme={null}
SELECT uniqMerge(c) FROM t;
```
***