> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-revert-104359-revert-104251-parquet-single.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> يتيح هذا المحرك القراءة من جدول في Google BigQuery والكتابة إليه، بما في ذلك مجموعات البيانات العامة.

# محرك جداول BigQuery

يتيح محرك `BigQuery` قراءة البيانات من جدول والكتابة إليه في [Google BigQuery](https://cloud.google.com/bigquery)، بما في ذلك مجموعات البيانات العامة.

تستخدم القراءة واجهة برمجة تطبيقات REST الخاصة بـ BigQuery (`tabledata.list`)، لذلك لا يمكن قراءة سوى الجداول الأصلية، أما العروض والعروض المادية والجداول الخارجية فلا يمكن قراءتها. وتستخدم الكتابة عمليات الإدراج المتدفقة (`tabledata.insertAll`)، التي تتطلب تمكين الفوترة للمشروع.

عمليات الكتابة ليست ذرية: يُرسل أمر `INSERT` كبير على دفعات (بحد أقصى 500 صف لكل طلب، ويُقسّم أيضًا ليبقى ضمن حد BigQuery البالغ 10 MB لحجم الطلب). وقد ينجح الطلب الواحد جزئيًا (إذ يمكن لـ BigQuery تثبيت بعض صفوف الطلب ورفض الصفوف الأخرى مع `insertErrors`)، وقد تُرفض دفعة لاحقة بعد قبول دفعات سابقة — وفي كلتا الحالتين، تبقى الصفوف المثبتة بالفعل في BigQuery بينما يُبلغ الاستعلام عن خطأ. يحمل كل صف `insertId` ثابتًا (مشتقًا من معرّف الاستعلام والموضع الترتيبي للصف) لكي يزيل BigQuery، بأفضل جهد، تكرار الصفوف التي أُعيدت محاولتها؛ ولأن `insertId` يعتمد على الموضع الترتيبي، فإن إعادة تشغيل أمر `INSERT` نفسه تزيل التكرار فقط عند تقديم الصفوف بالترتيب نفسه (على سبيل المثال، عند التشغيل أحادي الخيط، مع `max_threads = 1` و`max_insert_threads = 1`). راجع [قيود دالة الجدول `bigquery`](/ar/reference/functions/table-functions/bigquery#limitations) للتفاصيل.

<div id="creating-a-table">
  ## إنشاء جدول
</div>

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db.]table_name
[(
    name1 [type1],
    name2 [type2],
    ...
)]
ENGINE = BigQuery(project, dataset, table[, access_token][, key = value, ...])
```

قائمة الأعمدة اختيارية: عند عدم تحديدها، يُستنتج المخطط من مخطط جدول BigQuery. وعند تحديدها، يمكن أن تكون الأعمدة مجموعة فرعية من أعمدة BigQuery، ويجب تعريف كل عمود بالنوع المطابق تماماً لما يعيّنه له مخطط BigQuery (راجع [تعيين أنواع البيانات](/ar/reference/functions/table-functions/bigquery#data-type-mapping)). يمكن قراءة جدول يحذف تعريفه حقلاً `REQUIRED` في BigQuery ليس له تعبير قيمة افتراضية، ولكن لا يمكن الكتابة إليه: إذ ترفض عمليات الإدراج المتدفقة في BigQuery الصفوف التي لا تتضمن حقلاً كهذا، ولذلك يُرفض `INSERT` مسبقاً. عندما يعرّف الحقل `REQUIRED` المحذوف `defaultValueExpression`، يملأ BigQuery القيمة الافتراضية، ويظل الجدول قابلاً للكتابة. يُعيَّن `RECORD` ذو `NULLABLE` إلى `Nullable(Tuple(...))` لضمان حفظ سجلات `NULL` دون فقدان عند النقل ذهاباً وإياباً؛ ويتطلب إنشاء مثل هذا الجدول، سواء استُنتج مخططه أو عُرّف صراحةً، الإعداد `enable_nullable_tuple_type`، كما هو الحال مع أي عمود `Nullable(Tuple)`. عند تعريف الأعمدة صراحةً، يمكن بدلاً من ذلك تعريف حقل `RECORD` على أنه `Tuple(...)` عادي لتجنب هذا الإعداد، مقابل تحويل `NULL` للسجل بأكمله إلى tuple افتراضي؛ والاختلاف الوحيد المقبول عن النوع المستنتج هو إزالة `Nullable` الذي يغلّف `Tuple` الخاص بـ `RECORD`، وفقط في ذلك السجل نفسه — إذ لا يمكن نقل قابلية القيم الفارغة إلى سجل آخر، داخلياً كان أم خارجياً.

**معلمات المحرك**

* `project` — مشروع Google Cloud الذي يملك مجموعة البيانات.
* `dataset` — اسم مجموعة البيانات.
* `table` — اسم الجدول.
* `access_token` — رمز وصول OAuth 2.0 (وسيطة موضعية اختيارية).

يمكن أيضاً تمرير المعلمات على هيئة [مجموعة مسماة](/ar/concepts/features/configuration/server-config/named-collections) مع تجاوزات `key = value`. راجع [دالة الجدول `bigquery`](/ar/reference/functions/table-functions/bigquery#arguments) للاطلاع على القائمة الكاملة للمفاتيح ووصف [طرق المصادقة](/ar/reference/functions/table-functions/bigquery#authentication). يجب توفير طريقة مصادقة واحدة فقط؛ وبالنسبة إلى جدول دائم، يُفضَّل استخدام `service_account_key` أو `refresh_token` بدلاً من `access_token`، لأن رموز الوصول تنتهي صلاحيتها خلال ساعة.

<div id="usage-example">
  ## مثال على الاستخدام
</div>

```sql theme={null}
CREATE TABLE shakespeare
ENGINE = BigQuery('bigquery-public-data', 'samples', 'shakespeare',
                  service_account_key = '{"type": "service_account", ...}');

SELECT word, word_count FROM shakespeare ORDER BY word_count DESC LIMIT 3;

CREATE TABLE events (id Int64, payload Nullable(String))
ENGINE = BigQuery('my-project', 'my_dataset', 'events',
                  service_account_key = '{"type": "service_account", ...}');

INSERT INTO events VALUES (1, 'started');
```

<div id="related">
  ## ذات صلة
</div>

* [دالة الجدول `bigquery`](/ar/reference/functions/table-functions/bigquery)