11. التعبيرات والتصفية وحساب القيم

تلميح

تحتاج مقتطفات الشيفرة في هذه الصفحة إلى الاستيرادات التالية إذا كنت خارج وحدة تحكم pyqgis:

from qgis.core import (
    edit,
    QgsExpression,
    QgsExpressionContext,
    QgsFeature,
    QgsFeatureRequest,
    QgsField,
    QgsFields,
    QgsVectorLayer,
    QgsPointXY,
    QgsGeometry,
    QgsProject,
    QgsExpressionContextUtils
)

يوفّر QGIS بعض الدعم لتحليل التعبيرات الشبيهة بـ SQL. ولا يُدعم إلا جزء صغير من صياغة SQL. يمكن تقييم التعبيرات إما بوصفها شروطًا منطقية (تُعيد True أو False) أو بوصفها دوالًا (تُعيد قيمة مفردة). راجع التعبيرات في دليل المستخدم للاطلاع على القائمة الكاملة للدوال المتاحة.

تُدعم ثلاثة أنواع أساسية:

• العدد --- الأعداد الصحيحة والعشرية كلاهما، مثل 123 و 3.14

• السلسلة النصية --- يجب أن تُحاط بعلامات اقتباس مفردة: 'hello world'

• مرجع العمود --- عند التقييم، يُستبدل المرجع بالقيمة الفعلية للحقل. ولا تُهرَّب الأسماء.

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

• العوامل الحسابية: +، -، *، /، ^

• الأقواس: لفرض أولوية العوامل: (1 + 1) * 3

• الموجب والسالب الأحاديان: -12، +5

• الدوال الرياضية: sqrt، sin، cos، tan، asin، acos، atan

• دوال التحويل: to_int، to_real، to_string، to_date

• الدوال الهندسية: $area، $length

• دوال معالجة الأشكال الهندسية: $x، $y، $geometry، num_geometries، centroid

والشروط التالية مدعومة:

• المقارنة: =، !=، >، >=، <، <=

• مطابقة الأنماط: LIKE (باستخدام % و _)، ~ (التعبيرات النمطية)

• الشروط المنطقية: AND، OR، NOT

• التحقق من القيمة NULL: IS NULL، IS NOT NULL

أمثلة على الشروط:

• 1 + 2 = 3

• sin(angle) > 0

• 'Hello' LIKE 'He%'

• (x > 10 AND y > 10) OR z = 0

أمثلة على التعبيرات المفردة القيمة:

• 2 ^ 10

• sqrt(val)

• $length + 1

11.1. تحليل التعبيرات

يوضح المثال التالي كيفية التحقق مما إذا كان يمكن تحليل تعبير معيّن بشكل صحيح:

exp = QgsExpression('1 + 1 = 2')
assert(not exp.hasParserError())

exp = QgsExpression('1 + 1 = ')
assert(exp.hasParserError())

assert(exp.parserErrorString() == '\nIncomplete expression. You might not have finished the full expression.')

11.2. تقييم التعبيرات

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

11.2.1. التعبيرات الأساسية

يقيّم هذا التعبير الأساسي عملية حسابية بسيطة:

exp = QgsExpression('2 * 3')
print(exp)
print(exp.evaluate())

<QgsExpression: '2 * 3'>
6

يمكن استخدام التعبير أيضًا للمقارنة، فيُقيَّم إلى 1 (True) أو 0 (False)

exp = QgsExpression('1 + 1 = 2')
exp.evaluate()
# 1

11.2.2. التعبيرات مع المعالم

لتقييم تعبير على معلم، يجب إنشاء كائن QgsExpressionContext وتمريره إلى دالة التقييم ليتمكّن التعبير من الوصول إلى قيم حقول المعلم.

يوضح المثال التالي كيفية إنشاء معلم بحقل يُسمى "Column" وكيفية إضافة هذا المعلم إلى سياق التعبير.

fields = QgsFields()
field = QgsField('Column')
fields.append(field)
feature = QgsFeature()
feature.setFields(fields)
feature.setAttribute(0, 99)

exp = QgsExpression('"Column"')
context = QgsExpressionContext()
context.setFeature(feature)
exp.evaluate(context)
# 99

فيما يلي مثال أكثر اكتمالًا على كيفية استخدام التعبيرات في سياق طبقة متجهية، لحساب قيم حقول جديدة:

from qgis.PyQt.QtCore import QMetaType

# create a vector layer
vl = QgsVectorLayer("Point", "Companies", "memory")
pr = vl.dataProvider()
pr.addAttributes([QgsField("Name", QMetaType.Type.QString),
                  QgsField("Employees",  QMetaType.Type.Int),
                  QgsField("Revenue", QMetaType.Type.Double),
                  QgsField("Rev. per employee", QMetaType.Type.Double),
                  QgsField("Sum", QMetaType.Type.Double),
                  QgsField("Fun", QMetaType.Type.Double)])
vl.updateFields()

# add data to the first three fields
my_data = [
    {'x': 0, 'y': 0, 'name': 'ABC', 'emp': 10, 'rev': 100.1},
    {'x': 1, 'y': 1, 'name': 'DEF', 'emp': 2, 'rev': 50.5},
    {'x': 5, 'y': 5, 'name': 'GHI', 'emp': 100, 'rev': 725.9}]

for rec in my_data:
    f = QgsFeature()
    pt = QgsPointXY(rec['x'], rec['y'])
    f.setGeometry(QgsGeometry.fromPointXY(pt))
    f.setAttributes([rec['name'], rec['emp'], rec['rev']])
    pr.addFeature(f)

vl.updateExtents()
QgsProject.instance().addMapLayer(vl)

# The first expression computes the revenue per employee.
# The second one computes the sum of all revenue values in the layer.
# The final third expression doesn’t really make sense but illustrates
# the fact that we can use a wide range of expression functions, such
# as area and buffer in our expressions:
expression1 = QgsExpression('"Revenue"/"Employees"')
expression2 = QgsExpression('sum("Revenue")')
expression3 = QgsExpression('area(buffer($geometry,"Employees"))')

# QgsExpressionContextUtils.globalProjectLayerScopes() is a convenience
# function that adds the global, project, and layer scopes all at once.
# Alternatively, those scopes can also be added manually. In any case,
# it is important to always go from “most generic” to “most specific”
# scope, i.e. from global to project to layer
context = QgsExpressionContext()
context.appendScopes(QgsExpressionContextUtils.globalProjectLayerScopes(vl))

with edit(vl):
    for f in vl.getFeatures():
        context.setFeature(f)
        f['Rev. per employee'] = expression1.evaluate(context)
        f['Sum'] = expression2.evaluate(context)
        f['Fun'] = expression3.evaluate(context)
        vl.updateFeature(f)

print(f['Sum'])

876.5

11.2.3. تصفية طبقة باستخدام التعبيرات

يمكن استخدام المثال التالي لتصفية طبقة وإعادة أي معلم يطابق شرطًا.

layer = QgsVectorLayer("Point?field=Test:integer",
                           "addfeat", "memory")

layer.startEditing()

for i in range(10):
    feature = QgsFeature()
    feature.setAttributes([i])
    assert(layer.addFeature(feature))
layer.commitChanges()

expression = 'Test >= 3'
request = QgsFeatureRequest().setFilterExpression(expression)

matches = 0
for f in layer.getFeatures(request):
   matches += 1

print(matches)

7

11.3. معالجة أخطاء التعبيرات

قد تحدث أخطاء متعلقة بالتعبيرات أثناء تحليل التعبير أو تقييمه:

exp = QgsExpression("1 + 1 = 2")
if exp.hasParserError():
   raise Exception(exp.parserErrorString())

value = exp.evaluate()
if exp.hasEvalError():
   raise ValueError(exp.evalErrorString())