مرجع لغة طلب البحث (الإصدار 0.7)

تتيح لك لغة طلبات البحث عبر واجهة برمجة تطبيقات الرسوم المرئية في 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
جونرمز الحرف Eng12:00:00
1,000
2005-03-1935صواب2007-12-02 15:56:00
ديفرمز الحرف Eng12:00:00
500
2006-04-1927خطأقيمة فارغة
ساليرمز الحرف Eng13:00:00
600
2005-10-1030خطأقيمة فارغة
بنمجال المبيعات12:00:00
400
2002-10-1032صواب2005-03-09 12:30:00
دانامجال المبيعات12:00:00
350
2004-09-0825 ألفخطأقيمة فارغة
مايكMarketing13:00:00
800
2005-01-1024صواب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). التعبير haystack matches 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 (للعثور على أكبر قيمة في عمود) و+ (لإضافة قيم عمودين معًا في الصف نفسه).

يمكن أن تظهر بعض الدوال في أي عبارة، ويمكن أن يظهر بعضها في مجموعة فرعية من العبارات. وقد تم توثيق ذلك أدناه.

مثال:

تم اختيار هذا الجدول... في حال تطبيق طلب البحث هذا... ونحصل على هذه النتيجة.
الاسم الرواتب الضريبة تاريخ البدء
CANNOT TRANSLATE 1,000 100 2009/1/1
أفيتال 2,000 200 2008/1/21
Moran 3,000 300 2008/2/12
select upper(name), year(startDate)
الاسم السنة(تاريخ البدء)
أفيتال 2008
موران 2008
شارون 2009

 

يتم تحديد دوال معالجة البيانات التالية من خلال لغة طلب بحث واجهة برمجة تطبيقات الرسوم المرئية في 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()

لعرض قيمة العام من قيمة تاريخ أو تاريخ. على سبيل المثال: تعرض الدالة year(date "2009-02-05") القيمة 2009.

المعلمات: معلمة واحدة من النوع date أو datetime
نوع الإرجاع: number
month()

لعرض قيمة الشهر المستندة إلى الصفر من قيمة تاريخ أو تاريخ. على سبيل المثال: تعرض الدالة month(date "2009-02-05") القيمة 1. ملاحظة: تعتمد الأشهر على 0، لذلك تعرض الدالة 0 لشهر يناير (كانون الثاني) و1 شهر فبراير (شباط) وما إلى ذلك.

المعلمات: معلمة واحدة من النوع date أو datetime
نوع الإرجاع: number
day()

لعرض اليوم من الشهر بقيمة date أو قيمة datetime. على سبيل المثال: تعرض الدالة day(date "2009-02-05") القيمة 5.

المعلمات: معلمة واحدة من النوع date أو datetime
نوع الإرجاع: number
hour()

لعرض قيمة الساعة من تاريخ ووقت أو قيمة timeofday. على سبيل المثال: تعرض الدالة hour(timeofday "12:03:17") القيمة 12.

المعلمات: معلمة واحدة من النوع datetime أو timeofday
نوع الإرجاع: number
minute()

لعرض قيمة الدقيقة من قيمة datetime أو timeofday. على سبيل المثال: تعرض الدالة minute(timeofday "12:03:17") القيمة 3.

المعلمات: معلمة واحدة من النوع datetime أو timeofday
نوع الإرجاع: number
second()

لعرض القيمة الثانية من قيمة datetime أو timeofday. على سبيل المثال: تعرض الدالة second(timeofday "12:03:17") القيمة 17.

المعلمات: معلمة واحدة من النوع datetime أو timeofday
نوع الإرجاع: number
millisecond()

لعرض الجزء بالمللي ثانية من قيمة datetime أو timeofday. على سبيل المثال: تعرض الدالة millisecond(timeofday "12:03:17.123") القيمة 123.

المعلمات: معلمة واحدة من النوع datetime أو timeofday
نوع الإرجاع: number
quarter()

لعرض ربع السنة من قيمة date أو datetime. على سبيل المثال: تعرض الدالة quarter(date "2009-02-05") القيمة 1. تجدر الإشارة إلى أن الأرباع تستند إلى الرقم 1، لذلك تعرض الدالة الرقم 1 للربع الأول، واثنَين للربع الثاني، وما إلى ذلك.

المعلمات: معلمة واحدة من النوع date أو datetime
نوع الإرجاع: number
dayOfWeek()

لعرض اليوم من الأسبوع بقيمة date أو datetime. على سبيل المثال: تعرض الدالة dayOfWeek(date "2009-02-26") القيمة 5. يُرجى العِلم أنّ الأيام تستند إلى 1، لذلك تعرض الدالة الدالة 1 ليوم الأحد و2 ليوم الاثنين وما إلى ذلك.

المعلمات: معلمة واحدة من النوع date أو datetime
نوع الإرجاع: number
now()

لعرض قيمة تاريخ ووقت تمثل datetime الحالية في المنطقة الزمنية بتوقيت غرينتش.

المعلّمات: غير متوفّرة
نوع الإرجاع: datetime
dateDiff()

لعرض الفرق بالأيام بين قيمتَين date أو datetime. ملاحظة: يتم استخدام الأجزاء date من القيم فقط في العملية الحسابية وبالتالي تعرض الدالة دائمًا قيمة عدد صحيح. على سبيل المثال: تعرض الدالة dateDiff(date "2008-03-13", date "2008-02-12") القيمة 29، وتعرض dateDiff(date "2009-02-13", date "2009-03-13") القيمة -29. يتم اقتطاع قيم الوقت قبل المقارنة.

المعلّمات: معلّمتان من النوع date أو datetime (يمكن أن تكونا معلمتَين لكلٍّ منهما)
نوع الإرجاع: number
toDate()

لتحويل القيمة المقدمة إلى قيمة date.

  • عند عرض date، يتم عرض القيمة نفسها.
  • عند عرض datetime، يتم إرجاع جزء date. على سبيل المثال: تعرض toDate(dateTime "2009-01-01 12:00:00") القيمة "2009-01-01".
  • عند عرض number N، يتم عرض date N مللي ثانية بعد Epoch. تُعرَّف هذه الحقبة باسم 1,1970 كانون الثاني (يناير) عند الساعة 00:00:00 بتوقيت غرينيتش. على سبيل المثال: تعرض الدالة toDate(1234567890000) القيمة "2009-02-13".
المعلمات: معلمة واحدة من النوع date أو datetime أو number
نوع الإرجاع: date
upper()

لعرض string المحدد بأحرف كبيرة. على سبيل المثال: تعرض الدالة upper("foo") القيمة "FOO".

المعلمات: معلمة واحدة من النوع string
نوع الإرجاع: string
lower()

لعرض string المحدد بأحرف صغيرة. على سبيل المثال: تعرض الدالة lower("Bar") القيمة "bar".

المعلمات: معلمة واحدة من النوع 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