مرجع واجهة برمجة تطبيقات Python لـ chDB

تنفيذ استعلام SQL باستخدام محرك chDB.

هذه هي دالة الاستعلام الرئيسية التي تنفّذ عبارات SQL باستخدام محرك ClickHouse المضمّن. وهي تدعم تنسيقات إخراج متعددة، ويمكنها العمل مع قواعد البيانات المؤقتة أو المستندة إلى الملفات.

البنية

chdb.query(sql, output_format='CSV', path='', udf_path='')

المعلمات

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

يعيد نتيجة استعلام بالتنسيق المحدد:

الاستثناءات

أمثلة

>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"

>>> # Query with DataFrame output
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
   id    msg
0   1  hello

>>> # Query with file-based database
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")

تنفيذ استعلام SQL باستخدام محرك chDB.

هذه هي دالة الاستعلام الرئيسية التي تنفّذ عبارات SQL باستخدام محرك ClickHouse المضمّن. وهي تدعم تنسيقات إخراج متعددة، ويمكنها العمل مع قواعد بيانات مؤقتة أو مستندة إلى الملفات.

البنية

chdb.sql(sql, output_format='CSV', path='', udf_path='')

المعلمات

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

تعيد نتيجة استعلام بالتنسيق المحدد:

الاستثناءات

أمثلة

>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"

>>> # Query with DataFrame output
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
   id    msg
0   1  hello

>>> # Query with file-based database
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")

حوّل نتيجة استعلام إلى PyArrow Table.

يحوّل نتيجة استعلام chdb إلى PyArrow Table لمعالجة البيانات العمودية بكفاءة. ويُرجِع جدولًا فارغًا إذا كانت النتيجة فارغة.

البنية

chdb.to_arrowTable(res)

المعلمات

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

الأخطاء المرفوعة

مثال

>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> table = chdb.to_arrowTable(result)
>>> print(table.to_pandas())
   id    msg
0   1  hello

حوِّل نتيجة الاستعلام إلى إطار بيانات Pandas.

يحوِّل نتيجة استعلام في chDB إلى إطار بيانات Pandas عبر تحويلها أولًا إلى جدول PyArrow ثم إلى Pandas باستخدام تعدد الخيوط لتحسين الأداء.

البنية

chdb.to_df(r)

المعلمات

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

الاستثناءات

مثال

>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> df = chdb.to_df(result)
>>> print(df)
   id    msg
0   1  hello

تتوفر دوال الجلسة التالية:

أنشئ اتصالًا بخادم chDB الذي يعمل في الخلفية.

تنشئ هذه الدالة اتصالًا بمحرك قاعدة البيانات chDB ‏(ClickHouse). يُرجع كل استدعاء اتصالًا مستقلًا، ويمكن فتح أي عدد من الاتصالات بمسار قاعدة البيانات نفسه في الوقت ذاته.

chdb.connect(connection_string: str = ':memory:') → Connection

المعلمات:

التنسيقات الأساسية

مع معلمات الاستعلام

التعامل مع معلمات الاستعلام

تُمرَّر معلمات الاستعلام إلى محرك ClickHouse كوسيطات بدء تشغيل. معالجة خاصة للمعلمات:

للحصول على القائمة الكاملة للمعلمات، راجع clickhouse local --help --verbose

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

الاستثناءات

أمثلة

>>> # Temporary database
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # File-based database
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # With parameters
>>> conn = connect("data.db?mode=ro")  # Read-only mode
>>> conn = connect(":memory:?verbose&log-level=debug")  # Debug logging
>>>
>>> # Using context manager for automatic cleanup
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Connection automatically closed

انظر أيضًا

• Connection - فئة لاتصال قاعدة البيانات
• Cursor - مؤشر قاعدة بيانات لعمليات DB-API 2.0

الفئات الأساسية: Exception

الفئة الأساسية للاستثناءات المرتبطة بـ chDB.

يُرفَع هذا الاستثناء عندما يفشل تنفيذ استعلام في chDB أو عند حدوث خطأ. وهو يرث من فئة Exception القياسية في Python، ويوفّر معلومات عن الخطأ من محرك ClickHouse الداخلي.

الفئات الأساسية: object

ستحتفظ الجلسة بحالة الاستعلام. إذا كانت قيمة path هي None، فستستخدم الجلسة قاعدة البيانات المؤقتة (:memory:) المشتركة على مستوى العملية، بحيث تتمكن جميع الجلسات التي لا تحدد مسارًا من رؤية جداول بعضها بعضًا؛ ولا يُزال دليلها المؤقت إلا عند إغلاق آخر جلسة أو اتصال من هذا النوع. يمكنك أيضًا تمرير مسار لإنشاء قاعدة بيانات في ذلك المسار للاحتفاظ ببياناتك.

يمكنك أيضًا استخدام سلسلة اتصال لتمرير المسار ومعلمات أخرى.

class chdb.session.Session(path=None)

أمثلة

نظِّف موارد الجلسة مع معالجة الاستثناءات.

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

البنية

cleanup()

أمثلة

>>> session = Session("test.db")
>>> try:
...     session.query("INVALID SQL")
... finally:
...     session.cleanup()  # Safe cleanup regardless of errors

انظر أيضًا

• close() - للإغلاق الصريح للجلسة مع تمرير الأخطاء

أغلق الجلسة وحرّر الموارد.

تُغلق هذه الدالة الاتصال الأساسي وتعيد تعيين حالة الجلسة العامة. بعد استدعاء هذه الدالة، تصبح الجلسة غير صالحة ولا يمكن استخدامها لإجراء مزيد من الاستعلامات.

البنية

close()

أمثلة

>>> session = Session("test.db")
>>> session.query("SELECT 1")
>>> session.close()  # Explicitly close the session

نفِّذ استعلام SQL وأعِد النتائج.

تُنفِّذ هذه الطريقة استعلام SQL على قاعدة بيانات الجلسة وتُعيد النتائج بالتنسيق المحدد. وتدعم هذه الطريقة تنسيقات إخراج متعددة، كما تحافظ على حالة الجلسة بين الاستعلامات.

البنية

query(sql, fmt='CSV', udf_path='')

المعلمات

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

يعيد نتائج الاستعلام بالتنسيق المحدد. ويعتمد نوع القيمة المعادة الفعلي على معلمة التنسيق:

• تنسيقات السلاسل النصية (CSV وJSON وما إلى ذلك) تعيد str
• التنسيقات الثنائية (Arrow وParquet) تعيد bytes

الاستثناءات

أمثلة

>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1

>>> # Query with JSON format
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}

>>> # Complex query with table creation
>>> session.query("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>> session.query("INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob')")
>>> result = session.query("SELECT * FROM test ORDER BY id")
>>> print(result)
id,name
1,Alice
2,Bob

انظر أيضًا

• send_query() - لتنفيذ الاستعلام المتدفق
• sql - اسم مستعار لهذه الطريقة

نفّذ استعلام SQL وأعِد مكرّرًا لنتيجة متدفقة.

تُنفّذ هذه الطريقة استعلام SQL على قاعدة بيانات الجلسة وتُعيد كائن نتيجة متدفقة يتيح لك التكرار عبر النتائج دون تحميل كل شيء إلى الذاكرة دفعة واحدة. ويُعد هذا مفيدًا بشكل خاص مع مجموعات النتائج الكبيرة.

البنية

send_query(sql, fmt='CSV') → StreamingResult

المعلمات

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

الاستثناءات

أمثلة

>>> session = Session("test.db")
>>> session.query("CREATE TABLE big_table (id INT, data String) ENGINE = MergeTree() order by id")
>>>
>>> # Insert large dataset
>>> for i in range(1000):
...     session.query(f"INSERT INTO big_table VALUES ({i}, 'data_{i}')")
>>>
>>> # Stream results to avoid memory issues
>>> streaming_result = session.send_query("SELECT * FROM big_table ORDER BY id")
>>> for chunk in streaming_result:
...     print(f"Processing chunk: {len(chunk)} bytes")
...     # Process chunk without loading entire result set

>>> # Using with context manager
>>> with session.send_query("SELECT COUNT(*) FROM big_table") as stream:
...     for result in stream:
...         print(f"Count result: {result}")

راجع أيضًا

• query() - لتنفيذ الاستعلامات غير المتدفقة
• chdb.state.sqlitelike.StreamingResult - مُكرِّر النتائج المتدفقة

نفِّذ استعلام SQL وأعِد النتائج.

تُنفِّذ هذه الطريقة استعلام SQL على قاعدة بيانات الجلسة وتُعيد النتائج بالتنسيق المحدد. كما تدعم هذه الطريقة تنسيقات إخراج متعددة، وتحافظ على حالة الجلسة بين الاستعلامات.

بنية

sql(sql, fmt='CSV', udf_path='')

المعلمات

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

تُعيد نتائج الاستعلام بالتنسيق المحدد. ويعتمد نوع القيمة المعادة الفعلي على معلمة التنسيق:

• تُعيد تنسيق السلاسل النصية ‏(مثل CSV وJSON وغيرها) قيمة من النوع str
• تُعيد التنسيقات الثنائية ‏(Arrow وParquet) قيمة من النوع bytes

الاستثناءات:

أمثلة

>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1

>>> # Query with JSON format
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}

>>> # Complex query with table creation
>>> session.query("CREATE TABLE test (id INT, name String) ENGINE = MergeTree() order by id")
>>> session.query("INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob')")
>>> result = session.query("SELECT * FROM test ORDER BY id")
>>> print(result)
id,name
1,Alice
2,Bob

انظر أيضًا

• send_query() - لتنفيذ الاستعلامات المتدفقة
• sql - اسم مستعار لهذه الطريقة

أنشئ اتصالًا مع الخادم الخلفي لـ chDB.

تنشئ هذه الدالة اتصالًا بمحرك قاعدة بيانات chDB ‏(ClickHouse). يعيد كل استدعاء اتصالًا مستقلًا، ويمكن فتح أي عدد من الاتصالات إلى مسار قاعدة البيانات نفسه في الوقت ذاته.

الصياغة

chdb.state.connect(connection_string: str = ':memory:') → Connection

المعلمات

التنسيقات الأساسية

تنسيقات سلاسل الاتصال المدعومة:

مع معلمات الاستعلام

معالجة معلمات الاستعلام

تُمرَّر معلمات الاستعلام إلى محرك ClickHouse كوسيطات بدء تشغيل. توجد معالجة خاصة لبعض المعلمات:

للحصول على قائمة كاملة بالمعلمات، راجع clickhouse local --help --verbose

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

الاستثناءات

أمثلة

>>> # Temporary database
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # File-based database
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # With parameters
>>> conn = connect("data.db?mode=ro")  # Read-only mode
>>> conn = connect(":memory:?verbose&log-level=debug")  # Debug logging
>>>
>>> # Using context manager for automatic cleanup
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Connection automatically closed

انظر أيضًا

• Connection - فئة اتصال بقاعدة البيانات
• Cursor - مؤشر قاعدة البيانات لعمليات DB-API 2.0

الفئات الأساسية: object

الصياغة

class chdb.state.sqlitelike.Connection(connection_string: str)

أغلق الاتصال ونظّف الموارد.

تُغلق هذه الطريقة اتصال قاعدة البيانات وتُنظّف أي موارد مرتبطة به، بما في ذلك المؤشرات النشطة. بعد استدعاء هذه الطريقة، يصبح الاتصال غير صالح ولا يمكن استخدامه في أي عمليات لاحقة.

الصياغة

close() → None

أمثلة

>>> conn = connect("test.db")
>>> # Use connection for queries
>>> conn.query("CREATE TABLE test (id INT) ENGINE = Memory")
>>> # Close when done
>>> conn.close()

>>> # Using with context manager (automatic cleanup)
>>> with connect("test.db") as conn:
...     conn.query("SELECT 1")
...     # Connection automatically closed

أنشئ كائن Cursor لتنفيذ الاستعلامات.

تُنشئ هذه الطريقة مؤشر قاعدة بيانات يوفّر واجهة DB-API 2.0 القياسية لتنفيذ الاستعلامات وجلب النتائج. ويتيح المؤشر تحكمًا دقيقًا في تنفيذ الاستعلام واسترجاع النتائج.

الصياغة

cursor() → Cursor

يعيد

أمثلة

>>> conn = connect(":memory:")
>>> cursor = conn.cursor()
>>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
>>> cursor.execute("SELECT * FROM test")
>>> rows = cursor.fetchall()
>>> print(rows)
((1, 'Alice'),)

انظر أيضًا

• Cursor - تنفيذ لمؤشّر قاعدة البيانات

نفّذ استعلام SQL وأعِد النتائج كاملةً.

تُنفِّذ هذه الطريقة استعلام SQL بشكل متزامن وتُعيد مجموعة النتائج كاملةً. وهي تدعم تنسيقات إخراج متعددة وتُطبّق تلقائيًا المعالجة اللاحقة الخاصة بكل تنسيق.

الصياغة

query(query: str, format: str = 'CSV') → Any

المعلمات:

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

الاستثناءات

أمثلة

>>> conn = connect(":memory:")
>>>
>>> # Basic CSV query
>>> result = conn.query("SELECT 1 as num, 'hello' as text")
>>> print(result)
num,text
1,hello

>>> # DataFrame format
>>> df = conn.query("SELECT number FROM numbers(5)", "dataframe")
>>> print(df)
   number
0       0
1       1
2       2
3       3
4       4

انظر أيضًا

• send_query() - لتنفيذ الاستعلامات المتدفقة

نفّذ استعلام SQL وأعِد مكرّرًا لنتيجة متدفقة.

تنفّذ هذه الطريقة استعلام SQL وتُعيد كائن StreamingResult يتيح لك التكرار عبر النتائج دون تحميل كل شيء في الذاكرة دفعة واحدة. وهذا مثالي لمعالجة مجموعات النتائج الكبيرة.

البنية

send_query(query: str, format: str = 'CSV') → StreamingResult

المعلمات

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

الاستثناءات

أمثلة

>>> conn = connect(":memory:")
>>>
>>> # Basic streaming
>>> stream = conn.send_query("SELECT number FROM numbers(1000)")
>>> for chunk in stream:
...     print(f"Processing chunk: {len(chunk)} bytes")

>>> # Using context manager for cleanup
>>> with conn.send_query("SELECT * FROM large_table") as stream:
...     chunk = stream.fetch()
...     while chunk:
...         process_data(chunk)
...         chunk = stream.fetch()

>>> # Arrow format with RecordBatch streaming
>>> stream = conn.send_query("SELECT * FROM data", "Arrow")
>>> reader = stream.record_batch(rows_per_batch=10000)
>>> for batch in reader:
...     print(f"Batch shape: {batch.num_rows} x {batch.num_columns}")

انظر أيضًا

• query() - لتنفيذ الاستعلامات غير المتدفقة
• StreamingResult - مكرّر نتائج البث

الفئات الأساسية: object

مكرِّر نتائج متدفقة لمعالجة نتائج الاستعلامات الكبيرة.

توفّر هذه الفئة واجهة تكرار لنتائج الاستعلامات المتدفقة دون تحميل مجموعة النتائج بالكامل إلى الذاكرة. وهي تدعم تنسيقات إخراج متنوعة وتوفّر أساليب للجلب اليدوي للنتائج وبثّ RecordBatch من PyArrow.

class chdb.state.sqlitelike.StreamingResult

اجلب الجزء التالي من نتائج الاستعلام المتدفقة.

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

الصياغة

fetch() → Any

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

أمثلة

>>> stream = conn.send_query("SELECT * FROM large_table")
>>> chunk = stream.fetch()
>>> while chunk is not None:
...     process_data(chunk)
...     chunk = stream.fetch()

ألغِ الاستعلام المتدفق وحرِّر الموارد.

تلغي هذه الطريقة أي استعلام متدفق جارٍ وتحرِّر الموارد المرتبطة به. ويجب استدعاؤها عندما تريد إيقاف معالجة النتائج قبل انتهاء التدفق.

الصياغة

cancel() → None

أمثلة

>>> stream = conn.send_query("SELECT * FROM very_large_table")
>>> for i, chunk in enumerate(stream):
...     if i >= 10:  # Only process first 10 chunks
...         stream.cancel()
...         break
...     process_data(chunk)

أغلق النتيجة المتدفقة ونظّف الموارد.

اسم مستعار لـ cancel(). يُغلق مُكرِّر النتيجة المتدفقة ويحرّر أي موارد مرتبطة بها.

الصياغة

close() → None

أنشئ PyArrow RecordBatchReader لمعالجة الدُفعات بكفاءة.

تُنشئ هذه الطريقة كائن PyArrow RecordBatchReader يتيح التكرار بكفاءة عبر نتائج الاستعلام بتنسيق Arrow. وهذه هي الطريقة الأكثر كفاءة لمعالجة مجموعات النتائج الكبيرة عند استخدام PyArrow.

الصياغة

record_batch(rows_per_batch: int = 1000000) → pa.RecordBatchReader

المعلمات

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

أمثلة

>>> stream = conn.send_query("SELECT * FROM data", format="Arrow")
>>> reader = stream.record_batch(rows_per_batch=10000)
>>> for batch in reader:
...     print(f"Processing batch: {batch.num_rows} rows")
...     df = batch.to_pandas()
...     process_dataframe(df)

يدعم StreamingResult بروتوكول المكرِّر في بايثون، مما يسمح باستخدامه مباشرةً في حلقات for:

>>> stream = conn.send_query("SELECT number FROM numbers(1000000)")
>>> for chunk in stream:
...     print(f"Chunk size: {len(chunk)} bytes")

يدعم StreamingResult بروتوكول مدير السياق للتنظيف التلقائي للموارد:

>>> with conn.send_query("SELECT * FROM data") as stream:
...     for chunk in stream:
...         process(chunk)
>>> # Stream automatically closed

الصنف الأساسي: object

class chdb.state.sqlitelike.Cursor(connection)

أغلِق المؤشر ونظِّف الموارد.

تُغلق هذه الطريقة المؤشر وتُنظِّف أي موارد مرتبطة به. بعد استدعاء هذه الطريقة، يصبح المؤشر غير صالح ولا يمكن استخدامه في عمليات لاحقة.

الصيغة

close() → None

أمثلة

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchone()
>>> cursor.close()  # Cleanup cursor resources

أعِد قائمة بأسماء الأعمدة من آخر استعلام نُفِّذ.

تُرجِع هذه الطريقة أسماء الأعمدة من أحدث استعلام SELECT تم تنفيذه. وتُرجَع الأسماء بالترتيب نفسه الذي تظهر به في مجموعة النتائج.

الصيغة

column_names() → list

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

أمثلة

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name, email FROM users LIMIT 1")
>>> print(cursor.column_names())
['id', 'name', 'email']

انظر أيضًا

• column_types() - الحصول على معلومات عن نوع العمود
• description - وصف العمود في DB-API 2.0

أعِد قائمةً بأنواع الأعمدة من آخر استعلام تم تنفيذه.

تعيد هذه الطريقة أسماء أنواع أعمدة ClickHouse من أحدث استعلام SELECT تم تنفيذه. وتُعاد الأنواع بالترتيب نفسه الذي تظهر به في مجموعة النتائج.

الصيغة

column_types() → list

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

أمثلة

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT toInt32(1), toString('hello')")
>>> print(cursor.column_types())
['Int32', 'String']

انظر أيضًا

• column_names() - الحصول على معلومات عن أسماء الأعمدة
• description - وصف الأعمدة وفقًا لـ DB-API 2.0

ثبّت أي معاملة قيد الانتظار.

تُثبّت هذه الطريقة أي معاملة قاعدة بيانات قيد الانتظار. في ClickHouse، تُثبَّت معظم العمليات تلقائيًا، لكن هذه الطريقة مُتاحة من أجل التوافق مع DB-API 2.0.

الصيغة

commit() → None

أمثلة

>>> cursor = conn.cursor()
>>> cursor.execute("INSERT INTO test VALUES (1, 'data')")
>>> cursor.commit()

يعيد وصف الأعمدة وفقًا لمواصفة DB-API 2.0.

تعيد هذه الخاصية قائمة من tuples، يتكوّن كل منها من 7 عناصر تصف كل عمود في مجموعة نتائج آخر استعلام SELECT تم تنفيذه. يحتوي كل Tuple على: (name, type_code, display_size, internal_size, precision, scale, null_ok)

حاليًا، لا يتم توفير سوى name و type_code، بينما تُضبط الحقول الأخرى على None.

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

أمثلة

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users LIMIT 1")
>>> for desc in cursor.description:
...     print(f"Column: {desc[0]}, Type: {desc[1]}")
Column: id, Type: Int32
Column: name, Type: String

انظر أيضًا

• column_names() - الحصول على أسماء الأعمدة فقط
• column_types() - الحصول على أنواع الأعمدة فقط

نفّذ استعلام SQL وجهّز النتائج للاسترداد.

تنفّذ هذه الطريقة استعلام SQL وتجهّز النتائج لاستردادها باستخدام طرق الجلب. كما تتولى تحليل بيانات النتائج وإجراء التحويل التلقائي لأنواع بيانات ClickHouse.

الصيغة

execute(query: str) → None

المعلمات:

الاستثناءات

أمثلة

>>> cursor = conn.cursor()
>>>
>>> # Execute DDL
>>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>>
>>> # Execute DML
>>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
>>>
>>> # Execute SELECT and fetch results
>>> cursor.execute("SELECT * FROM test")
>>> rows = cursor.fetchall()
>>> print(rows)
((1, 'Alice'),)

انظر أيضًا

• fetchone() - استرجاع صف واحد
• fetchmany() - استرجاع عدة صفوف
• fetchall() - استرجاع جميع الصفوف المتبقية

اجلب جميع الصفوف المتبقية من نتيجة الاستعلام.

تسترجع هذه الطريقة جميع الصفوف المتبقية من مجموعة نتائج الاستعلام الحالية بدءًا من موضع المؤشر الحالي. وتُرجع tuple من tuple للصفوف مع تطبيق تحويل أنواع Python المناسب.

البنية

fetchall() → tuple

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

أمثلة

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users")
>>> all_users = cursor.fetchall()
>>> for user_id, user_name in all_users:
...     print(f"User {user_id}: {user_name}")

انظر أيضًا

• fetchone() - جلب صف واحد
• fetchmany() - جلب عدة صفوف على دفعات

اجلب عدة صفوف من نتيجة الاستعلام.

تسترجع هذه الطريقة ما يصل إلى size صفًا من مجموعة نتائج الاستعلام الحالية. وتُرجع tuple من tuples للصفوف، بحيث يحتوي كل صف على قيم الأعمدة مع تحويل مناسب إلى أنواع Python.

الصيغة

fetchmany(size: int = 1) → tuple

المعلمات

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

أمثلة

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT * FROM large_table")
>>>
>>> # Process results in batches
>>> while True:
...     batch = cursor.fetchmany(100)  # Fetch 100 rows at a time
...     if not batch:
...         break
...     process_batch(batch)

انظر أيضًا

• fetchone() - جلب صف واحد
• fetchall() - جلب جميع الصفوف المتبقية

اجلب الصف التالي من نتيجة الاستعلام.

تسترجع هذه الطريقة الصف التالي المتاح من مجموعة نتائج الاستعلام الحالية. وتُرجع قيمة من نوع tuple تحتوي على قيم الأعمدة مع تطبيق التحويل المناسب إلى أنواع Python.

الصيغة

fetchone() → tuple | None

يعيد:

أمثلة

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users")
>>> row = cursor.fetchone()
>>> while row is not None:
...     user_id, user_name = row
...     print(f"User {user_id}: {user_name}")
...     row = cursor.fetchone()

انظر أيضًا

• fetchmany() - استرجاع عدة صفوف
• fetchall() - استرجاع جميع الصفوف المتبقية

حوِّل نتيجة الاستعلام إلى PyArrow Table.

تُحوِّل هذه الدالة نتائج استعلامات chdb إلى تنسيق PyArrow Table، مما يوفّر وصولًا فعّالًا إلى البيانات المخزّنة عموديًا وإمكانية التشغيل البيني مع مكتبات معالجة البيانات الأخرى.

الصيغة

chdb.state.sqlitelike.to_arrowTable(res)

المعلمات:

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

الاستثناءات

أمثلة

>>> import chdb
>>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
>>> table = to_arrowTable(result)
>>> print(table.schema)
num: int64
text: string
>>> print(table.to_pandas())
   num   text
0    1  hello

حوِّل نتيجة الاستعلام إلى Pandas DataFrame.

تُحوِّل هذه الدالة نتائج استعلامات chdb إلى Pandas DataFrame عبر تحويلها أولًا إلى PyArrow Table ثم إلى DataFrame. ويوفّر ذلك إمكانات مريحة لتحليل البيانات باستخدام واجهة Pandas البرمجية.

الصيغة

chdb.state.sqlitelike.to_df(r)

المعلمات:

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

الاستثناءات

انظر أيضًا

• to_arrowTable() - للتحويل إلى تنسيق PyArrow Table

أمثلة

>>> import chdb
>>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
>>> df = to_df(result)
>>> print(df)
   num   text
0    1  hello
>>> print(df.dtypes)
num      int64
text    object
dtype: object

الأصناف الأساسية:

class chdb.dataframe.Table(*args: Any, **kwargs: Any)

يوفّر chDB واجهة متوافقة مع Python DB-API 2.0 للاتصال بقواعد البيانات، مما يتيح لك استخدام chDB مع الأدوات وأطر العمل التي تعتمد واجهات قواعد بيانات قياسية.

تتضمن واجهة chDB DB-API 2.0 ما يلي:

• الاتصالات: إدارة اتصالات قاعدة البيانات باستخدام سلاسل الاتصال
• المؤشرات: تنفيذ الاستعلامات واسترجاع النتائج
• نظام الأنواع: ثوابت أنواع ومحوّلات متوافقة مع DB-API 2.0
• معالجة الأخطاء: تسلسل هرمي قياسي لاستثناءات قواعد البيانات
• أمان الخيوط: المستوى 1 من أمان الخيوط (يمكن للخيوط مشاركة الوحدات، لكن ليس الاتصالات)

تتضمن واجهة Database API ‏(DBAPI) 2.0 الدوال الأساسية التالية:

أنشئ اتصالًا جديدًا بقاعدة البيانات.

الصيغة

chdb.dbapi.connect(*args, **kwargs)

المعلمات

الاستثناءات

يسترجع معلومات إصدار العميل.

يعيد إصدار عميل chDB كسلسلة نصية للتوافق مع MySQLdb.

الصيغة

chdb.dbapi.get_client_info()

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

إرجاع x كنوع ثنائي.

تُحوِّل هذه الدالة المُدخل إلى النوع bytes لاستخدامه مع الحقول الثنائية في قاعدة البيانات، وذلك وفقًا لمواصفة DB-API 2.0.

الصيغة

chdb.dbapi.Binary(x)

المعلمات

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

الفئات الأساسية: object

اتصال متوافق مع DB-API 2.0 بقاعدة بيانات chDB.

يوفّر هذا الصنف واجهة DB-API قياسية للاتصال بقواعد بيانات chDB والتفاعل معها. ويدعم قواعد البيانات المؤقتة وقواعد البيانات القائمة على الملفات.

يدير الاتصال محرك chDB الأساسي ويوفّر أساليب لتنفيذ الاستعلامات وإدارة المعاملات (بلا تأثير في ClickHouse) وإنشاء المؤشرات.

class chdb.dbapi.connections.Connection(path=None)

المعلمات

المتغيرات

أمثلة

>>> # Temporary database
>>> conn = Connection()
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchall()
>>> conn.close()

>>> # File-based database
>>> conn = Connection('mydata.db')
>>> with conn.cursor() as cur:
...     cur.execute("CREATE TABLE users (id INT, name STRING) ENGINE = MergeTree() order by id")
...     cur.execute("INSERT INTO users VALUES (1, 'Alice')")
>>> conn.close()

>>> # Context manager usage
>>> with Connection() as cur:
...     cur.execute("SELECT version()")
...     version = cur.fetchone()

أغلق اتصال قاعدة البيانات.

يُغلق اتصال chDB الأساسي ويضع علامة على هذا الاتصال باعتباره مغلقًا. وأي عمليات لاحقة على هذا الاتصال ستؤدي إلى ظهور خطأ.

الصيغة

close()

الاستثناءات التي قد تُرفع

اعتمد المعاملة الحالية.

الصيغة

commit()

أنشئ مؤشرًا جديدًا لتنفيذ الاستعلامات.

الصيغة

cursor(cursor=None)

المعلمات

العوائد

الاستثناءات

مثال

>>> conn = Connection()
>>> cur = conn.cursor()
>>> cur.execute("SELECT 1")
>>> result = cur.fetchone()

أفلِت قيمة بحيث يمكن تضمينها بأمان في استعلامات SQL.

الصيغة

escape(obj, mapping=None)

المعاملات

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

مثال

>>> conn = Connection()
>>> safe_value = conn.escape("O'Reilly")
>>> query = f"SELECT * FROM users WHERE name = {safe_value}"

قم بإفلات قيمة نصية لاستعلامات SQL.

الصيغة

escape_string(s)

المعلمات

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

تحقّق مما إذا كان الاتصال مفتوحًا.

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

نفّذ استعلام SQL مباشرةً وأعِد النتائج الأولية.

تتجاوز هذه الطريقة واجهة المؤشر وتنفّذ الاستعلامات مباشرةً. لاستخدام DB-API القياسي، يُفضَّل استخدام الطريقة cursor().

الصيغة

query(sql, fmt='CSV')

المعلمات:

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

الاستثناءات

مثال

>>> conn = Connection()
>>> result = conn.query("SELECT 1, 'hello'", "CSV")
>>> print(result)
"1,hello\n"

يعرض آخر استجابة للاستعلام.

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

التراجع عن المعاملة الحالية.

البنية

rollback()

يرث من: object

مؤشر DB-API 2.0 لتنفيذ الاستعلامات وجلب النتائج.

يوفّر المؤشر أساليب لتنفيذ عبارات SQL، وإدارة نتائج الاستعلام، والتنقّل عبر مجموعات النتائج. كما يدعم ربط المعلمات والعمليات المجمّعة، ويلتزم بمواصفات DB-API 2.0.

لا تُنشئ مثيلات مؤشر مباشرةً. استخدم Connection.cursor() بدلًا من ذلك.

class chdb.dbapi.cursors.Cursor(connection)

أمثلة

>>> conn = Connection()
>>> cur = conn.cursor()
>>> cur.execute("SELECT 1 as id, 'test' as name")
>>> result = cur.fetchone()
>>> print(result)  # (1, 'test')
>>> cur.close()

نفّذ إجراءً مخزّنًا (تنفيذ مبدئي).

الصيغة

callproc(procname, args=())

المعلمات

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

أغلِق المؤشر وحرِّر الموارد المرتبطة به.

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

الصيغة

close()

نفّذ استعلام SQL مع ربط اختياري للمعلمات.

تُنفِّذ هذه الطريقة تعليمة SQL واحدة مع استبدال اختياري للمعلمات. وتدعم عدة أنماط لعناصر نائبة للمعلمات لمزيد من المرونة.

البنية

execute(query, args=None)

المعلمات

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

أنماط المعلمات

أمثلة

>>> # Question mark parameters
>>> cur.execute("SELECT * FROM users WHERE id = ? AND age > ?", (123, 18))
>>>
>>> # Named parameters
>>> cur.execute("SELECT * FROM users WHERE name = %(name)s", {'name': 'Alice'})
>>>
>>> # No parameters
>>> cur.execute("SELECT COUNT(*) FROM users")

الاستثناءات

نفِّذ استعلامًا عدة مرات باستخدام مجموعات مختلفة من المعلمات.

تُنفِّذ هذه الطريقة استعلام SQL نفسه بكفاءة عدة مرات مع قيم مختلفة للمعلمات. وهي مفيدة بشكل خاص في عمليات INSERT المجمّعة.

الصيغة

executemany(query, args)

المعلمات

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

أمثلة

>>> # Bulk insert with question mark parameters
>>> users_data = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
>>> cur.executemany("INSERT INTO users VALUES (?, ?)", users_data)
>>>
>>> # Bulk insert with named parameters
>>> users_data = [
...     {'id': 1, 'name': 'Alice'},
...     {'id': 2, 'name': 'Bob'}
... ]
>>> cur.executemany(
...     "INSERT INTO users VALUES (%(id)s, %(name)s)",
...     users_data
... )

استرجع جميع الصفوف المتبقية من نتيجة الاستعلام.

البنية

fetchall()

يعيد

يثير

مثال

>>> cursor.execute("SELECT id, name FROM users")
>>> all_rows = cursor.fetchall()
>>> print(len(all_rows))  # Number of total rows

يجلب عدة صفوف من نتيجة الاستعلام.

البنية

fetchmany(size=1)

المعلمات

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

الاستثناءات

مثال

>>> cursor.execute("SELECT id, name FROM users")
>>> rows = cursor.fetchmany(3)
>>> print(rows)  # [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]

يجلب الصف التالي من نتيجة الاستعلام.

الصياغة

fetchone()

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

الاستثناءات

مثال

>>> cursor.execute("SELECT id, name FROM users LIMIT 3")
>>> row = cursor.fetchone()
>>> print(row)  # (1, 'Alice')
>>> row = cursor.fetchone()
>>> print(row)  # (2, 'Bob')

الحد الأقصى لحجم تعليمة statement التي تُنشئها executemany().

القيمة الافتراضية هي 1024000.

يعيد سلسلة الاستعلام الدقيقة التي ستُرسَل إلى قاعدة البيانات.

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

الصيغة

mogrify(query, args=None)

المعلمات

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

مثال

>>> cur.mogrify("SELECT * FROM users WHERE id = ?", (123,))
"SELECT * FROM users WHERE id = 123"

انتقل إلى مجموعة النتائج التالية (غير مدعوم).

الصيغة

nextset()

يعيد

يضبط أحجام الإدخال للمعلمات (تنفيذ شكلي لا يؤدي أي إجراء).

البنية

setinputsizes(*args)

المعلمات

ضبط أحجام أعمدة الإخراج (تنفيذ شكلي بلا تأثير فعلي).

الصيغة

setoutputsizes(*args)

المعلمات

فئات الاستثناءات لعمليات قاعدة البيانات في chdb.

توفّر هذه الوحدة تسلسلاً هرمياً كاملاً لفئات الاستثناءات للتعامل مع الأخطاء المرتبطة بقاعدة البيانات في chdb، وذلك وفقاً لمواصفة Python Database API الإصدار 2.0.

يأتي التسلسل الهرمي للاستثناءات على النحو التالي:

StandardError
├── Warning
└── Error
    ├── InterfaceError
    └── DatabaseError
        ├── DataError
        ├── OperationalError
        ├── IntegrityError
        ├── InternalError
        ├── ProgrammingError
        └── NotSupportedError

تمثل كل فئة من فئات الاستثناء فئةً محددة من أخطاء قاعدة البيانات:

راجع أيضًا

• مواصفة Python Database API الإصدار 2.0
• chdb.dbapi.connections - إدارة اتصالات قاعدة البيانات
• chdb.dbapi.cursors - عمليات مؤشرات قاعدة البيانات

أمثلة

>>> try:
...     cursor.execute("SELECT * FROM nonexistent_table")
... except ProgrammingError as e:
...     print(f"SQL Error: {e}")
...
SQL Error: Table 'nonexistent_table' doesn't exist

>>> try:
...     cursor.execute("INSERT INTO users (id) VALUES (1), (1)")
... except IntegrityError as e:
...     print(f"Constraint violation: {e}")
...
Constraint violation: Duplicate entry '1' for key 'PRIMARY'

يرث من: DatabaseError

يُرفَع هذا الاستثناء عند حدوث أخطاء ناتجة عن مشكلات في البيانات التي تجري معالجتها.

يُرفَع هذا الاستثناء عندما تفشل عمليات قاعدة البيانات بسبب مشكلات في البيانات قيد المعالجة، مثل:

• عمليات القسمة على صفر
• قيم رقمية خارج النطاق
• قيم تاريخ/وقت غير صالحة
• أخطاء اقتطاع السلاسل النصية
• فشل تحويل الأنواع
• تنسيق بيانات غير صالح لنوع العمود

الاستثناءات المُثارة

أمثلة

>>> # Division by zero in SQL
>>> cursor.execute("SELECT 1/0")
DataError: Division by zero

>>> # Invalid date format
>>> cursor.execute("INSERT INTO table VALUES ('invalid-date')")
DataError: Invalid date format

الفئات الأساسية: Error

استثناء يُرفَع عند حدوث أخطاء مرتبطة بقاعدة البيانات.

هذه هي الفئة الأساسية لجميع الأخطاء المتعلقة بقاعدة البيانات. وهي تشمل كل الأخطاء التي تحدث أثناء عمليات قاعدة البيانات وترتبط بقاعدة البيانات نفسها لا بالواجهة.

تشمل الحالات الشائعة ما يلي:

• أخطاء تنفيذ SQL
• مشكلات الاتصال بقاعدة البيانات
• مشكلات متعلقة بالمعاملات
• انتهاكات القيود الخاصة بقاعدة البيانات

الفئات الأساسية: StandardError

استثناء يُعد الفئة الأساسية لجميع استثناءات الأخطاء الأخرى (وليس Warning).

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

انظر أيضًا

• Warning - للتحذيرات غير الجسيمة التي لا تمنع اكتمال العملية

الفئات الأساسية: DatabaseError

يُثار هذا الاستثناء عندما تتأثر السلامة العلائقية لقاعدة البيانات.

ويُثار عند انتهاك عمليات قاعدة البيانات لقيود السلامة، بما في ذلك:

• انتهاك قيد المفتاح الخارجي
• انتهاك المفتاح الأساسي أو القيد الفريد (مفاتيح مكررة)
• انتهاك قيد التحقق
• انتهاك قيد NOT NULL
• انتهاك السلامة المرجعية

يُثير

أمثلة

>>> # Duplicate primary key
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'John')")
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'Jane')")
IntegrityError: Duplicate entry '1' for key 'PRIMARY'

>>> # Foreign key violation
>>> cursor.execute("INSERT INTO orders (user_id) VALUES (999)")
IntegrityError: Cannot add or update a child row: foreign key constraint fails

الفئات الأساسية: Error

يُثار هذا الاستثناء عند حدوث أخطاء تتعلق بواجهة قاعدة البيانات، لا بقاعدة البيانات نفسها.

يُثار هذا الاستثناء عند وجود مشكلات في تنفيذ واجهة قاعدة البيانات، مثل:

• معلمات اتصال غير صالحة
• إساءة استخدام API (استدعاء الأساليب على اتصالات مغلقة)
• أخطاء بروتوكول على مستوى الواجهة
• فشل استيراد الوحدة أو تهيئتها

يُثير

الفئات الأساسية: DatabaseError

يُرفَع هذا الاستثناء عندما تواجه قاعدة البيانات خطأً داخليًا.

يُرفَع هذا الاستثناء عندما يواجه نظام قاعدة البيانات أخطاءً داخلية لا يتسبب بها التطبيق، مثل:

• حالة مؤشر غير صالحة (لم يعد المؤشر صالحًا)
• حالات عدم اتساق في حالة المعاملة (المعاملة غير متزامنة)
• مشكلات تلف في قاعدة البيانات
• تلف في بنية البيانات الداخلية
• أخطاء قاعدة بيانات على مستوى النظام

يرفع

الفئات الأساسية: DatabaseError

يُرفع هذا الاستثناء عندما لا تكون إحدى الطرق أو Database API مدعومة.

يُرفع هذا الاستثناء عندما يحاول التطبيق استخدام ميزات في قاعدة البيانات أو طرق API لا تدعمها تهيئة قاعدة البيانات الحالية أو إصدارها الحالي، مثل:

• طلب rollback() على الاتصالات التي لا تدعم المعاملات
• استخدام ميزات SQL متقدمة لا يدعمها إصدار قاعدة البيانات
• استدعاء طرق غير مُنفّذة في برنامج التشغيل الحالي
• محاولة استخدام ميزات معطّلة في قاعدة البيانات

الاستثناءات

أمثلة

>>> # Transaction rollback on non-transactional connection
>>> connection.rollback()
NotSupportedError: Transactions are not supported

>>> # Using unsupported SQL syntax
>>> cursor.execute("SELECT * FROM table WITH (NOLOCK)")
NotSupportedError: WITH clause not supported in this database version

الفئات الأساسية: DatabaseError

استثناء يُرفَع عند وقوع أخطاء مرتبطة بتشغيل قاعدة البيانات.

يُرفَع هذا الاستثناء عند حدوث أخطاء أثناء تشغيل قاعدة البيانات ولا تكون بالضرورة ضمن سيطرة المبرمج، بما في ذلك:

• انقطاع الاتصال بقاعدة البيانات بشكل غير متوقع
• تعذّر العثور على خادم قاعدة البيانات أو تعذّر الوصول إليه
• حالات فشل معالجة المعاملات
• أخطاء تخصيص الذاكرة أثناء المعالجة
• نفاد مساحة القرص أو الموارد
• أخطاء داخلية في خادم قاعدة البيانات
• إخفاقات المصادقة أو التفويض

يُثير

الفئات الأساسية: DatabaseError

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

يُرفَع هذا الاستثناء عندما تكون هناك أخطاء برمجية في استخدام التطبيق لقاعدة البيانات، بما في ذلك:

• تعذّر العثور على جدول أو عمود
• وجود الجدول أو الفهرس مسبقًا عند الإنشاء
• أخطاء في بناء جملة SQL في التعليمات
• تحديد عدد غير صحيح من المعلمات في التعليمات المُحضّرة
• عمليات SQL غير صالحة (مثل DROP على كائنات غير موجودة)
• استخدام غير صحيح لأساليب واجهة برمجة تطبيقات قواعد البيانات

يُثير

أمثلة

>>> # Table not found
>>> cursor.execute("SELECT * FROM nonexistent_table")
ProgrammingError: Table 'nonexistent_table' doesn't exist

>>> # SQL syntax error
>>> cursor.execute("SELCT * FROM users")
ProgrammingError: You have an error in your SQL syntax

>>> # Wrong parameter count
>>> cursor.execute("INSERT INTO users (name, age) VALUES (%s)", ('John',))
ProgrammingError: Column count doesn't match value count

الفئات الأساسية: Exception

استثناء مرتبط بالعمليات التي تُجرى باستخدام chdb.

هذه هي الفئة الأساسية لجميع الاستثناءات المرتبطة بـ chdb. وهي ترث من فئة Exception المضمنة في Python وتمثل الجذر في التسلسل الهرمي لاستثناءات عمليات قاعدة البيانات.

الفئات الأساسية: StandardError

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

يُثار هذا الاستثناء عندما تكتمل العملية على قاعدة البيانات، ولكن مع تحذيرات مهمة ينبغي تنبيه التطبيق إليها. وتشمل السيناريوهات الشائعة ما يلي:

• اقتطاع البيانات أثناء الإدراج
• فقدان الدقة في التحويلات الرقمية
• تحذيرات تحويل ترميز الأحرف

str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

أنشئ كائن سلسلة نصية جديدًا من الكائن المُعطى. إذا جرى تحديد encoding أو errors، فيجب أن يوفّر الكائن مخزنًا مؤقتًا للبيانات سيُفك ترميزه باستخدام encoding المحدد ومعالج الأخطاء. وبخلاف ذلك، يُرجِع ناتج object._\_str_\_() (إذا كان معرّفًا) أو repr(object).

• القيمة الافتراضية لـ encoding هي ‘utf-8’.
• القيمة الافتراضية لـ errors هي ‘strict’.

int([x]) -> integer
int(x, base=10) -> integer

حوِّل رقمًا أو سلسلة نصية إلى عدد صحيح، أو أعد 0 إذا لم تُمرَّر أي argument. إذا كان x رقمًا، فأعد x._int_(). بالنسبة إلى الأعداد ذات الفاصلة العائمة، يُقتطع الجزء الكسري باتجاه الصفر.

إذا لم يكن x رقمًا أو إذا أُعطيت base، فيجب أن يكون x سلسلة نصية، أو bytes، أو instance من bytearray يمثّل عددًا صحيحًا مكتوبًا بالأساس المحدد. يمكن أن تسبق هذه الصيغة العلامة ‘+’ أو ‘-’، وأن تُحاط بمسافات بيضاء. تكون القيمة الافتراضية لـ base هي 10. الأسس الصالحة هي 0 و2-36. ويعني الأساس 0 أن يُستدل على الأساس من السلسلة نفسها باعتبارها عددًا صحيحًا مكتوبًا.

>>> int(‘0b100’, base=0)
4

str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

أنشئ كائنًا نصيًا جديدًا من الكائن المعطى. إذا تم تحديد encoding أو errors، فيجب أن يوفّر الكائن مخزنًا مؤقتًا للبيانات يُفك ترميزه باستخدام الترميز المحدد ومعالج الأخطاء المحدد. وإلا، فستُعاد نتيجة object._str_() (إن كانت معرّفة) أو repr(object). القيمة الافتراضية لـ encoding هي ‘utf-8’. القيمة الافتراضية لـ errors هي ‘strict’.

frozenset موسع لمقارنة الأنواع في DB-API 2.0.

يوسّع هذا الصنف frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح تحقّقًا مرنًا من الأنواع، بحيث يمكن مقارنة العناصر الفردية بالمجموعة باستخدام معاملي المساواة وعدم المساواة.

يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة.

أمثلة

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

frozenset موسع لمقارنة الأنواع وفقًا لـ DB-API 2.0.

يوسّع هذا الصنف frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح التحقق من الأنواع بمرونة، بحيث يمكن مقارنة العناصر الفردية بالمجموعة باستخدام معاملي المساواة وعدم المساواة.

يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وما إلى ذلك لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة.

أمثلة

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

frozenset موسع لمقارنة الأنواع في DB-API 2.0.

يوسّع هذا الصنف frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح إجراء تحقق من الأنواع بمرونة، بحيث يمكن مقارنة العناصر الفردية بالمجموعة باستخدام معاملي المساواة وعدم المساواة.

يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة.

أمثلة

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

frozenset موسع لمقارنة الأنواع في DB-API 2.0.

توسّع هذه الفئة frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. وتتيح تحقّقًا مرنًا من الأنواع، بحيث يمكن مقارنة العناصر الفردية بالمجموعة باستخدام معاملي المساواة وعدم المساواة.

يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة.

أمثلة

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

frozenset موسّعة لمقارنة الأنواع في DB-API 2.0.

يوسّع هذا الصنف frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح تحققًا مرنًا من الأنواع، بحيث يمكن مقارنة العناصر المفردة بالمجموعة باستخدام معاملي المساواة وعدم المساواة.

يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة.

أمثلة

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

frozenset موسّعة لمقارنة الأنواع في DB-API 2.0.

يوسّع هذا الصنف frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح تحقّقًا مرنًا من الأنواع، بحيث يمكن مقارنة العناصر الفردية بالمجموعة باستخدام معاملي المساواة وعدم المساواة.

يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة.

أمثلة

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

frozenset موسَّعة لمقارنة الأنواع وفق DB-API 2.0.

يوسِّع هذا الصنف frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح التحقق من الأنواع بمرونة، بحيث يمكن مقارنة العناصر المفردة بالمجموعة باستخدام معاملي المساواة وعدم المساواة.

يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة.

أمثلة

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

frozenset موسع لمقارنة الأنواع في DB-API 2.0.

توسّع هذه الفئة frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. وتتيح إجراء تحقق من الأنواع بمرونة، بحيث يمكن مقارنة العناصر المفردة بالمجموعة باستخدام معاملي المساواة وعدم المساواة.

يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة.

أمثلة

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

أمثلة الاستخدام

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

import chdb.dbapi as dbapi

print("chdb driver version: {0}".format(dbapi.get_client_info()))

# Create connection and cursor
conn = dbapi.connect()
cur = conn.cursor()

# Execute query
cur.execute('SELECT version()')
print("description:", cur.description)
print("data:", cur.fetchone())

# Clean up
cur.close()
conn.close()

التعامل مع البيانات:

import chdb.dbapi as dbapi

conn = dbapi.connect()
cur = conn.cursor()

# Create table
cur.execute("""
    CREATE TABLE employees (
        id UInt32,
        name String,
        department String,
        salary Decimal(10,2)
    ) ENGINE = Memory
""")

# Insert data
cur.execute("""
    INSERT INTO employees VALUES
    (1, 'Alice', 'Engineering', 75000.00),
    (2, 'Bob', 'Marketing', 65000.00),
    (3, 'Charlie', 'Engineering', 80000.00)
""")

# Query data
cur.execute("SELECT * FROM employees WHERE department = 'Engineering'")

# Fetch results
print("Column names:", [desc[0] for desc in cur.description])
for row in cur.fetchall():
    print(row)

conn.close()

إدارة الاتصالات:

import chdb.dbapi as dbapi

# Temporary database (default)
conn1 = dbapi.connect()

# Persistent database file
conn2 = dbapi.connect("./my_database.chdb")

# Connection with parameters
conn3 = dbapi.connect("./my_database.chdb?log-level=debug&verbose")

# Read-only connection
conn4 = dbapi.connect("./my_database.chdb?mode=ro")

# Automatic connection cleanup
with dbapi.connect("test.chdb") as conn:
    cur = conn.cursor()
    cur.execute("SELECT count() FROM numbers(1000)")
    result = cur.fetchone()
    print(f"Count: {result[0]}")
    cur.close()

أفضل الممارسات

1. إدارة الاتصال: أغلق دائمًا الاتصالات والمؤشرات عند الانتهاء
2. مديرو السياق: استخدم تعليمات with للتنظيف التلقائي
3. المعالجة على دفعات: استخدم fetchmany() مع مجموعات النتائج الكبيرة
4. معالجة الأخطاء: ضمّن عمليات قاعدة البيانات داخل كتل try-except
5. ربط المعلمات: استخدم الاستعلامات المُعلَّمة بالمعلمات متى أمكن
6. إدارة الذاكرة: تجنب fetchall() مع مجموعات البيانات الكبيرة جدًا

يدعم chDB دوال UDF أصلية في بايثون تعمل ضمن العملية، مع وسائط محددة الأنواع، واستنتاج تلقائي للأنواع، ومعالجة قابلة للتهيئة لقيم NULL والتعامل مع الاستثناءات. يمكن استدعاء دوال بايثون المسجّلة كدوال UDF مباشرةً من استعلامات SQL.

تستخدم الأمثلة أدناه تنسيق إخراج CSV الافتراضي. توضح التعليقات المضمنة قيم النتائج المنطقية؛ بينما يطبع الإخراج الخام NULL بالشكل \N ويطبّق اقتباس CSV على قيم السلاسل النصية والتواريخ.

سجّل دالة بايثون كدالة SQL في chDB.

بنية

chdb.create_function(name, func, arg_types=None, return_type=None, *, on_null=None, on_error=None)

المعلمات

يقبل كل مَعْلَم نوع (عناصر arg_types وreturn_type) ما يلي:

• ثابت ChdbType: ‏INT64، ‏STRING، ‏FLOAT64، إلخ.
• سلسلة نوع ClickHouse: ‏"Int64"، ‏"String"، ‏"DateTime64(6)"، ‏"DateTime('UTC')"، إلخ.
• نوع بايثون: ‏int، ‏float، ‏str، ‏bool، ‏bytes، ‏datetime.date، ‏datetime.datetime — يُعيَّن وفق تعيين الأنواع التلقائي

يؤدي تسجيل اسم مسجّل مسبقًا إلى ظهور خطأ — لا تُستبدل UDFs تلقائيًا. استدعِ drop_function أولًا لإعادة تسجيل دالة.

مثال

from chdb import create_function, drop_function, query
from chdb.sqltypes import INT64, STRING

create_function("strlen", len, arg_types=[STRING], return_type=INT64)
print(query("SELECT strlen('hello')"))  # 5

drop_function("strlen")

أزِل دالة UDF مسجَّلة سابقًا بلغة بايثون. لا يحدث شيء إذا لم تكن الدالة مسجَّلة، لذا يمكن استدعاؤها بأمان دون شرط.

البنية

chdb.drop_function(name)

المعلمات

مُزيّن لتسجيل دالة بايثون كدالة SQL في chDB. تظل الدالة قابلة للاستدعاء كدالة بايثون عادية، وتصبح متاحة في الوقت نفسه ضمن استعلامات SQL باسمها __name__.

البنية

from chdb import func

@func(arg_types=None, return_type=None, *, on_null=None, on_error=None)
def my_function(...):
    ...

المَعلمات

كما في create_function، باستثناء name وfunc، إذ يُستمدّان من الدالة المُزيَّنة.

أمثلة

from chdb import func, query
from chdb.sqltypes import INT64, STRING

# Explicit types
@func([INT64, INT64], INT64)
def add(a, b):
    return a + b

# Types inferred from annotations
@func()
def multiply(a: int, b: int) -> int:
    return a * b

# Explicit return_type, arg_types inferred from annotations
@func(return_type=STRING)
def greet(name: str):
    return f"Hello, {name}!"

print(query("SELECT add(12, 22)"))       # 34
print(query("SELECT multiply(3, 7)"))    # 21
print(query("SELECT greet('world')"))    # Hello, world!

استورد الأنواع من chdb.sqltypes:

from chdb.sqltypes import (
    BOOL,
    INT8, INT16, INT32, INT64, INT128, INT256,
    UINT8, UINT16, UINT32, UINT64, UINT128, UINT256,
    FLOAT32, FLOAT64,
    STRING,
    DATE, DATE32, DATETIME, DATETIME64,
)

عند استنتاج الأنواع من التعليقات التوضيحية في بايثون، يُستخدم التعيين التالي:

يمكن تحديد الأنواع بعدة طرق:

from chdb import create_function, func
from chdb.sqltypes import INT64

# 1. ChdbType constants
create_function("f1", lambda x: x, arg_types=[INT64], return_type=INT64)

# 2. ClickHouse type strings
create_function("f2", lambda x: x, arg_types=["Int64"], return_type="Int64")

# 3. Parameterized type strings
create_function("f3", lambda x: x, arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')")

# 4. Python types — passed directly or used as annotations
create_function("f4", lambda x: x, arg_types=[int], return_type=int)

@func()
def f5(x: int) -> int:
    return x

تحكّم في كيفية التعامل مع قيم NULL باستخدام parameter on_null.

from chdb import func, query, NullHandling

# Default: NULL in → NULL out, function not called
@func(return_type="Int64")
def add_one(x: int) -> int:
    return x + 1

print(query("SELECT add_one(NULL)"))  # NULL

# Pass NULL as None
@func(return_type="Int64", on_null="pass")
def null_safe(x):
    return 0 if x is None else x + 1

print(query("SELECT null_safe(NULL)"))  # 0

تحكّم في كيفية التعامل مع الاستثناءات باستخدام المعلمة on_error.

from chdb import func, query

# Default: exception propagates
@func(arg_types=["Int64", "Int64"], return_type="Int64")
def divide(a, b):
    return a // b

# print(query("SELECT divide(1, 0)"))  # Error: division by zero

# Ignore: exception → NULL
@func(arg_types=["Int64", "Int64"], return_type="Int64", on_error="ignore")
def safe_divide(a, b):
    return a // b

print(query("SELECT safe_divide(1, 0)"))   # NULL
print(query("SELECT safe_divide(10, 2)"))  # 5

تدعم UDFs دعمًا كاملًا الأنواع Date وDate32 وDateTime وDateTime64 مع مراعاة المناطق الزمنية.

from chdb import func, query
from datetime import datetime, timedelta, date

@func(arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')")
def add_one_hour(dt):
    return dt + timedelta(hours=1)

@func()
def get_year(d: date) -> int:
    return d.year

print(query("SELECT add_one_hour(toDateTime('2024-01-01 12:00:00', 'UTC'))"))  # 2024-01-01 13:00:00
print(query("SELECT get_year(toDate('2024-06-15'))"))  # 2024

• تُحوَّل قيم DateTime/DateTime64 المُدخلة إلى ClickHouse إلى كائنات datetime في بايثون مزودة بمعلومات timezone
• تحتفظ كائنات datetime في بايثون بمعلومات timezone عند إعادتها إلى ClickHouse
• يستخدم النوع DATETIME64 من chdb.sqltypes scale افتراضيًا قدره 6 (ميكروثوانٍ)، وهو ما يعادل DateTime64(6)

مُزيِّن لدوال بايثون من نوع UDF (دالة معرّفة من المستخدم) في chDB.

البنية

chdb.udf.chdb_udf(return_type='String')

المعلمات

ملاحظات

1. يجب أن تكون الدالة عديمة الحالة. يتم دعم UDFs فقط، وليس UDAFs.
2. نوع الإرجاع الافتراضي هو String. ويجب أن يكون نوع الإرجاع أحد أنواع بيانات ClickHouse.
3. يجب أن تستقبل الدالة وسيطات من النوع String. جميع الوسيطات سلاسل نصية.
4. سيتم استدعاء الدالة لكل سطر من الإدخال.
5. يجب أن تكون الدالة مكتوبة باستخدام pure بايثون. استورد جميع الوحدات المستخدمة داخل الدالة.
6. مُفسِّر بايثون المستخدم هو نفسه المستخدم لتشغيل البرنامج النصي.

مثال

@chdb_udf()
def sum_udf(lhs, rhs):
    return int(lhs) + int(rhs)

@chdb_udf()
def func_use_json(arg):
    import json
    # ... use json module

إنشاء ملفات تهيئة UDF وملفات البرامج النصية التنفيذية.

تنشئ هذه الدالة الملفات اللازمة لدالة معرّفة من قبل المستخدم (UDF) في chDB:

1. برنامجًا نصيًا تنفيذيًا بلغة بايثون لمعالجة بيانات الإدخال
2. ملف تهيئة XML لتسجيل UDF في ClickHouse

بنية

chdb.udf.generate_udf(func_name, args, return_type, udf_body)

المعاملات

الدوال والأدوات المساعدة لـ chDB.

تتضمن هذه الوحدة مجموعة متنوعة من الدوال المساعدة للعمل مع chDB، بما في ذلك استنتاج أنواع البيانات، وأدوات تحويل البيانات، وأدوات تصحيح الأخطاء.

يحوّل قائمة من القواميس إلى تنسيق عمودي.

تأخذ هذه الدالة قائمة من القواميس وتحوّلها إلى قاموس حيث يقابل كل مفتاح عمودًا، وتمثل كل قيمة قائمةً من قيم الأعمدة. تُمثَّل القيم المفقودة في القواميس على أنها None.

البنية

chdb.utils.convert_to_columnar(items: List[Dict[str, Any]]) → Dict[str, List[Any]]

المعلمات

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

مثال

>>> items = [
...     {"name": "Alice", "age": 30, "city": "New York"},
...     {"name": "Bob", "age": 25},
...     {"name": "Charlie", "city": "San Francisco"}
... ]
>>> convert_to_columnar(items)
{
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [30, 25, None],
    'city': ['New York', None, 'San Francisco']
}

يُسطِّح قاموسًا متداخلًا.

تأخذ هذه الدالة قاموسًا متداخلًا وتُسطِّحه عبر دمج المفاتيح المتداخلة باستخدام فاصل. وتُحوَّل قوائم القواميس إلى سلاسل JSON.

البنية

chdb.utils.flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '_') → Dict[str, Any]

المعلمات

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

مثال

>>> nested_dict = {
...     "a": 1,
...     "b": {
...         "c": 2,
...         "d": {
...             "e": 3
...         }
...     },
...     "f": [4, 5, {"g": 6}],
...     "h": [{"i": 7}, {"j": 8}]
... }
>>> flatten_dict(nested_dict)
{
    'a': 1,
    'b_c': 2,
    'b_d_e': 3,
    'f_0': 4,
    'f_1': 5,
    'f_2_g': 6,
    'h': '[{"i": 7}, {"j": 8}]'
}

يستنتج أنسب نوع بيانات لقائمة من القيم.

تفحص هذه الدالة قائمة من القيم وتحدد نوع البيانات الأنسب لتمثيل جميع القيم فيها. وهي تأخذ في الاعتبار أنواع الأعداد الصحيحة، والأعداد الصحيحة غير الموقعة، والأنواع العشرية، وأنواع الفاصلة العائمة، وتستخدم “string” افتراضيًا إذا تعذر تمثيل القيم بأي نوع رقمي أو إذا كانت جميع القيم None.

البنية

chdb.utils.infer_data_type(values: List[Any]) → str

المعلمات

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

يستنتج أنواع البيانات لكل عمود في بنية بيانات عمودية.

تحلّل هذه الدالة القيم في كل عمود وتستنتج أكثر أنواع البيانات ملاءمةً له، استنادًا إلى عيّنة من البيانات.

الصيغة

chdb.utils.infer_data_types`(column_data: Dict[str, List[Any]], n_rows: int = 10000) → List[tuple]

المعاملات

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

الفئات الأساسية: ABC

class chdb.rwabc.PyReader(data: Any)

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

abstractmethod (col_names: List[str], count: int) → List[Any]

المعلمات

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

الفئات الأساسية: ABC

class chdb.rwabc.PyWriter(col_names: List[str], types: List[type], data: Any)

جمِّع البيانات النهائية من الكتل وأعِدها. يجب أن تُنفِّذها الأصناف الفرعية.

abstractmethod finalize() → bytes

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

يحفظ أعمدة البيانات في كتل. يجب أن تنفّذه الفئات الفرعية.

abstractmethod write(col_names: List[str], columns: List[List[Any]]) → None

المعلمات

الفئات الأساسية: Exception

فئة الاستثناء الأساسية للأخطاء المرتبطة بـ chDB.

يتم رفع هذا الاستثناء عندما يفشل تنفيذ query في chDB أو عند حدوث error. وهو يرث من فئة Exception القياسية في Python ويقدّم معلومات عن الخطأ من ClickHouse engine الأساسي.

تتضمن رسالة الاستثناء عادةً معلومات تفصيلية عن error من ClickHouse، بما في ذلك أخطاء الصياغة، وعدم تطابق الأنواع، والجداول أو الأعمدة المفقودة، وغيرها من مشكلات تنفيذ query.

المتغيرات

أمثلة

>>> try:
...     result = chdb.query("SELECT * FROM non_existent_table")
... except chdb.ChdbError as e:
...     print(f"Query failed: {e}")
Query failed: Table 'non_existent_table' doesn't exist

>>> try:
...     result = chdb.query("SELECT invalid_syntax FROM")
... except chdb.ChdbError as e:
...     print(f"Syntax error: {e}")
Syntax error: Syntax error near 'FROM'

تسلسل مضمّن غير قابل للتغيير.

إذا لم يتم تمرير أي وسيطة، فسيُعيد المُنشئ tuple فارغًا. وإذا تم تحديد iterable، فستتم تهيئة tuple من عناصره.

إذا كانت الوسيطة من النوع tuple، فستكون القيمة المُعادة هي الكائن نفسه.

str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str