تتيح لك لغة طلبات البحث عبر واجهة برمجة تطبيقات الرسوم المرئية في Google تنفيذ عمليات معالجة متنوعة للبيانات باستخدام طلب البحث لمصدر البيانات.
جدول المحتويات
مقدمة
عادةً ما تتوقّع التمثيل البصري بيانات في شكل محدّد. على سبيل المثال، يمكن أن يتوقع المخطط الدائري البيانات كعمودين: تصنيف نص وقيمة رقمية. قد لا تتطابق البيانات الموجودة في مصدر البيانات مع هذه البنية تمامًا. على سبيل المثال، قد يحتوي مصدر البيانات على أكثر من عمودين، أو قد لا يتطابق ترتيب الأعمدة مع الترتيب المتوقع في المخطط الدائري.
تتيح لغة طلب البحث إمكانية إرسال طلبات لمعالجة البيانات وتنسيقها إلى مصدر البيانات، والتأكد من مطابقة بنية البيانات المعروضة ومحتوياتها مع البنية المتوقعة.
وتكون بنية لغة طلب البحث مشابهة للغة SQL. ويجب أن يكون مطوّرو البرامج الذين لديهم دراية بلغة SQL قادرين على تعلّم لغة طلب البحث هذه واستخدامها بسرعة. يتوفّر العديد من البرامج التعليمية بلغة SQL على الويب. هناك بعض الاختلافات بين لغة طلب البحث وSQL هذه والتي تم توضيحها في قسم البنية.
وتجدر الإشارة إلى أنّه لا يُطلب من مصادر البيانات استخدام لغة طلب البحث لتنفيذ كل ميزات اللغة، أو في حال استخدامها. إذا لم يكن لديك سبب للاعتقاد بخلاف ذلك، يجب ألا تعتمد على مصدر البيانات لتطبيق جميع ميزات هذه اللغة.
استخدام لغة طلب البحث
يمكنك إرفاق سلسلة طلب بحث مع طلب مصدر بيانات من خلال ضبط سلسلة طلب البحث من داخل رمز JavaScript أو إعداد سلسلة طلب البحث كمعلَمة في عنوان URL لمصدر البيانات. إذا لم يتضمن طلبك سلسلة طلب بحث، يكون السلوك التلقائي لمصدر البيانات هو عرض جميع الصفوف والأعمدة باستخدام الترتيب والتنسيق التلقائي للصفوف/الأعمدة. ويمكنك تغيير ذلك من خلال تضمين سلسلة طلب بحث في طلبك إلى مصدر بيانات.
إعداد طلب البحث من JavaScript
لضبط سلسلة الطلب من داخل رمز JavaScript، عليك استدعاء طريقة setQuery
من فئة google.visualization.Query
.
var query = new google.visualization.Query(DATA_SOURCE_URL); query.setQuery('select dept, sum(salary) group by dept'); query.send(handleQueryResponse);
إعداد طلب البحث في عنوان URL لمصدر البيانات
يمكن إضافة سلسلة طلب البحث إلى عنوان URL لمصدر البيانات باستخدام المَعلمة tq
.
يسمح لك تعيين طلب البحث في معلمة عنوان URL بدلاً من جافا سكريبت باستخدام التمثيلات البصرية المكتوبة من قِبل مطورين آخرين بسهولة، وسيظل بإمكانك تخصيص الطلب.
يجب ترميز سلسلة طلب البحث بشكل صحيح كمعلمة عنوان URL.
يمكنك ترميز عنوان URL باستخدام دالة JavaScript encodeURIComponent
،
أو يمكنك تشفيره يدويًا باستخدام أداة الترميز في نهاية هذا القسم.
مثال:
جرِّب سلسلة طلب البحث التالية لجدول بيانات Google. (تجدر الإشارة إلى أنّ أرقام تعريف الأعمدة في جداول البيانات تكون دائمًا أحرفًا، وأنّ نص عنوان العمود المعروض في جدول البيانات المنشور هو تصنيفات وليس أرقام تعريف. ويجب استخدام المعرّف، وليس التصنيف، في سلسلة طلب البحث.)
select A, sum(B) group by A
عند التشفير، يصبح طلب البحث هذا:
select%20A%2C%20sum(B)%20group%20by%20A
لنفترض أن هذا هو عنوان URL لجدول بياناتك:
https://docs.google.com/a/google.com/spreadsheets/d/1r8_mfnZAvTFmT02JHi1XgOwn_-sLCR9XgmR8wEQ4uW4
أضف /gviz/tq?tq=
YOUR_QUERY_STRING إلى عنوان URL لجدول البيانات للحصول على سلسلة طلب البحث النهائية:
https://docs.google.com/a/google.com/spreadsheets/d/1r8_mfnZAvTFmT02JHi1XgOwn_-sLCR9XgmR8wEQ4uW4/gviz/tq?tq=select%A%2C%20sum(B)%20group%20by%20A
استخدم الأداة أدناه لتشفير أو فك تشفير سلسلة طلب بحث:
ملاحظة: يتطلب الوصول إلى بيانات جدول البيانات الخاصة تمرير بيانات اعتماد التفويض الصريحة باستخدام OAuth. راجِع قسم جداول بيانات Google: التفويض للحصول على مزيد من التفاصيل.
بنية اللغة
نظرة عامة
تم تصميم بنية لغة الاستعلامات في واجهة برمجة تطبيقات الرسوم المرئية في Google بحيث تكون مشابهة لبنية لغة الاستعلامات البنيوية (SQL). ومع ذلك، فهي مجموعة فرعية من لغة الاستعلامات البنيوية (SQL)، مع بعض الميزات الخاصة بها والتي ستحتاج إلى تعلّمها. إذا كنت معتادًا على استخدام لغة الاستعلامات البنيوية (SQL)، لن يكون من الصعب تعلّمها
جداول البيانات
يستخدم هذا المستند المصطلح جدول البيانات للإشارة إلى مجموعة النتائج من طلب البحث. يتكون جدول البيانات من صفوف وأعمدة. يتضمن كل عمود في جدول البيانات الخصائص التالية:
- المعرّف (أو رقم تعريف العمود). يُستخدم للإشارة إلى الأعمدة ضمن طلب البحث. يُرجى العِلم بأنّه يجب عدم محاولة الرجوع إلى عمود معيّن حسب التصنيف في طلب البحث، بل حسب المعرّف فقط. ملاحظة: يُرجى عدم استخدام أي معرّفات تتضمّن مسافات، لأنّه من الصعب إدارتها، لأنّ ذلك قد يتسبب في ارتكاب أخطاء صغيرة، ولكن يصعب العثور عليها، في الترميز. بالإضافة إلى ذلك، يجب وضع علامات اقتباس خلفية بين المعرّف الذي يتضمن مسافات.
- التصنيف:
string
يتم عرضها عادةً للمستخدمين. على سبيل المثال، وسيلة إيضاح ضمن مخطط دائري، أو رأس عمود في الجدول. - نوع البيانات. تشمل أنواع البيانات المتاحة
string
وnumber
وboolean
وdate
وdatetime
وtimeofday
. وستحتوي جميع قيم العمود على نوع بيانات يتطابق مع نوع العمود أو قيمةnull
. وتتشابه هذه الأنواع مع أنواع JavaScript، ولكنها ليست متطابقة معها، كما هو موضّح في القسم Litarys من هذه الصفحة. - نمط التنسيق. ويمكن لمصدر البيانات تحديد أنماط التنسيق لبعض أعمدته أو كلها. يمكنك إلغاء هذا النمط من خلال تضمين بند تنسيق.
جدول يتم استخدامه في جميع الأمثلة:
في هذا القسم، تشير جميع أمثلة طلبات البحث إلى الجدول التالي. رؤوس الأعمدة هي معرّفات الأعمدة.
الاسمstring |
القسمstring |
وقت الغداءtimeofday |
الراتب number |
تاريخ الوظيفةdate |
العمرnumber |
بين الكبارboolean |
أقدمية وقت البدءdatetime |
---|---|---|---|---|---|---|---|
جون | رمز الحرف Eng | 12:00:00 | 1,000 | 2005-03-19 | 35 | صواب | 2007-12-02 15:56:00 |
ديف | رمز الحرف Eng | 12:00:00 | 500 | 2006-04-19 | 27 | خطأ | قيمة فارغة |
سالي | رمز الحرف Eng | 13:00:00 | 600 | 2005-10-10 | 30 | خطأ | قيمة فارغة |
بن | مجال المبيعات | 12:00:00 | 400 | 2002-10-10 | 32 | صواب | 2005-03-09 12:30:00 |
دانا | مجال المبيعات | 12:00:00 | 350 | 2004-09-08 | 25 ألف | خطأ | قيمة فارغة |
مايك | Marketing | 13:00:00 | 800 | 2005-01-10 | 24 | صواب | 2007-12-30 14:40:00 |
بنود اللغة
تتكون بنية لغة طلب البحث من الجمل التالية. وتبدأ كل عبارة بكلمة أو كلمتين رئيسيتين. جميع البنود اختيارية. يتم الفصل بين العناصر باستخدام مسافات. يجب أن يكون ترتيب البنود على النحو التالي:
بند | الاستخدام |
---|---|
select |
لاختيار الأعمدة المطلوب عرضها، وبأي ترتيب. وفي حال حذفه، يتم عرض جميع أعمدة الجدول بالترتيب التلقائي. |
where |
لعرض الصفوف التي تطابق شرطًا فقط. وإذا تم حذفها، سيتم عرض جميع الصفوف. |
group by |
لتجميع القيم عبر الصفوف. |
pivot |
لتحويل القيم المميزة في الأعمدة إلى أعمدة جديدة. |
order by |
لترتيب الصفوف حسب القيم في الأعمدة. |
limit |
تحدّد عدد الصفوف المعروضة. |
offset |
لتخطي عدد معين من الصفوف الأولى. |
label |
لتعيين تصنيفات الأعمدة. |
format |
لتنسيق القيم في أعمدة معيّنة باستخدام أنماط تنسيق معيّنة |
options |
لتعيين خيارات إضافية. |
from |
تم استبعاد البند from من اللغة. |
اختيار
تُستخدم عبارة select
لتحديد الأعمدة المراد عرضها وترتيبها.
إذا لم يتم تحديد هذا البند، أو إذا تم استخدام select *
،
فسيتم عرض جميع أعمدة جدول مصدر البيانات، بالترتيب الأصلي.
وتتم الإشارة إلى الأعمدة من خلال المعرّفات (وليس حسب التصنيفات). على سبيل المثال، في جدول بيانات Google، تكون معرّفات الأعمدة حرفًا أو عمودًا من حرفين (A، B، C، ...).
يمكن أن تكون العناصر في عبارة select
معرّفات أعمدة أو نتائج
دالات التجميع أو الدالات الرقمية أو عوامل التشغيل.
أمثلة:
select *
select dept, salary
select max(salary)
في المثال التالي، تُستخدَم علامات الاقتباس للإشارة إلى أرقام تعريف الأعمدة التي تحتوي على مسافات (عنوان بريد إلكتروني) أو كلمات محجوزة (التاريخ):
select `email address`, name, `date`
تشغيل طلب البحث التالي على جدول الجدول:
select lunchTime, name
لعرض الاستجابة التالية:
وقت الغداء | اسم |
---|---|
12:00:00 | جون |
12:00:00 | ديف |
13:00:00 | سالي |
12:00:00 | بن |
12:00:00 | دانا |
13:00:00 | مايك |
أين
تُستخدم العبارة where
لعرض الصفوف التي تطابق
شرطًا معيّنًا فقط.
عوامل تشغيل المقارنة البسيطة هي <=, <, >, >=, =,
!=, <>
. ويعني عاملا المقارنة != <>
أنّهما غير متساوين. تتم مقارنة السلاسل من خلال القيمة المعجمية. يُرجى العِلم بأنّ المساواة
يحدّدها =
، وليس ==
كما هو الحال في معظم لغات الكمبيوتر.
تُجرى المقارنة مع null
باستخدام is null
أو is not null
.
يمكنك الانضمام إلى شروط متعددة باستخدام عوامل التشغيل المنطقية and
وor
وnot
. يمكن استخدام الأقواس لتحديد الأولوية الصريحة.
تتوافق عبارة Where أيضًا مع بعض عوامل تشغيل مقارنة السلاسل الأكثر تعقيدًا.
تأخذ عوامل التشغيل هذه سلسلتَين كوسيطات، وسيتم تحويل أي وسيطات غير نصية (على سبيل المثال، التواريخ أو الأرقام) إلى سلاسل قبل المقارنة. إنّ مطابقة السلسلة حسّاسة لحالة الأحرف (يمكنك استخدام
دالات رقمية
upper()
أو lower()
للتغلب على هذه المشكلة).
contains
- مطابقة سلسلة فرعية. تمامًا تكون قيمةcontains
part صحيحة إذا كانت part في أي مكان ضمن كل. مثال:where name contains 'John'
يتطابق مع "جون" أو "جون آدمز" أو "طارق جون فضية" ولكن لا يتطابق مع "جون آدامز".starts with
- مطابقة بادئة. value تكون قيمةstarts with
prefix صحيحة إذا كانت prefix في بداية value. أمثلة:where dept starts with 'engineering'
يتطابق مع "المهندسين" و"المدراء الهندسيين".where dept starts with 'e'
يطابق "الهندسة" و"الهندسة" و"هـ".ends with
- مطابقة لاحقة. القيمةends with
اللاحقة تكون صحيحة إذا كانت اللاحقة في نهاية value. مثال:where role ends with 'y'
يتطابق مع "cowboy" و"boy" و"y".matches
- تطابق التعبير العادي (preg). التعبير haystackmatches
needle يكون صحيحًا إذا كان التعبير العادي في needle يتطابق مع haystack. أمثلة: يتطابق اسمwhere country matches '.*ia'
مع الهند ونيجيريا، ولكنه لا يتطابق مع إنديانا. لاحظ أن هذا ليس بحثًا عموميًا، لذا لن يتطابق اسمwhere country matches 'an'
مع "كندا".like
- عملية بحث نصية تتيح استخدام حرفَي بدل: % لا يتطابقان مع أي حرف أو أكثر من أي نوع، و_ (شرطة سفلية)، تتطابق مع أي حرف واحد. وهو مماثل لعامل تشغيل SQL LIKE. مثال: يتطابقwhere name like fre%
مع "fre" و"fred" و"freddy".
أمثلة:
where salary >= 600 where dept != 'Eng' and date '2005-01-21' < hireDate where (dept<>'Eng' and isSenior=true) or (dept='Sales') or seniorityStartTime is null
تشغيل طلب البحث التالي على جدول الجدول:
select name where salary > 700
لعرض الاستجابة التالية:
اسم |
---|
جون |
مايك |
تجميع حسب
تُستخدم عبارة group by
لتجميع القيم عبر الصفوف.
يتم إنشاء صف واحد لكل مجموعة مختلفة من القيم في العبارة
التجميع حسب.
يتم ترتيب البيانات تلقائيًا حسب أعمدة التجميع، ما لم يتم تحديد خلاف ذلك من خلال عبارة order by
.
ملاحظة: إذا كنت تستخدم عبارة group by
، يجب إما أن يكون كل
عمود مُدرج في عبارة select
إما مُدرجًا في عبارة group by
،
أو مُرفقًا بواسطة دالة التجميع.
أمثلة:
select dept, max(salary) group by dept
تشغيل طلب البحث التالي على جدول الجدول:
select lunchTime, avg(salary), count(age) group by isSenior,lunchTime
لعرض الاستجابة التالية:
وقت الغداء | متوسط الراتب | عدد الأعمار |
---|---|---|
12:00:00 | 425 | 2 |
13:00:00 | 600 | 1 |
12:00:00 | 700 | 2 |
13:00:00 | 800 | 1 |
محوري
تُستخدم العبارة pivot
لتحويل القيم المختلفة في الأعمدة إلى أعمدة جديدة. على سبيل المثال، يؤدي المحور العمودي "السنة" إلى إنتاج جدول يحتوي على عمود لكل سنة مميزة يظهر في الجدول الأصلي.
وقد يكون هذا الإجراء مفيدًا إذا رسم رسم بياني خطي لكل عمود كخط منفصل مثلاً. إذا كنت ترغب في رسم خط منفصل لكل عام،
وكانت "السنة" أحد أعمدة الجدول الأصلي، فسيكون الخيار الجيد
هو استخدام عملية محورية لإجراء تحوّل البيانات اللازم.
ملاحظة: إذا كنت تستخدم عبارة pivot
،
يجب عندئذٍ أن يكون كل عمود مُدرج في عبارة select
إما مُدرجًا في عبارة group by
، أو أن يكون محاطًا بـ دالة للتجميع
.
ونظرًا لأنّ الصفوف المتعددة قد تحتوي على القيم نفسها للأعمدة المحورية،
يتضمّن المحور التجميع. يُرجى العلم أنه عند استخدام pivot
بدون
استخدام group by
، سيحتوي جدول النتائج على صف واحد فقط.
على سبيل المثال، يتم تشغيل طلب البحث التالي في جدول الأمثلة:
select sum(salary) pivot dept
لعرض الاستجابة التالية:
راتب المهندس المعماري | مجموع رواتب التسويق | راتب إجمالي المبيعات |
---|---|---|
2100 | 800 | 750 |
وذلك لأن 2100 هي مجموع رواتب قسم الهندسة، و800 لقسم التسويق وما إلى ذلك.
يمكن أن يكون استخدام pivot
مع group by
أكثر فائدة، لأنه ينشئ جدولاً تحتوي فيه كل خلية على نتيجة للتجميع ذي الصلة والعمود ذي الصلة. على سبيل المثال، يمكن تشغيل طلب البحث التالي في جدول الجدول:
select dept, sum(salary) group by dept pivot lunchTime
لعرض الاستجابة التالية:
قسم | 12:00:00 - الراتب الإجمالي | راتب مجموع 13:00:00 |
---|---|---|
رمز الحرف Eng | 1500 | 600 |
Marketing | قيمة فارغة | 800 |
مجال المبيعات | 750 | قيمة فارغة |
يمكنك أيضًا "عكس" هذا الجدول، وتبديل الأعمدة والصفوف، من خلال التبديل بين عمودَي pivot
وgroup by
. تشغيل طلب البحث التالي على
جدول الأمثلة:
select lunchTime, sum(salary) group by lunchTime pivot dept
لعرض الاستجابة التالية:
وقت الغداء | راتب المهندس المعماري | مجموع رواتب التسويق | راتب إجمالي المبيعات |
---|---|---|---|
12:00:00 | 1500 | قيمة فارغة | 750 |
13:00:00 | 600 | 800 | قيمة فارغة |
يمكنك أيضًا استخدام أكثر من عمود في عبارة pivot
. وفي هذه الحالة، تتألف أعمدة جدول الاستجابة من جميع مجموعات القيم الفريدة في الأعمدة الموجودة في الجدول الأصلي. على سبيل المثال، يمكنك تشغيل طلب البحث التالي في example table:
select sum(salary) pivot dept, lunchTime
لعرض الاستجابة التالية:
Eng,12:00:00 الراتب الإجمالي | Eng,13:00:00 الراتب الإجمالي | تسويق,13:00:00 الراتب الإجمالي | المبيعات، 12:00:00 الراتب |
---|---|---|---|
1500 | 600 | 800 | 750 |
يُرجى العِلم بأنّه لا يتم تقديم أعمدة في جدول الردود إلّا للنُسخ التي تظهر في الجدول الأصلي. ولهذا السبب، ليس هناك عمود "للتسويق، 12:00:00" أو "للمبيعات"، 13:00:00.
كما يمكن استخدام أكثر من مجموعة. على سبيل المثال، يؤدي تشغيل طلب البحث التالي في example table:
select sum(salary), max(lunchTime) pivot dept
لعرض الاستجابة التالية:
راتب المهندس المعماري | مجموع رواتب التسويق | راتب إجمالي المبيعات | الحد الأقصى لوقت الغداء للمهندس | الحد الأقصى لوقت الغداء للتسويق | الحد الأقصى لوقت الغداء للمبيعات |
---|---|---|---|---|---|
2100 | 800 | 750 | 13:00:00 | 13:00:00 | 12:00:00 |
يمكنك دمج تجميعات متعددة في عبارة select
وأعمدة متعددة في عبارة group by
وأعمدة متعددة في عبارة pivot
. يتم إجراء التجميع داخليًا باستخدام تسلسل للأعمدة في المجموعة باستخدام الجمل المحورية والفقرات المحورية.
قد لا تظهر الأعمدة المحددة في عبارة pivot
في العبارات select
أو group by
أو order by
.
عند استخدام pivot
، لا يمكن أن تحتوي عبارة order by
على أي أعمدة للتجميع. والسبب في ذلك أنه يتم إنشاء العديد من الأعمدة في جدول النتائج لكل
تجميع محدّد في عبارة select
. ومع ذلك، يمكنك تنسيق أعمدة التجميع عند استخدام pivot
. وينتج عن هذا التنسيق أن جميع الأعمدة الجديدة ذات الصلة بالتجميع المحدد، التي يتم إنشاؤها بواسطة العملية المحورية، تم تنسيقها بواسطة النمط المحدد. في
المثال أعلاه، ستؤثّر إضافة format sum(salary) "some_format_string"
في الأعمدة التالية: الراتب الإجمالي: الرواتب الإجمالية والرواتب الإجمالية.
يمكنك تصنيف أعمدة التجميع. إذا لم يتم تحديد تصنيف في
السمة label
، سيتألف تصنيف العمود الذي يتم إنشاؤه نتيجة
التطوّر من قائمة القيم في الأعمدة المحورية، ونوع
التجميع (الحد الأدنى والأقصى والمجموع و...) وتصنيف العمود المجمّع.
على سبيل المثال: "Eng,12:00:00 sum الراتب". إذا تم تحديد تجميع واحد فقط في عبارة select
، تتم إزالة جزء التجميع من التصنيف ويتم الاحتفاظ فقط بقائمة القيم في الأعمدة المحورية. على سبيل المثال: "Eng,12:00:00". عندما تحدّد عبارة label
تصنيفًا لعمود التجميع، يتم إلحاق التصنيف المطلوب بقائمة القيم، وذلك عند توفّر تجميع واحد فقط في العبارة select
وعندما يتوفّر أكثر من تصنيف واحد. على سبيل المثال، سينتج عن الدالة label sum(salary) "sumsal"
تصنيفات الأعمدة "الإنكليزية، 12:00:00 المجموع"، و"الهندسة، 13:00:00 المجموع"، وما إلى ذلك.
الترتيب حسب
تُستخدم عبارة order by
لفرز الصفوف حسب القيم في أعمدة محددة.
يمكن أن تكون العناصر في عبارة order by
معرّفات أعمدة أو نتائج
دالات التجميع أو الدالات الرقمية أو عوامل التشغيل.
أمثلة:
order by dept, salary desc
select dept, max(salary) group by dept order by max(salary)
الحدّ الأقصى المسموح به
تُستخدم العبارة limit
للحد من عدد الصفوف المعروضة.
مثال:
limit 100
الإزاحة
تُستخدم عبارة offset
لتخطي عدد معين من الصفوف الأولى.
إذا تم استخدام عبارة limit
، يتم تطبيق offset
أولاً: على سبيل المثال، تعرض limit 15 offset
30
الصفوف من 31 إلى 45.
أمثلة:
offset 10 limit 30 offset 210
التصنيف
تُستخدم العبارة label
لضبط التصنيف لعمود واحد أو أكثر.
لاحظ أنه لا يمكنك استخدام قيمة تصنيف بدلاً من المعرف في طلب البحث.
يمكن أن تكون العناصر في عبارة label
معرّفات أعمدة أو نتائج
دالات التجميع أو دوال رقمية أو عوامل تشغيل.
البنية:
label column_id label_string [,column_id label_string]
column_id
- معرِّف العمود الذي يتم تخصيصه للتصنيف.
label_string
- التصنيف المطلوب تعيينه لهذا العمود. وتستخدم العديد من العروض المرئية تصنيف العمود كنص لعرضه على المستخدم النهائي، مثل تصنيف التسمية التوضيحية في رسم بياني دائري. تكون التصنيفات حرفيًا لسلسلة، وتتّبع قواعد البنية هذه.
مثال:
يحدّد المثال التالي تصنيف عمود القسم إلى "القسم"، وتصنيف عمود الاسم على "اسم الموظف"، وتصنيف عمود الموقع على "الموقع الجغرافي للموظف":
label dept 'Department', name "Employee Name", location 'Employee Location'
التنسيق
تُستخدم العبارة format
لتحديد قيمة منسقة للخلايا في عمود واحد أو أكثر. يجب أن تتضمن البيانات المعروضة قيمة فعلية وقيمة منسّقة لكل خلية في عمود منسق. تستخدم العديد من التمثيلات البصرية القيمة غير المنسقة
للعمليات الحسابية، ولكن تستخدم القيمة المنسّقة للعرض. يتم عادة عرض الأنماط التي تحددها في هذه العبارة في خاصية pattern للأعمدة المقابلة.
بنية النمط:
number
وdate
وtimeofday
وdatetime
- نمطا التاريخ والرقم اللذين تم تعريفهما بواسطة وحدة المعالجة المركزية (ICU)
-
boolean
- النمط هو
string
بالتنسيق "value-if-true:value-if-false".
مثال:
format salary '#,##0.00', hireDate 'dd-MMM-yyyy', isSenior 'Yes!:Not yet'
الخيارات
تُستخدم عبارة options
للتحكم في الخيارات الإضافية
لتنفيذ طلب البحث. الكلمات الرئيسية المحتملة التي يمكن أن تتبع عبارة
options
هي:
-
no_format
لإزالة القيم المنسقة من النتيجة، وترك القيم الأساسية فقط. ويمكن استخدامها عندما لا يستخدم التمثيل البصري المحدّد القيم المنسّقة لتقليل حجم الاستجابة. -
no_values
يزيل القيم الأساسية من النتيجة، ويترك القيم المنسّقة فقط. ويمكن استخدامها عندما يستخدم التمثيل البصري المحدّد القيم المنسّقة فقط لتقليل حجم الاستجابة.
وظائف معالجة البيانات
هناك أنواع متعددة من عوامل التشغيل والدوال التي تسمح لك بمعالجة البيانات أو تجميعها في عمود واحد، أو مقارنة البيانات أو دمجها على مستوى الأعمدة. وتشمل الأمثلة sum() (لإضافة جميع القيم في عمود) وMax (للعثور على أكبر قيمة في عمود) و+ (لإضافة قيم عمودين معًا في الصف نفسه).
يمكن أن تظهر بعض الدوال في أي عبارة، ويمكن أن يظهر بعضها في مجموعة فرعية من العبارات. وقد تم توثيق ذلك أدناه.
مثال:
تم اختيار هذا الجدول... | في حال تطبيق طلب البحث هذا... | ونحصل على هذه النتيجة. | ||||||||||||||||||||||||
|
select upper(name), year(startDate) |
|
يتم تحديد دوال معالجة البيانات التالية من خلال لغة طلب بحث واجهة برمجة تطبيقات الرسوم المرئية في Google:
دوال التجميع
يتم تمرير دوال التجميع إلى معرّف عمود واحد، وتنفيذ إجراء عبر جميع القيم في كل مجموعة (يتم تحديد المجموعات من خلال عبارات group by
أو pivot
، أو جميع الصفوف في حال عدم استخدام هذه العبارات).
أمثلة:
select max(salary) // Returns a table with one column and one row. select max(salary) group by dept // Returns a table with the max salary for each dept column value. select max(salary) pivot dept // Returns a one-row table with a column for each dept, // and the max salary for that department.
يمكن استخدام دوال التجميع في عبارات select
وorder by
وlabel
وformat
.
ولا يمكن أن تظهر في عبارات where
أو group by
أو pivot
أو
limit
أو offset
أو options
.
في ما يلي وظائف التجميع المتوافقة:
الاسم | الوصف | أنواع الأعمدة المتوافقة | نوع القيمة التي يتم عرضها |
---|---|---|---|
avg() |
لعرض متوسط قيمة جميع القيم في العمود لمجموعة. | number |
number |
count() |
لعرض عدد العناصر في العمود المحدد لمجموعة. ولا يتم احتساب الخلايا الفارغة. | أي نوع | number |
max() |
لعرض الحد الأقصى للقيمة في عمود المجموعة. تتم مقارنة التواريخ مع
صغر التواريخ، ويتم مقارنة string أبجديًا، مع مراعاة حساسية حالة الأحرف. |
أي نوع | النوع نفسه كعمود |
min() |
لعرض أدنى قيمة في عمود المجموعة. تتم مقارنة التواريخ مع
صغر التواريخ، ويتم مقارنة string أبجديًا، مع مراعاة حالة الأحرف. |
أي نوع | النوع نفسه كعمود |
sum() |
لعرض مجموع كل القيم في العمود لمجموعة. | number |
number |
ملاحظة: لا يمكن لدوال التجميع سوى استخدام معرّف العمود كوسيطة:
max(startDate) // OK min(firstScore) + min(secondScore) // OK max(year(startDate)) // INVALID. max requires column ID sum(salary + perks) // INVALID. sum requires column ID.
الدالات الرقمية
تعمل الدوال العددية على أكثر من صفر أو أكثر من المعلمات لإنشاء قيمة أخرى. يمكن تمرير الدالات الكمّية أي تعبير يتم تقييمه بمعلمة النوع المناسب. تجدر الإشارة إلى أن هذه الأنواع هي الأنواع المحدّدة في قسم الحرفية في هذا المستند، والتي قد تختلف قليلاً عن كائنات JavaScript ذات الأسماء المتشابهة.
تجدر الإشارة إلى أنه سيتم تغيير اسم العمود من خلال لفّه في دالة رقمية.
يمكن أن تأخذ الدالات الرقمية أي معلمة يتم تقييمها بقيمة واحدة:
year(max(startDate)) datediff(now(), todate(1234567890000))
يمكن استخدام الدوال العددية في أي من العبارات التالية: select
وwhere
وgroup by
وpivot
وorder by
وlabel,
و
format
.
الاسم | |
---|---|
year() |
لعرض قيمة العام من قيمة تاريخ أو تاريخ. على سبيل المثال:
تعرض الدالة المعلمات: معلمة واحدة من النوع
date أو datetime نوع الإرجاع:
number |
month() |
لعرض قيمة الشهر المستندة إلى الصفر من قيمة تاريخ أو تاريخ. على سبيل المثال:
تعرض الدالة المعلمات: معلمة واحدة من النوع
date أو datetime نوع الإرجاع:
number |
day() |
لعرض اليوم من الشهر بقيمة المعلمات: معلمة واحدة من النوع
date أو datetime نوع الإرجاع:
number |
hour() |
لعرض قيمة الساعة من تاريخ ووقت أو قيمة المعلمات: معلمة واحدة من النوع
datetime أو timeofday نوع الإرجاع:
number |
minute() |
لعرض قيمة الدقيقة من قيمة المعلمات: معلمة واحدة من النوع
datetime أو timeofday نوع الإرجاع:
number |
second() |
لعرض القيمة الثانية من قيمة المعلمات: معلمة واحدة من النوع
datetime أو timeofday نوع الإرجاع:
number |
millisecond() |
لعرض الجزء بالمللي ثانية من قيمة المعلمات: معلمة واحدة من النوع
datetime أو timeofday نوع الإرجاع:
number |
quarter() |
لعرض ربع السنة من قيمة المعلمات: معلمة واحدة من النوع
date أو datetime نوع الإرجاع:
number |
dayOfWeek() |
لعرض اليوم من الأسبوع بقيمة المعلمات: معلمة واحدة من النوع
date أو datetime نوع الإرجاع:
number |
now() |
لعرض قيمة تاريخ ووقت تمثل المعلّمات: غير متوفّرة
نوع الإرجاع:
datetime |
dateDiff() |
لعرض الفرق بالأيام بين قيمتَين المعلّمات: معلّمتان من النوع
date أو datetime (يمكن أن تكونا معلمتَين لكلٍّ منهما)نوع الإرجاع:
number |
toDate() |
لتحويل القيمة المقدمة إلى قيمة
المعلمات: معلمة واحدة من النوع
date أو datetime أو number نوع الإرجاع:
date |
upper() |
لعرض المعلمات: معلمة واحدة من النوع
string نوع الإرجاع:
string |
lower() |
لعرض المعلمات: معلمة واحدة من النوع
string نوع الإرجاع:
string |
عوامل التشغيل الحسابية
يمكنك استخدام معاملات الحساب لإجراء العمليات الحسابية على أي شيء يتم تقييمه لرقم واحد (أي ناتج ناتج الدوال المجمّعة أو عوامل التشغيل أو الثوابت).
أمثلة:
select empSalary - empTax select 2 * (max(empSalary) / max(empTax))
يتم تحديد عوامل التشغيل التالية:
الاسم | الوصف | المَعلمات | نوع القيمة التي يتم عرضها |
---|---|---|---|
+ |
لعرض مجموع قيمتَين (number ). |
ثانيتان number |
number |
- |
لعرض الفرق بين قيمتين (number ). |
ثانيتان number |
number |
* |
لعرض ناتج number من ثانيتَين. |
ثانيتان number |
number |
/ |
لعرض حاصل ضرب number . القسمة على صفر تُرجع قيمة خالية. |
ثانيتان number |
number |
عناصر اللغة
الكتابات
القيم الحرفية هي قيم تُستخدم للمقارنات أو المهام. يمكن أن تكون القيم الحرفية string
أو أرقام أو قيم منطقية أو أنواعًا مختلفة من التاريخ/الوقت. في ما يلي بعض الأمثلة على
الأحرف الحرفية المستخدمة في بنية طلب البحث:
where startDate < date "2008-03-18" // date "2008-03-18" is a date literal
limit 30 // 30 is a numeric literal
format salary '#,##0.00', isSenior 'not yet:of course!' // '#,##0.00' and 'not yet:of course!' are both string
literals
في ما يلي التنسيقات لكل نوع من الحرفي:
string
يجب تضمين حرفي واحد (
string
) بين علامتَي اقتباس مفردتين أو مزدوجتَين. أمثلة:"fourteen" 'hello world' "It's raining"
-
number
- يتم تحديد القيم الحرفية الرقمية بتدوين عشري.
أمثلة:
3 3.0 3.14 -71 -7.2 .6
-
boolean
- الأحرف الحرفية المنطقية إما
true
أوfalse
. -
date
- استخدِم الكلمة الرئيسية
date
متبوعة بكلمةstring
حرفية بالتنسيقyyyy-MM-dd
. مثال:date "2008-03-18"
. -
timeofday
- يمكنك استخدام الكلمة الرئيسية
timeofday
متبوعة بكلمة حرفيةstring
HH:mm:ss[.SSS]
مثال:timeofday "12:30:45"
. -
datetime
- التاريخ والوقت، باستخدام إما الكلمة الرئيسية
datetime
أو الكلمة الرئيسيةtimestamp
متبوعة بكلمةstring
حرفيةyyyy-MM-dd HH:mm:ss[.sss]
. مثال:datetime '2008-03-18 12:30:34.123'
المعرّفات
المعرِّفات (أو المعرِّفات) هي نصوص string
تحدِّد الأعمدة.
ملاحظة مهمة: إذا كان المعرّف
- تحتوي على مساحات،
- هي كلمة محجوزة،
- يحتوي على أي شيء باستثناء الأحرف الأبجدية الرقمية أو الشُرط السفلية ([a-zA-Z0-9_])، أو
- يبدأ برقم
يجب إحاطته بعلامات اقتباس خلفية (وليس علامات اقتباس مفردة).
بخلاف ذلك، لا يلزم إدراج المعرّف. (تجدر الإشارة إلى أنه ليست كل الكلمات الرئيسية التي تم تحديدها باستخدام البنية عبارة عن كلمات محجوزة؛ لذا يمكنك، على سبيل المثال، استخدام "max" كمعرّف، بدون الحاجة إلى اقتباسها مرة أخرى.)
أمثلة: col1 employee_table `start
date` `7 days traffic` `select`
ننصح بعدم اختيار معرّف يتطلّب علامات اقتباس خلفية لأنه من السهل نسيان استخدام علامات الاقتباس، أو استخدام "علامات الاقتباس الفردية" بدون قصد بدلاً من علامات الاقتباس. هذه أخطاء شائعة وغالبًا ما يصعب تصحيحها.
الحساسية لحالة الأحرف
والمعرّفات وسلاسل الأحرف حسّاسة لحالة الأحرف. وتكون جميع عناصر اللغة الأخرى غير حساسة لحالة الأحرف.
الكلمات المحجوزة
يجب إعادة اقتباس الكلمات المحجوزة التالية إذا تم استخدامها كمعرّف:
and asc by date datetime desc false format group label limit not offset options or order pivot select timeofday timestamp true where