Boolean expression rules

This chapter introduces how to write query condition expressions.

Overview

A predicate expression outputs a boolean value. Milvus filters scalars by using predicates. When evaluating a predicate expression, it will return TRUE or FALSE. Please refer to the Python SDK API reference for guidance on using predicate expressions.

Operators

Logical Operators

Logical operators compare two expressions.

Symbol Operation Example Description
'and' && AND expr1 && expr2 Returns True when both expr1 and expr2 are true.
'or' || OR expr1 || expr2 Returns True when either expr1 or expr2 is true.

Binary Arithmetic Operators

Binary arithmetic operators take two operands and perform basic arithmetic operations, returning the corresponding result.

Symbol Operation Example Description
+ Addition a + b Adds the two operands together.
- Subtraction a - b Subtracts the second operand from the first.
* Multiplication a * b Multiplies the two operands.
/ Division a / b Divides the first operand by the second.
** Exponentiation a ** b Raises the first operand to the power of the second.
% Modulo a % b Divides the first operand by the second and returns the remainder.

Relational Operators

Relational operators use symbols to check for equality, inequality, or relative order between two expressions.

Symbol Operation Example Description
< Less than a < b Returns True if a is less than b.
> Greater than a > b Returns True if a is greater than b.
== Equal to a == b Returns True if a is equal to b.
!= Not equal to a != b Returns True if a is not equal to b.
<= Less than or equal to a <= b Returns True if a is less than or equal to b.
>= Greater than or equal to a >= b Returns True if a is greater than or equal to b.

Operator Precedence and Associativity

The following table lists the precedence and associativity of operators. Operators are listed in order of precedence from top to bottom.

Precedence Operator Description Associativity
1 + - Unary arithmetic operators Left to right
2 not Unary logical operator Right to left
3 ** Binary arithmetic operator Left to right
4 * / % Binary arithmetic operator Left to right
5 + - Binary arithmetic operator Left to right
6 < <= > >= Comparison operators Left to right
7 == != Comparison operators Left to right
8 like LIKE Matching operator Left to right
9 json_contains JSON_CONTAINS JsonArray operator Left to right
10 json_contains_all JSON_CONTAINS_ALL JsonArray operator Left to right
11 json_contains_any JSON_CONTAINS_ANY JsonArray operator Left to right
12 && and Binary logical operator Left to right
13 || or Binary logical operator Left to right

Expressions are typically evaluated from left to right. Complex expressions are evaluated one at a time. The order of evaluation of expressions is determined by the precedence of the operators used.

If an expression contains two or more operators with the same precedence, the leftmost operator is evaluated first.

For example, 10 / 2 * 5 will be evaluated as (10 / 2) and the result will be multiplied by 5.

When it is necessary to prioritize lower-precedence operations, they should be enclosed in parentheses.

For example, 30 / 2 + 8. It is usually calculated as 30 divided by 2, and then 8 is added to the result. If you want to divide by 2 + 8, it should be written as 30 / (2 + 8).

Parentheses can be nested within an expression. The innermost parentheses are evaluated first.

Example conditions

Here are some examples of all the available boolean expressions in Milvus (int64 represents a scalar field containing INT64 type data, float represents a scalar field containing floating-point type data, and VARCHAR represents a scalar field containing VARCHAR type data):

  1. Comparison expression
"int64 > 0"

"0 < int64 < 400"

"500 < int64"

VARCHAR > "str1"
  1. Logical operations and parentheses
"(int64 > 0 && int64 < 400) or (int64 > 500 && int64 < 1000)"
  1. in expression

Milvus only supports the deletion of entities with explicitly defined primary keys, which can only be achieved through the term expression in.

"int64 not in [1, 2, 3]"

VARCHAR not in ["str1", "str2"]
  1. TermExpr, BinaryLogicalOp, and CmpOp (on different fields)
"int64 in [1, 2, 3] and float != 2"
  1. BinaryLogicalOp and CmpOp
"int64 == 0 || int64 == 1 || int64 == 2"
  1. CmpOp and UnaryArithOp or BinaryArithOp
"200+300 < int64"
  1. MatchOp (prefix matching)
VARCHAR like "prefix%"
  1. JsonArrayOp

  • JSON_CONTAINS(identifier, JsonExpr)

    If the JSON expression in the JSON_CONTAINS (second parameter) statement is a list, the identifier (first parameter) should be a list of lists. Otherwise, the statement always evaluates to False.

json_contains(x, 1) # ==> true
json_contains(x, "a") # ==> false

json_contains(x, [1,2,3]) # ==> true
json_contains(x, [3,2,1]) # ==> false

  • JSON_CONTAINS_ALL(identifier, JsonExpr)

    The JSON expression in the JSON_CONTAINS_ALL statement should always be a list.

json_contains_all(x, [1,2,8]) # ==> true
json_contains_all(x, [4,5,6]) # ==> false (6 does not exist)

  • JSON_CONTAINS_ANY(identifier, JsonExpr)

    The JSON expression in the JSON_CONTAINS_ANY statement should always be a list. Otherwise, its behavior is the same as JSON_CONTAINS.

json_contains_any(x, [1,2,8]) # ==> true
json_contains_any(x, [4,5,6]) # ==> true
json_contains_any(x, [6,9]) # ==> false