}`. مرِّر القيم في قاموس بايثون.
استخدم `None` في بايثون للقيم القابلة لأن تكون NULL. القيم المتداخلة `None` مدعومة داخل معاملات `Array` و`Tuple`، وداخل القيم الحرفية `Map` عندما يُضبط `dict_parameter_format` على `"map"`.
* الربط من جهة الخادم باستخدام قاموس بايثون، وقيمة DateTime، وقيمة نصية
```python theme={null}
import datetime
my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)
parameters = {
"table": "my_table",
"v1": my_date,
"v2": "a string with a single quote'",
}
client.query(
"SELECT * FROM {table:Identifier} "
"WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}",
parameters=parameters,
)
```
وهذا يكافئ:
```sql theme={null}
SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
AND string ILIKE 'a string with a single quote\''
```
الربط من جهة الخادم مدعوم في استعلامات `SELECT` فقط. ولا يعمل مع `ALTER` أو `DELETE` أو `INSERT` أو أي نوع آخر من العبارات.
#### الربط من جهة العميل
يدعم ClickHouse Connect أيضًا ربط المعلمات من جهة العميل، ما يتيح مرونة أكبر عند إنشاء استعلامات SQL المعتمدة على القوالب. بالنسبة إلى الربط من جهة العميل، يجب أن تكون وسيطة `parameters` قاموسًا أو تسلسلًا. ويستخدم الربط من جهة العميل تنسيق السلاسل بأسلوب ["printf"](https://docs.python.org/3/library/stdtypes.html#old-string-formatting) في بايثون لإجراء استبدال المعلمات.
لاحظ أنه، بخلاف الربط من جهة الخادم، لا يعمل الربط من جهة العميل مع معرّفات قاعدة البيانات مثل أسماء قواعد البيانات أو الجداول أو الأعمدة، لأن التنسيق بأسلوب بايثون لا يستطيع التمييز بين الأنواع المختلفة من السلاسل، ولأنها تحتاج إلى تنسيق مختلف (backticks أو علامتا الاقتباس المزدوجتان لمعرّفات قاعدة البيانات، وعلامتا الاقتباس المفردتان لقيم البيانات).
* مثال باستخدام قاموس بايثون، وقيمة DateTime، وإفلات السلاسل
```python theme={null}
import datetime
my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)
parameters = {"v1": my_date, "v2": "a string with a single quote'"}
client.query(
"SELECT * FROM my_table "
"WHERE date >= %(v1)s AND string ILIKE %(v2)s",
parameters=parameters,
)
```
يؤدي ذلك إلى إنشاء الاستعلام التالي على الخادم:
```sql theme={null}
SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
AND string ILIKE 'a string with a single quote\''
```
* مثال على تسلسل في بايثون (Tuple) وFloat64 وIPv4Address
```python theme={null}
import ipaddress
parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe))
client.query(
"SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s",
parameters=parameters,
)
```
يؤدي ذلك إلى إنشاء الاستعلام التالي على الخادم:
```sql theme={null}
SELECT *
FROM some_table
WHERE metric >= 35200.44
AND ip_address = '68.61.4.254'
```
يتعامل ربط Datetime مع القيم غير المزوّدة بمنطقة زمنية على أنها وقت الساعة. ينسّق العميل قيمة `datetime` غير المزوّدة بمنطقة زمنية حرفيًا. يفسّرها ClickHouse باستخدام المنطقة الزمنية المُعلنة في عنصر نائب من جهة الخادم مثل `{dt:DateTime('Europe/Berlin')}`، ثم `session_timezone` عند تعيينها، ثم المنطقة الزمنية للخادم. تُحوَّل قيمة `datetime` المراعية للمنطقة الزمنية إلى المنطقة الزمنية المُعلنة في العنصر النائب عند وجودها، وإلا فإلى المنطقة الزمنية للخادم المُبلّغ عنها عند الاتصال. إذا كان إعداد `session_timezone` يختلف عن المنطقة الزمنية للخادم المُبلّغ عنها، فأعلن منطقة زمنية في العنصر النائب للحفاظ على اللحظة المقصودة للقيم المراعية للمنطقة الزمنية.
للتوافق المؤقت مع التحويل المحلي للمضيف الأقدم، عيّن `common.set_setting("naive_datetime_binding", "legacy")` قبل ربط المعلمات. وللحفاظ على لحظة زمنية، أرفق `tzinfo` المقصودة بقيمة `datetime` قبل تمريرها كمعلمة. تفسّر عمليات الإدراج عبر `client.insert` قيم `datetime` غير المزوّدة بمنطقة زمنية وفق المنطقة الزمنية المحلية للعملية افتراضيًا. عيّن إعداد `naive_datetime_insert` العام إلى `"server"` لتفسيرها كوقت الساعة في المنطقة الزمنية للعمود، أو في المنطقة الزمنية للخادم إذا لم تكن للعمود منطقة زمنية. راجع [كائنات datetime غير المراعية للمنطقة الزمنية](/ar/integrations/language-clients/python/advanced-inserting#timezone-naive-datetime-objects).
بالنسبة إلى العنصر النائب `{value:DateTime64(precision)}` من جهة الخادم، يحافظ النوع المُعلن تلقائيًا على دقة أجزاء الثانية، بما في ذلك داخل تلميحات `Array` و`Tuple`.
لا يحتوي الربط من جهة العميل باستخدام `%s` على نوع مُعلن. غلّف قيمة `datetime` داخل `DT64Param` عندما يجب تنسيقها بدقة أجزاء الثانية:
```python theme={null}
from datetime import datetime
from clickhouse_connect.driver.binding import DT64Param
query = "SELECT toDateTime64(%s, 6)"
parameters = [DT64Param(datetime.now())]
client.query(query, parameters=parameters)
```
ولأغراض التوافق مع الإصدارات السابقة، فإن اسم المعلمة في القاموس الذي ينتهي بـ `_64` يطلب أيضًا تنسيق DateTime64 عندما لا يكون الاسم المنتهي بهذه اللاحقة موجودًا حرفيًا في الاستعلام.
تُنسَّق معلمة `datetime.time` أو `datetime.timedelta` كقيمة حرفية `[-]HH:MM:SS[.ffffff]` لأعمدة ClickHouse `Time` و`Time64`، في أسلوبي الربط كليهما وداخل قيم `Array` و`Tuple`. يضيف العميل علامتي الاقتباس، لذا لا تضع علامات اقتباس حول العنصر النائب في الاستعلام. قد تكون قيمة `timedelta` سالبة وقد تتجاوز 24 ساعة. تحتفظ قيمة `Timedelta` من pandas بالنانوثواني الخاصة بها وتُنسَّق بكسر من تسع خانات لـ `Time64(9)`. تُتجاهل معلومات المنطقة الزمنية في قيمة `time` المراعية للمنطقة الزمنية لأن ClickHouse `Time` لا يحتوي على منطقة زمنية.
### وسيطة Settings
تقبل جميع طُرق `insert` و`select` الأساسية في ClickHouse Connect Client وسيطةً اختيارية باسم `settings` لتمرير [إعدادات المستخدم](/ar/reference/settings/session-settings) الخاصة بخادم ClickHouse لعبارة SQL المضمَّنة. يجب أن تكون وسيطة `settings` قاموسًا. ويجب أن يتكوّن كل عنصر من اسم إعداد في ClickHouse والقيمة المرتبطة به. لاحظ أن القيم ستُحوَّل إلى سلاسل نصية عند إرسالها إلى الخادم كمعلمات استعلام.
وكما هو الحال مع الإعدادات على مستوى العميل، سيتجاهل ClickHouse Connect أي إعدادات يضع الخادم عليها العلامة *readonly*=*1*، مع تسجيل رسالة في السجل بذلك. أما الإعدادات التي تنطبق فقط على الاستعلامات عبر ClickHouse HTTP interface فتكون صالحة دائمًا. وتجد وصف هذه الإعدادات ضمن واجهة برمجة تطبيقات `get_client` [واجهة برمجة تطبيقات](#settings-argument).
مثال على استخدام إعدادات ClickHouse:
```python theme={null}
settings = {
"merge_tree_min_rows_for_concurrent_read": 65535,
"session_id": "session_1234",
"use_skip_indexes": False,
}
client.query(
"SELECT event_type, sum(timeout) "
"FROM event_errors WHERE event_time > '2022-08-01'",
settings=settings,
)
```
## طريقة `command` في `Client`
استخدم `Client.command` مع التعليمات التي لا تُرجِع مجموعة بيانات جدولية، أو مع الاستعلامات التي تُرجِع قيمة بدائية واحدة أو صفًا واحدًا. وبحسب الاستجابة، فإنها تُرجِع سلسلة نصية، أو عددًا صحيحًا، أو تسلسلًا من السلاسل النصية، أو `QuerySummary`. وتُرجِع عملية القراءة التي تنتج مجموعة نتائج فارغة سلسلةً نصية فارغة.
| المعلمة | النوع | الافتراضي | الوصف |
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cmd | str | *Required* | تعليمة ClickHouse SQL تُرجِع قيمة واحدة أو صفًا واحدًا من القيم. |
| parameters | dict or sequence | *None* | راجع [وصف المعلمات](#parameters-argument). |
| data | str or bytes | *None* | بيانات اختيارية لتضمينها مع الأمر كجسم طلب POST. |
| settings | dict | *None* | راجع [وصف الإعدادات](#settings-argument-1). |
| use\_database | bool | True | استخدم قاعدة بيانات العميل (المحددة عند إنشاء العميل). وتعني False أن الأمر سيستخدم قاعدة البيانات الافتراضية في خادم ClickHouse للمستخدم المتصل. |
| external\_data | ExternalData | *None* | كائن `ExternalData` يحتوي على بيانات ملف أو بيانات ثنائية لاستخدامها مع الاستعلام. راجع [الاستعلامات المتقدمة (البيانات الخارجية)](/ar/integrations/language-clients/python/advanced-querying#external-data) |
| transport\_settings | dict | *None* | قاموس اختياري من ترويسات HTTP لتضمينها مع هذا الطلب. يُضاف كل زوج مفتاح-قيمة كترويسة HTTP (مثل `{'X-Custom-Header': 'value'}`). وهو مفيد لمصادقة الوكيل، أو تتبّع الطلبات، أو تمرير الترويسات التي تتطلبها البنية التحتية الوسيطة. |
### أمثلة الأوامر
#### عبارات DDL
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Create a table. A successful DDL returns QuerySummary.
summary = client.command(
"CREATE TABLE test_command "
"(col_1 String, col_2 DateTime) "
"ENGINE MergeTree ORDER BY tuple()"
)
print(summary.query_id())
# Show table definition
result = client.command("SHOW CREATE TABLE test_command")
print(result)
# Output:
# CREATE TABLE default.test_command
# (
# `col_1` String,
# `col_2` DateTime
# )
# ENGINE = MergeTree
# ORDER BY tuple()
# Drop table
client.command("DROP TABLE test_command")
```
#### استعلامات بسيطة تُعيد قيماً مفردة
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Single value result
count = client.command("SELECT count() FROM system.tables")
print(count)
# Server version
version = client.command("SELECT version()")
print(version)
```
#### الأوامر ذات المعلمات
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Using client-side parameters
table_name = "system"
result = client.command(
"SELECT count() FROM system.tables WHERE database = %(db)s",
parameters={"db": table_name}
)
# Using server-side parameters
result = client.command(
"SELECT count() FROM system.tables WHERE database = {db:String}",
parameters={"db": "system"}
)
```
#### الأوامر ذات الإعدادات
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Execute command with specific settings
result = client.command(
"OPTIMIZE TABLE large_table FINAL",
settings={"optimize_throw_if_noop": 1}
)
```
## طريقة `query` في Client
تسترجع `Client.query` مجموعة بيانات جدولية بتنسيق ClickHouse Native وتُرجع `QueryResult`. تُحمَّل النتيجة الكاملة في الذاكرة عند الوصول إلى إحدى خصائص النتيجة. استخدم طريقة بث للنتائج التي لا ينبغي الاحتفاظ بها في الذاكرة.
| المعلمة | النوع | الافتراضي | الوصف |
| -------------------- | ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | str | مطلوب | استعلام ClickHouse يُرجع نتيجة جدولية، وغالبًا ما يكون `SELECT` أو `DESCRIBE`. ويمكن حذفه عند توفيره بواسطة `context`. |
| `parameters` | dict or sequence | `None` | راجع [وسيط Parameters](#parameters-argument). |
| `settings` | dict | `None` | راجع [وسيط Settings](#settings-argument-1). |
| `query_formats` | dict | `None` | تنسيق القراءة حسب نوع ClickHouse. راجع [تنسيقات القراءة](/ar/integrations/language-clients/python/advanced-querying#read-formats). |
| `column_formats` | dict | `None` | تنسيق القراءة حسب عمود النتيجة، بما في ذلك تعيينات تنسيق النوع Nested. |
| `encoding` | str | `None` | ترميز أعمدة String. القيمة الافتراضية هي UTF-8. |
| `use_none` | bool | `True` | إرجاع `None` لقيمة SQL NULL. وعندما تكون القيمة false، تُرجَع القيمة الافتراضية لـ NULL لهذا النوع. تختار طرق NumPy/Pandas قيمًا افتراضية تركّز على الأداء. |
| `column_oriented` | bool | `False` | إرجاع النتيجة على هيئة أعمدة بدلًا من صفوف. |
| `use_numpy` | bool | `False` | قراءة أعمدة النتائج المتوافقة إلى مصفوفات NumPy داخل `QueryResult`. يُفضَّل `query_np` عندما تكون النتيجة المطلوبة مصفوفة NumPy واحدة. |
| `max_str_len` | int | `0` | مع `use_numpy`، استخدم `dtype` ثابت العرض من Unicode لأعمدة String حتى هذا الطول. تستخدم القيمة صفر object arrays. |
| `context` | `QueryContext` | `None` | سياق استعلام قابل لإعادة الاستخدام. تتجاوز معاملات الطريقة الصريحة قيم السياق. |
| `query_tz` | str or `tzinfo` | `None` | المنطقة الزمنية المُطبَّقة على جميع أعمدة النتائج من نوع `DateTime` و`DateTime64`. |
| `column_tzs` | dict | `None` | تعيين المنطقة الزمنية لكل عمود. |
| `external_data` | `ExternalData` | `None` | ملف خارجي أو بيانات ثنائية. راجع [البيانات الخارجية](/ar/integrations/language-clients/python/advanced-querying#external-data). |
| `transport_settings` | dict | `None` | HTTP headers تُضاف إلى هذا الطلب. |
| `tz_mode` | str | Client default | تجاوز على مستوى الاستعلام لمعالجة المنطقة الزمنية بالقيم `"naive_utc"` أو `"aware"` أو `"schema"`. |
### أمثلة على الاستعلامات
#### استعلام بسيط
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Simple SELECT query
result = client.query(
"SELECT number, toString(number) AS label FROM numbers(3)"
)
# Access results as rows
for row in result.result_rows:
print(row)
# Output:
# (0, '0')
# (1, '1')
# (2, '2')
# Access column names and types
print(result.column_names)
# Output: ('number', 'label')
print([col_type.name for col_type in result.column_types])
# Output: ['UInt64', 'String']
```
#### الوصول إلى نتائج الاستعلام
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
result = client.query("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3")
# Row-oriented access (default)
print(result.result_rows)
# Output: [(0, '0'), (1, '1'), (2, '2')]
# Column-oriented access
print(result.result_columns)
# Output: [[0, 1, 2], ['0', '1', '2']]
# Named results (list of dictionaries)
for row_dict in result.named_results():
print(row_dict)
# Output:
# {'number': 0, 'str': '0'}
# {'number': 1, 'str': '1'}
# {'number': 2, 'str': '2'}
# First row as dictionary
print(result.first_item)
# Output: {'number': 0, 'str': '0'}
# First row as tuple
print(result.first_row)
# Output: (0, '0')
```
#### استعلام باستخدام معلمات جهة العميل
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Using dictionary parameters (printf-style)
query = "SELECT * FROM system.tables WHERE database = %(db)s AND name LIKE %(pattern)s"
parameters = {"db": "system", "pattern": "%query%"}
result = client.query(query, parameters=parameters)
# Using tuple parameters
query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s"
parameters = ("system", 5)
result = client.query(query, parameters=parameters)
```
#### استعلام باستخدام معلمات على جانب الخادم
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Server-side binding (more secure, better performance for SELECT queries)
query = "SELECT * FROM system.tables WHERE database = {db:String} AND name = {tbl:String}"
parameters = {"db": "system", "tbl": "query_log"}
result = client.query(query, parameters=parameters)
```
#### الاستعلام مع الإعدادات
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Pass ClickHouse settings with the query
result = client.query(
"SELECT sum(number) FROM numbers(1000000)",
settings={
"max_block_size": 100000,
"max_execution_time": 30
}
)
```
### كائن `QueryResult`
تُرجِع طريقة `query` الأساسية كائن `QueryResult` بالخصائص العامة التالية:
* `result_rows` -- مصفوفة النتائج منظَّمة على شكل صفوف.
* `result_columns` -- مصفوفة النتائج منظَّمة على شكل أعمدة.
* `result_set` -- `result_rows` أو `result_columns`، بحسب اتجاه الاستعلام.
* `column_names` -- `Tuple` يضم أسماء أعمدة النتائج.
* `column_types` -- `Tuple` من كائنات `ClickHouseType`.
* `row_count` -- عدد صفوف النتائج المُخزَّنة فعليًا.
* `query_id` -- معرّف الاستعلام الذي تم الإبلاغ عنه أو إنشاؤه للطلب. وتعني السلسلة الفارغة عدم توفر أي معرّف.
* `summary` -- قاموس مفكوك الترميز من ترويسة الاستجابة `X-ClickHouse-Summary`.
* `first_item` -- الصف الأول على هيئة قاموس، أو `None` إذا كانت النتيجة فارغة.
* `first_row` -- الصف الأول على هيئة تسلسل، أو `None` إذا كانت النتيجة فارغة.
* `column_block_stream` و`row_block_stream` و`rows_stream` -- سياقات تدفق داخلية. استخدم بدلًا من ذلك طرق البث المقابلة في العميل.
راجع [الاستعلامات المتدفقة](/ar/integrations/language-clients/python/advanced-querying#streaming-queries) للتعرّف على واجهات برمجة التطبيقات `StreamContext` المدعومة.
## استهلاك نتائج الاستعلام باستخدام NumPy أو Pandas أو Arrow
يوفّر ClickHouse Connect طرق استعلام متخصصة لتنسيقات بيانات NumPy وPandas وArrow. للحصول على معلومات مفصلة حول استخدام هذه الطرق، بما في ذلك الأمثلة وإمكانات البث والتعامل المتقدم مع الأنواع، راجع [الاستعلام المتقدم (استعلامات NumPy وPandas وArrow)](/ar/integrations/language-clients/python/advanced-querying#numpy-pandas-and-arrow-queries).
## أساليب Client للاستعلامات المتدفقة
لبث مجموعات نتائج كبيرة، يوفّر ClickHouse Connect عدة أساليب للبث المتدفق. راجع [الاستعلامات المتقدمة (الاستعلامات المتدفقة)](/ar/integrations/language-clients/python/advanced-querying#streaming-queries) للاطلاع على التفاصيل والأمثلة.
## طريقة `insert` في `Client`
في حالة الاستخدام الشائعة المتمثلة في إدراج عدة سجلات في ClickHouse، تتوفر الطريقة `Client.insert`. وتقبل المعلمات التالية:
| Parameter | Type | Default | Description |
| -------------------- | --------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `table` | str | Required | الجدول المستهدف. ويُسمح باستخدام اسم مؤهل بقاعدة البيانات. ويمكن حذفه عند توفيره بواسطة `context`. |
| `data` | Sequence of Sequences | Required | مصفوفة بيانات موجَّهة للصفوف أو موجَّهة للأعمدة. ويمكن توفيرها لاحقًا عبر `InsertContext`. |
| `column_names` | str or Sequence\[str] | `"*"` | الأعمدة المرتبة. يؤدي `"*"` إلى تنفيذ استعلام للبيانات الوصفية لاكتشاف كل عمود قابل للإدراج. |
| `database` | str or None | Client database | قاعدة البيانات المستهدفة عندما لا يكون `table` مؤهلاً. |
| `column_types` | Sequence\[`ClickHouseType`] | `None` | أنواع الأعمدة الصريحة. وعند توفيرها، تتجنب استعلام البيانات الوصفية. |
| `column_type_names` | Sequence\[str] | `None` | أسماء أنواع ClickHouse الصريحة. وهي بديل لـ `column_types`. |
| `column_oriented` | bool | `False` | يفسِّر `data` على أنها أعمدة بدلًا من صفوف. |
| `settings` | dict | `None` | راجع [وسيطة Settings](#settings-argument-1). |
| `context` | `InsertContext` | `None` | سياق إدراج قابل لإعادة الاستخدام. راجع [InsertContexts](/ar/integrations/language-clients/python/advanced-inserting#insertcontexts). |
| `transport_settings` | dict | `None` | ترويسات HTTP تُضاف إلى هذا الطلب. |
تعيد هذه الطريقة `QuerySummary`. ويحتوي قاموس `summary` الخاص بها على القيم التي يبلّغ عنها الخادم. وتمثل `written_rows` خاصيةً تيسيرية، بينما تعيد `written_bytes()` و`query_id()` القيم المناظرة. ويؤدي فشل الإدراج إلى رفع استثناء.
للاطلاع على طرق الإدراج المتخصصة التي تعمل مع Pandas DataFrames وPyArrow Tables وDataFrames المعتمدة على Arrow، راجع [الإدراج المتقدم (طرق الإدراج المتخصصة)](/ar/integrations/language-clients/python/advanced-inserting#specialized-insert-methods).
تُعد مصفوفة NumPy أيضًا Sequence of Sequences صالحة، ويمكن استخدامها كوسيط `data` مع طريقة `insert` الأساسية، لذلك لا حاجة إلى طريقة متخصصة.
### أمثلة
تفترض الأمثلة الواردة أدناه وجود جدول `users` مسبقًا، بمخطط `(id UInt32, name String, age UInt8)`.
#### إدراج أساسي موجّه بالصفوف
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Row-oriented data: each inner list is a row
data = [
[13, "user_1", 25],
[79, "user_2", 30],
]
client.insert("users", data, column_names=["id", "name", "age"])
```
#### إدراج موجّه بالأعمدة
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Column-oriented data: each inner list is a column
data = [
[13, 79], # id column
["user_1", "user_2"], # name column
[25, 30], # age column
]
client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True)
```
#### إدراج باستخدام أنواع أعمدة صريحة
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Useful when you want to avoid a DESCRIBE query to the server
data = [
[13, "user_1", 25],
[79, "user_2", 30],
]
client.insert(
"users",
data,
column_names=["id", "name", "age"],
column_type_names=["UInt32", "String", "UInt8"],
)
```
#### الإدراج في قاعدة بيانات محددة
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
data = [
[13, "user_1", 25],
[79, "user_2", 30],
]
# Insert into a table in a specific database
client.insert(
"users",
data,
column_names=["id", "name", "age"],
database="production",
)
```
## الإدراج من الملفات
لإدراج البيانات مباشرةً من الملفات إلى جداول ClickHouse، راجع [الإدراج المتقدم (الإدراج من الملفات)](/ar/integrations/language-clients/python/advanced-inserting#file-inserts).
## واجهة برمجة التطبيقات الخام
للاطلاع على حالات الاستخدام المتقدمة التي تتطلب وصولًا مباشرًا إلى واجهات HTTP الخاصة بـ ClickHouse من دون تحويلات للأنواع، راجع [الاستخدام المتقدم (واجهة برمجة التطبيقات الخام)](/ar/integrations/language-clients/python/advanced-usage#raw-api).
## بايثون DB-API 2.0
تُنفِّذ وحدة `clickhouse_connect.dbapi` واجهة الاتصال والمُؤشِّر وفقًا للمعيار PEP 249. وهي تُعرِّف مستوى واجهة برمجة التطبيقات بأنه 2.0، و`threadsafety=2`، و`paramstyle="pyformat"`. وتوفّر الوحدة أيضًا مُنشئات الأنواع وفقًا للمعيار PEP 249، وهي `Date` و`Time` و`Timestamp` و`Binary`، والدوال `DateFromTicks` و`TimeFromTicks` و`TimestampFromTicks`.
```python theme={null}
from clickhouse_connect import dbapi
connection = dbapi.connect(
host="localhost",
username="default",
password="password",
database="default",
)
cursor = connection.cursor()
try:
cursor.execute(
"SELECT name FROM system.tables "
"WHERE database = %(database)s ORDER BY name LIMIT 5",
{"database": "system"},
)
print(cursor.description)
print(cursor.fetchall())
finally:
cursor.close()
connection.close()
```
يقبل كلٌّ من `Cursor.execute` و`Cursor.executemany` وسيطتَي الكلمات المفتاحية الإضافيتين `settings` و`query_formats`. تمرّر `settings` إعدادات ClickHouse. وتطبّق `query_formats` تنسيقات القراءة حسب نوع ClickHouse عندما تُرجع العبارة صفوفًا، باستخدام التعيين نفسه المستخدم في `Client.query`. ويستخدم `executemany` مسار الإدراج المجمّع Native الخاص ببرنامج التشغيل لعبارات `INSERT ... VALUES` المتوافقة مع تسلسل صفوف مُجسَّد. وتستهلك `fetchone` و`fetchmany` و`fetchall` النتيجة المُجسَّدة الحالية.
يستمدّ `Cursor.description` القيمة `null_ok` من نوع كل عمود في النتيجة. وتُرجع الأنواع غير القابلة للقيم الفارغة `False`، بينما تُرجع الأنواع القابلة للقيم الفارغة `True`، بما في ذلك أغلفة `Nullable` و`Variant` و`Dynamic`. وتعني `None` أن قابلية القيم الفارغة غير معروفة. عندما لا يُرجع استعلام يبدأ بـ `SELECT` أو `WITH`، مع تجاهل التعليقات البادئة، أي صفوف أو بيانات وصفية للأعمدة، يشغّل المؤشّر استعلام بيانات وصفية بـ `LIMIT 0` لملء `description`. وإذا فشل استعلام البيانات الوصفية هذا، يُترك `description` فارغًا.
لا يوفّر ClickHouse معاملات تقليدية عبر واجهة HTTP هذه. وتُعدّ `Connection.commit()` و`Connection.rollback()` عمليتَي no-op. ولا تزال [قواعد تزامن معرّف الجلسة](/ar/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids) تنطبق عند مشاركة الاتصال.
## فئات ودوال الأدوات المساعدة
توفر الوحدات التالية أدوات مساعدة عامة إضافية تستخدمها التطبيقات العميلة.
يُعرض إصدار الحزمة المثبتة في السلسلة `clickhouse_connect.__version__`.
### الاستثناءات
تُعرَّف الاستثناءات المخصّصة، بما في ذلك التسلسل الهرمي للاستثناءات في DB-API 2.0، في `clickhouse_connect.driver.exceptions`. ويوفّر كلٌّ من `DatabaseError` و`OperationalError` السمة الرقمية `code` التي تحمل رمز الخطأ في ClickHouse، والسمة `name` التي تحمل الاسم الرمزي مثل `UNKNOWN_TABLE`، بحيث يمكن للتطبيقات التفريع بناءً على `exc.code` بدلًا من تحليل الرسالة. تُضبط `code` حتى عند تعطيل `show_clickhouse_errors`، بينما تتطلب `name` تفاصيل الخطأ (`True` أو `"scrub"`). وتكون كلتاهما `None` عند عدم توفرهما، كما في أخطاء النقل. استخدم `show_clickhouse_errors="scrub"` عندما ينبغي للمستخدمين النهائيين رؤية أخطاء SQL دون معلومات عن المضيف أو إصدار الخادم. يتحكم الإعداد أيضًا في رسائل `StreamFailureError` أثناء التدفق ورسائل النقل العامة. وهو يتحكم في `str(exc)` فقط. تظل أخطاء النقل مرفقة باعتبارها `__cause__`، ويمكن أن تحتوي آثار التتبع على نص الخطأ الأصلي للمضيف أو URL أو المكتبة.
### أدوات ClickHouse SQL
يمكن استخدام الدوال والفئة DT64Param في الوحدة `clickhouse_connect.driver.binding` لبناء استعلامات ClickHouse SQL وإفلاتها بشكل صحيح. وبالمثل، يمكن استخدام الدوال في الوحدة `clickhouse_connect.driver.parser` لتحليل أسماء أنواع بيانات ClickHouse.
## حالات الاستخدام متعددة الخيوط، ومتعددة العمليات، وغير المتزامنة أو القائمة على الأحداث
للحصول على معلومات حول استخدام ClickHouse Connect في التطبيقات متعددة الخيوط، ومتعددة العمليات، وغير المتزامنة أو القائمة على الأحداث، راجع [الاستخدام المتقدم (حالات الاستخدام متعددة الخيوط، ومتعددة العمليات، وغير المتزامنة أو القائمة على الأحداث)](/ar/integrations/language-clients/python/advanced-usage#multithreaded-multiprocess-and-asyncevent-driven-use-cases).
## AsyncClient
للاطلاع على الاستخدام الأصلي لـ asyncio، راجع [الاستخدام المتقدم (AsyncClient)](/ar/integrations/language-clients/python/advanced-usage#asyncclient).
## إدارة معرّفات الجلسات في ClickHouse
للاطلاع على معلومات حول إدارة معرّفات جلسات ClickHouse في التطبيقات متعددة الخيوط أو المتزامنة، راجع [الاستخدام المتقدم (إدارة معرّفات الجلسات في ClickHouse)](/ar/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids).
## تخصيص مجمّع اتصالات HTTP
لمزيد من المعلومات حول تخصيص مجمّع اتصالات HTTP للتطبيقات الكبيرة متعددة الخيوط، راجع [الاستخدام المتقدم (تخصيص مجمّع اتصالات HTTP)](/ar/integrations/language-clients/python/advanced-usage#customizing-the-http-connection-pool).