3.3 參數綁定

最佳實務做法是將值與運算式字串分開,而不是直接在運算式字串中使用值。這可使用運算式字串中的參數和 bind() 函數將值綁定至參數來完成。

參數可透過下列方式指定:匿名和具名。

參數類型

語法

範例

允許用於 CRUD 操作

允許用於 SQL 字串

匿名

?

'age > ?'

具名

:

'age > :age'

下列範例示範如何在 execute() 函數之前使用 bind() 函數。對於每個具名參數,請提供一個 bind() 的引數,其中包含參數名稱及其值。參數值對傳遞至 bind() 的順序並不重要。此範例假設 test 綱要已指派給變數 db,且集合 my_collection 存在。

# Collection.find() function with hardcoded values
myColl = db.get_collection('my_collection')

myRes1 = myColl.find('age = 18').execute()

# Using the .bind() function to bind parameters
myRes2 = myColl.find('name = :param1 AND age = :param2').bind('param1','Rohit').bind('param2', 18).execute()

# Using named parameters
myColl.modify('name = :param').set('age', 55).bind('param', 'Nadya').execute()

# Binding works for all CRUD statements except add()
myRes3 = myColl.find('name like :param').bind('param', 'R%').execute()

X DevAPI 中不支援匿名預留位置。此限制可提高使用預留位置的多個方法的 CRUD 命令鏈中的程式碼清晰度。無論使用哪種 bind() 語法變體,基於參數名稱,參數和預留位置之間始終存在明確的關聯。

CRUD 命令鏈的所有方法都會為預留位置形成一個命名空間。在下列範例中,modify()set() 會鏈結在一起。這兩個方法都採用帶有預留位置的運算式。預留位置是指一個組合的命名空間。兩者都使用一個名為 :param 的預留位置。對 bind() 的單次呼叫,其中包含 :param 的一個名稱值參數,用於將預留位置值指派給鏈結方法中 :param 的兩個實例

# one bind() per parameter
myColl = db.get_collection('relatives')
juniors = myColl.find('alias = "jr"').execute().fetch_all()

for junior in juniors:
  myColl.modify('name = :param'). \
    set('parent_name',mysqlx.expr(':param')). \
    bind('param', junior.name).execute()

具名參數不允許使用以數字開頭的名稱。例如,不允許 :1one:1

準備 CRUD 陳述式

除了直接使用 bind()execute()execute() 來綁定和執行 CRUD 操作之外,也可以將 CRUD 操作物件儲存在變數中以供稍後執行。

這樣做的好處是可以將幾組變數綁定至運算式字串中定義的參數,因此在執行大量類似操作時可以獲得更好的效能。此範例假設 test 綱要已指派給變數 db,且集合 my_collection 存在。

myColl = db.get_collection('my_collection')

# Only prepare a Collection.remove() operation, but do not run it yet
myRemove = myColl.remove('name = :param1 AND age = :param2')

# Binding parameters to the prepared function and .execute()
myRemove.bind('param1', 'Leon').bind('param2', 39).execute()
myRemove.bind('param1', 'Johannes').bind('param2', 28).execute()

# Binding works for all CRUD statements but add()
myFind = myColl.find('name like :param1 AND age > :param2')

myDocs = myFind.bind('param1', 'L%').bind('param2', 20).execute()
MyOtherDocs = myFind.bind('param1', 'J%').bind('param2', 25).execute()