Method SetVariable

SetVariable(String, FieldValue)

Binds a variable to a given value. The variable is identified by its name.
Declaration
public PreparedStatement SetVariable(string name, FieldValue value)
Parameters
Type Name Description
String name Name of the variable.
FieldValue value The value of the variable.
Returns
Type Description
PreparedStatement This instance.
Remarks

The values of bind variables are set as instances of FieldValue. Thus you may pass different types of values to this method via using implicit conversions provided by FieldValue (see example below). This method returns this instance PreparedStatement to enable chaining.

Note that the bind variables are not cleared after a query execution. If you wish to remove all bind variables, call ClearVariables() method.

Examples
Setting bind variables by name. 
var preparedStatement = await client.PrepareAsync(
    "SELECT * FROM orders WHERE quantity > $qty AND " +
    "city = $city AND date = $date");

// Set variables of different types.
preparedStatement
    .SetVariable("$qty", 1000)
    .SetVariable("$city", "New York")
    .SetVariable("$date", new DateTime(2021, 05, 18));

// Execute the query.
await foreach(var result in
    client.GetQueryAsyncEnumerable(preparedStatement))
{
    // .....
}
See Also

SetVariable(Int32, FieldValue)

Binds an external variable to a given value. The variable is identified by its position within the query string.
Declaration
public PreparedStatement SetVariable(int position, FieldValue value)
Parameters
Type Name Description
Int32 position The position of the variable.
FieldValue value The value of the variable.
Returns
Type Description
PreparedStatement This instance.
Remarks

This method is useful for queries where bind variables identified by "?" are used instead of named variables (but it can be used for both types of variables).

The positions start at 1. The variable that appears first in the query text has position 1, the variable that appears second has position 2 and so on.

If the provided position exceeds the number of variables in the query string (and thus does not refer to any existing variable in the query), this method will throw ArgumentOutOfRangeException if the driver has access to the variables used in the query (otherwise, such exception would be thrown when the query is executed).

Examples
Setting bind variables by position. 
var preparedStatement = await client.PrepareAsync(
    "SELECT * FROM users u where u.firstName = ? AND " +
    "u.address.city = ?");

preparedStatement
    .SetVariable(1, "John")
    .SetVariable(2, "Redwood City");

// Execute the query.
await foreach(var result in
    client.GetQueryAsyncEnumerable(preparedStatement))
{
    // .....
}
Exceptions
Type Condition
ArgumentOutOfRangeException If position is negative or zero or greater than the total number of external variables in the query.
See Also