نظرة على لغة الاستعلام CAML Overview - 3

• نظرة على لغة الاستعلام CAML Overview - 1
• نظرة على لغة الاستعلام CAML Overview - 2
• نظرة على لغة الاستعلام CAML Overview - 3

تشكل عبارات عمليات المقارنة الجزء الأكبر من عبارات لغة الاستعلام CAML Query والجزء التالي سيركز على شرح كافة هذه العبارات:

عبارة BeginsWith

تستخدم هذه العبارة للبحث عن قيمة نصية في بداية قيمة حقل نصي ويتم استخدام هذه العبارة ضمن عبارة Where مباشرة أو ضمن عبارة And أو عبارة Or:

<Query>
    <Where>
     <BeginWith>
      <FieldRef Name="Title" />
      <Value Type="Text">Person</Value>
    </BeginWith>
</Where>
</Query>

العبارة السابقة تبحث عن كل العناصر التي يبدأ حقل العنوان Title بـ Person, ويتم استخدام العبارة BeginWith بنفس الطريقة في حال استخدام العبارة And أو العبارة Or.

عبارة Contains

تتشابه عبارة Contains مع عبارة BeginsWith في أنها تطبق على الحقول النصية والاختلاف هو أنها تبحث عن سلسلة نصية في جزء من أجزاء قيمة الحقل النصي أي ليس من الضروري أن تظهر السلسلة النصية في بداية قيمة الحقل, ويتم استخدام هذه العبارة ضمن عبارة Where مباشرة أو ضمن عبارة And أو عبارة Or:

<Query>
<Where>
 <And>
  <BeginsWith>
   <FieldRef Name="Title" />
   <Value Type="Text">Person</Value>
  </BeginsWith>
  <Contains>
   <FieldRef Name="Description" />
   <Value Type="Note">Ahmed</Value>
  </Contains
    </And>
</Where>
</Query>

المثال السابق يدمج بين العبارتين BeginsWith و Contains ضمن عبارة And, وبنفس الطريقة يمكن استخدام العبارة Contains مع عبارة Or أو حتى بشكل مباشر ضمن عبارة Where.

عبارة Eq

العبارة Eq هي اختصار للكلمة Equal وتستخدم للتأكد من أن قيمة حقل ما تساوي قيمة محددة سواء نصية أو رقمية أو حتى تاريخ ووقت أو أي قيمة أخرى. ويمكين استخدامها ضمن العبارة And أو العبارة Or أو مباشرة ضمن العبارة Where:

<Query>
<Where>
 <Eq>
  <FieldRef Name="Status" />
  <Value Type="Text">Completed</Value>
    </Eq>
</Where>
</Query>

طبعاً المثال السابق من السهل قراءته والذي يشتطر أن تكون قيمة الحقل Status تساوي القيمة Completed ليظهر عنصر القائمة في نتائج الاستعلام.

عبارة Neq

عبارة Neq هي اختصار لـ Not Equal والتي تفيد في التأكد من قيمة حقل ما لا تساوي قيمة معينة, نصية أو رمقية أو حتى تاريخ ووقت أو أي قيمة أخرى وهي بعكس العبارة Eq, وطريقة استخدامها مشابهة تماماً للعبارة Eq حيث يمكن استخدامها ضمن العبارة And أو العبارة Or أو مباشرة ضمن عبارة Where.

<Query>
<Where>
 <Neq>
  <FieldRef Name="Status" />
  <Value Type="Text">Completed</Value>
    </Neq>
</Where>
</Query>

عبارة Gt

عبارة Gt هي اختصار لـ Greater Than (أكبر تماماً من) وهي معامل رياضي تستخدم لمقارنة قيمة حقل ما مع قيمة من النوع الرقمي أو تاريخ أو وقت وطبعاً يمكن استخدام العبارة Gt ضمن عبارة And أو عبارة Or أو حتى ضمن عبارة Where مباشرة:

<Query>
<Where>
 <Gt>
  <FieldRef Name="DeadLine" />
        <Value Type="DateTime><Today /></Value>
 </Gt>
</Where>
</Query>

المثال السابق يقارن قيمة الحقل DeadLine وهو من النوع DateTime مع تاريخ اليوم الذي عُبر عنه باستخدام قيمة معرفة سابقاً ضمن لغة الاستعلام CAML وهذه القيمة هي عندها تظهر العناصر التي تكون فيها قيمة الحقل DeadLine أكبر تماماً من تاريخ اليوم.

عبارة Geq

عبارة Geq هي اختصار لـ Greater Than or Equal (أكبر أو يساوي) وهذه العبارة مشابهة تماماً للعبارة Gt في كيفية استخدامها, حيث يمكن استخدام العبارة Geq ضمن عبارة And أو عبارة Or أو حتى ضمن عبارة Where مباشرة:

<Query>
<Where>
 <Geq>
  <FieldRef Name="DeadLine" />
        <Value Type="DateTime><Today /></Value>
 </Geq>
</Where>
</Query>

عبارة Lt
عبارة Lt هي اختصار لـ Less Than (أصغر تماماً من) وهي معامل رياضي تستخدم لمقارنة قيمة حقل ما مع قيمة من النوع الرقمي أو تاريخ أو وقت وطبعاً يمكن استخدام العبارة Lt ضمن عبارة And أو عبارة Or أو حتى ضمن عبارة Where مباشرة:

<Query>
<Where>
 <Lt>
  <FieldRef Name="DeadLine" />
        <Value Type="DateTime><Today /></Value>
 </Lt>
</Where>
</Query>

المثال السابق يقارن قيمة الحقل DeadLine وهو من النوع DateTime مع تاريخ اليوم الذي عُبر عنه باستخدام قيمة معرفة سابقاً ضمن لغة الاستعلام CAML وهذه القيمة هي عندها تظهر العناصر التي تكون فيها قيمة الحقل DeadLine أصغر تماماً من تاريخ اليوم.

عبارة Leq
عبارة Leq هي اختصار لـ Less Than or Equal (أصغر أو يساوي) وهذه العبارة مشابهة تماماً للعبارة Lt في كيفية استخدامها, حيث يمكن استخدام العبارة Leq ضمن عبارة And أو عبارة Or أو حتى ضمن عبارة Where مباشرة:

<Query>
<Where>
 <Leq>
  <FieldRef Name="DeadLine" />
        <Value Type="DateTime><Today /></Value>
 </Leq>
</Where>
</Query>

عبارة IsNotNull
تستخدم عبارة IsNotNull لاستخراج العناصر التي يكون فيها الحقل المستهدف لا يحتوي على قيمة خالية, ويمكن استخدام عبارة IsNotNull ضمن عبارة And أو عبارة Or أو مباشرة ضمن عبارة Where:

<Query>
<Where>
 <IsNotNull>
  <FieldRef Name="DeadLine" />
 </IsNotNull >
</Where>
</Query>

ونلاحظ أن العبارة IsNotNull لا تتطلب وجود العبارة Value بعد العبارة FieldRef.

عبارة IsNull
تستخدم عبارة IsNull لاستخراج العناصر التي يكون فيها الحقل المستهدف يحتوي على قيمة خالية, ويمكن استخدام عبارة IsNull ضمن عبارة And أو عبارة Or أو مباشرة ضمن عبارة Where:

<Query>
<Where>
 <IsNull>
  <FieldRef Name="DeadLine" />
 </IsNull >
</Where>
</Query>

ونلاحظ أن العبارة IsNull لا تتطلب وجود العبارة Value بعد العبارة FieldRef.

نظرة على لغة الاستعلام CAML Overview - 2

• نظرة على لغة الاستعلام CAML Overview - 1
• نظرة على لغة الاستعلام CAML Overview - 2
• نظرة على لغة الاستعلام CAML Overview - 3

العمليات المنطقية في لغة الاستعلام CAML

ضمن لغة الاستعلام CAML يمكن استخدام تعليمتين منطقيتين فقط وهما And و Or وذلك ضمن عبارة Where مباشرة ولا يمكن استخدامهما إلا ضمن عبارة Where أو إحداهما ضمن الأخرى, وما يلي شرح لطريقة الاستخدام لـ Or و And:

عبارة Or

تستخدم عبارة Or ضمن عبارة And أو عبارة Where مباشرة وطبعاً من المعروف أن عبارة Or المنطقية تعمل بالطريقة التالية:

TRUE	OR	TRUE	TRUE
TRUE	OR	FALSE	TRUE
FALSE	OR	TRUE	TRUE
FALSE	OR	FALSE	FALSE

من الجدول السابق نستنتج أنه يكفي أن تكون إحدى العبارتين صحيحة لتكون نتيجة العبارة Or تساوي TRUE. وتستخدم العبارة Or ضمن لغة الاستعلام CAML كما يلي:

<or>...</or>

وضمن عبارة Or يمكن استخدام البعارات التالية فقط:

• And
• BeginsWith
• Contains
• DateRangesOverlap
• Eq
• Geq
• Gt
• IsNotNull
• IsNull
• Leq
• Lt
• Membership
• Neq

يمكن استخدام أي تتابع من العبارات السابقة ضمن عبارة Or مع الانتباه إلى أنه يجب استخدام عبارتين ضمن كل عبارة Or, كما في المثال التالي:

<Query>
   <Where>
     <Or>
       <Eq>
          <FieldRef Name="DisplayAtMain" />
          <Value Type="Boolean">1</Value>
       </Eq>
       <Eq>
          <FieldRef Name="Title" />
          <Value Type="Text">تجربة</Value>
       </Eq>
       </Or>
    </Where>
</Query>

في المثال السابق تظهر النتائج عندما تكون قيمة الحقل DisplayAtMain = 1 (TRUE) أو قيمة الحقل النصي Title تساوي "تجربة".
أما في حال استخدام العبارة Or من أجل أكثر من عبارتين فيجب تضمين عبارة Or داخل عبارة Or خارجية وذلك كما في المثال التالي:

<query>
    <Where>
        <Or>
         <And>
             <Eq>
                <FieldRef Name="DisplayAtMain" />
                <Value Type="Boolean">1</Value>
                </Eq>
                <Eq>
                <FieldRef Name="Title" />
                <Value Type="Text">تجربة</Value>
                </Eq>
             </And>
             <Gt>
                 <FieldRef Name="ID" />
                 <Value Type="Number">10</Value>
            </Gt>
        </Or>
    </Where>
</query>

في المثال السابق تظهر نتائج عندما يتحقق أحد الشرطين فإما (تكون قيمة الحقل DisplayAtMain = 1 (TRUE) و قيمة الحقل النصي Title تساوي "تجربة") أو (قيمة الحقل ID أكبر تماماً من القيمة 10). وهنا نلاحظ كيف تمت كتابة الشرطين الأولين ضمن عبارة And وعبارة And نفسها تم تضمينها ضمن عبارة Or.

عبارة And

تستخدم عبارة And ضمن عبارة Or أو عبارة Where مباشرة وطبعاً من المعروف أن عبارة And المنطقية تعمل بالطريقة التالية:

TRUE	OR	TRUE	TRUE
TRUE	OR	FALSE	FALSE
FALSE	OR	TRUE	FALSE
FALSE	OR	FALSE	FALSE

من الجدول السابق نستنتج أنه يجب أن تكون العبارتين صحيحتين لتكون نتيجة العبارة And تساوي TRUE. وتستخدم العبارة And ضمن لغة الاستعلام CAML كما يلي:

<And> … </And>

وضمن عبارة And يمكن استخدام البعارات التالية فقط:

• Or
• BeginsWith
• Contains
• DateRangesOverlap
• Eq
• Geq
• Gt
• IsNotNull
• IsNull
• Leq
• Lt
• Membership
• Neq

يمكن استخدام أي تتابع من العبارات السابقة ضمن عبارة And مع الانتباه إلى أنه يجب استخدام عبارتين ضمن كل عبارة And, كما في المثال التالي:

<Query>
    <Where>
        <And>
            <Eq>
                <FieldRef Name="DisplayAtMain" />
                <Value Type="Boolean">1</Value>
            </Eq>
            <Eq>
                <FieldRef Name="Title" />
                <Value Type="Text">تجربة</Value>
            </Eq>
        </And>
    </Where>
</Query>

في المثال السابق تظهر النتائج عندما تكون قيمة الحقل DisplayAtMain = 1 (TRUE) و قيمة الحقل النصي Title تساوي "تجربة".
أما في حال استخدام العبارة And من أجل أكثر من عبارتين فيجب تضمين عبارة And داخل عبارة And خارجية وذلك كما في المثال التالي:

<Query>
<Where>
    <And>
        <And>
         <Eq>
                <FieldRef Name="DisplayAtMain" />
                <Value Type="Boolean">1</Value>
            </Eq>
            <Eq>
                <FieldRef Name="Title" />
                <Value Type="Text">تجربة</Value>
            </Eq>
        </And>
        <Gt>
            <FieldRef Name="ID" />
            <Value Type="Number">10</Value>
        </Gt>
        </And>
</Where>
</Query>

في المثال السابق تظهر نتائج عندما يتحقق أحد الشرطين فإما (تكون قيمة الحقل DisplayAtMain = 1 (TRUE) و قيمة الحقل النصي Title تساوي "تجربة") و (قيمة الحقل ID أكبر تماماً من القيمة 10). وهنا نلاحظ كيف تمت كتابة الشرطين الأولين ضمن عبارة And وعبارة And نفسها تم تضمينها ضمن عبارة And أخرى.

نظرة على لغة الاستعلام CAML Overview - 1

• نظرة على لغة الاستعلام CAML Overview - 1
• نظرة على لغة الاستعلام CAML Overview - 2
• نظرة على لغة الاستعلام CAML Overview - 3

تستخدم هذه اللغة في Windows SharePoint Services (WSS) وذلك لأغراض متعددة ومختلفة, منها تعريف الحقول Fields والمناظير Views ضمن المواقع والقوائم في الـ SharePoint بشكل عام وسنبدأ إن شاء الله بكيفية استخدام الـ CAML في عملية استخراج البيانات من القوائم أو مايسمى بـ CAML Query.

هيكلية لغة الاستعلام CAML Query
جميع الصيغ التي تهدف إلى استخراج البيانات من أي قائمة لها الشكل التالي:

<query>
  <where>
    ...
  </where>
  <groupby>
    ...
  </groupby>
  <orderby>
    ...
  </orderby>
</query>

Query
حيث يعتبر العنصر Query أول عناصر هذه الصيغة وجميع العناصر الأخرى تنحصر بين و , والعناصر التي تأتي تحت هذا العنصر مباشرة هي:

• Where
• OrderBy
• GroupBy

ملاحظة: لا يجب استخدام هذا العنصر في حال استخدام الصف SPQuery عند كتابة شيفرة بلغة C# أو VB.NET لاستخراج البيانات من القوائم بالاعتماد على لغة الاستعلام CAML.

Where

يدل اسم هذا العنصر على وظيفته حيث يعبر عن وجود شرط يجب أن تحققه العناصر التي سيتم استخراجها من القائمة التي تنفذ عليها عملية الاستعلام, وضمنها يمكن استخدام العناصر التالية فقط:

• And
• BeginsWith
• Contains
• DateRangesOverlap
• Eq
• Geq
• Gt
• IsNotNull
• IsNull
• Leq
• Lt
• Membership
• Neq
• Or

وطبعاً يمكن الدمج بين العناصر السابقة لتوفير مجموعة من الشروط والفصل بينها باستخدام And أو Or, وإجراء عمليات حسابية بسيطة ويمكن استخدام ثوابت معرفة سابقاً في لغة الاستعلام CAML.

OrderBy

وظيفة هذا العنصر هو ترتيب نتائج الاستعلام وفقاً لحقل Field أو أكثر من حقول القائمة التي يُنفذ الاستعلام عليها, وصيغة هذا العنصر هي:

<OrderBy>
<FieldRef
Ascending = "TRUE" "FALSE"
Name = "Text" />
...
</OrderBy>

حيث استخدم العنصر FieldRef لتعريف اسم الحقل الذي سيتم ترتيب النتائج وفقاً له, وذلك بتحديد الخاصتين التاليتين:

• Ascending: وتقبل إحدى القيمتين TRUE أو FALSE فول كانت القيمة هي TRUE فسيتم ترتيب نتائج الاستعلام بشكل تصاعدي وفقاً للحقل الحالي (وهي القيمة الافتراضية) أما لو كانت القيمة هي FALSE فسيتم ترتيب نتائج الاستعلام بشكل تنازلي وفقاً للحقل الحالي.
• Name: اسم الحقل الذي سيتم الترتيب وفقاً له, وهنا يجب كتابة اسم الحقل بشكل صحيح مع الانتباه إلى أن اسم الحقل غالباً هو ليس نفسه الاسم الظاهر فهو يختلف باختلاف طريقة تسمية الحقل عند إنشاء أعمدة القائمة.

GroupBy

يُستخدم هذا العنصر بهدف تجميع النتائج حسب أحد حقول القائمة, ولها الصيغة التالية:

<GroupBy
  Collapse = "TRUE"  "FALSE">
  <FieldRef Name = "Field_Name"/>
</GroupBy>

وهذا العنصر لها خاصية اسمها Collapse وتأخذ إما القيمة TRUE عندها سيتم طي البيانات ضمن مجموعات أما FALSE فسيتم توسيع كل المجموعات وإظهار البيانات, أما العنصر FieldRef فيستخدم فقط الخاصية التالية:

• Name: اسم الحقل الذي سيتم التجميع وفقاً له, وهنا يجب كتابة اسم الحقل بشكل صحيح مع الانتباه إلى أن اسم الحقل غالباً هو ليس نفسه الاسم الظاهر فهو يختلف باختلاف طريقة تسمية الحقل عند إنشاء أعمدة القائمة.