Version: 1.x

Operators

A variety of operators in SurrealQL allow for complex manipulation of data, and advanced logic.

Operator	Description
`&&` or `AND`	Checks whether both of two values are truthy
`\|\|` or `OR`	Checks whether either of two values is truthy
`!`	Reverses the truthiness of a boolean value
`??`	Check whether either of two values are truthy and not NULL
`?:`	Check whether either of two values are truthy
`=` or `IS`	Check whether two values are equal
`!=` or `IS NOT`	Check whether two values are not equal
`==`	Check whether two values are exactly equal
`?=`	Check whether any value in a set is equal to a value
`*=`	Check whether all values in a set are equal to a value
`~`	Compare two values for equality using fuzzy matching
`!~`	Compare two values for inequality using fuzzy matching
`?~`	Check whether any value in a set is equal to a value using fuzzy matching
`*~`	Check whether all values in a set are equal to a value using fuzzy matching
`<`	Check whether a value is less than another value
`<=`	Check whether a value is less than or equal to another value
`>`	Check whether a value is greater than another value
`>=`	Check whether a value is greater than or equal to another value
`+`	Add two values together
`-`	Subtract a value from another value
`*` or `×`	Multiply two values together
`/` or `÷`	Divide a value by another value
`%`	Returns the remainder of a division operation
`**`	Raises a base value by another value
`IN`	Checks whether a value is contained within another value
`NOT IN`	Checks whether a value is not contained within another value
`CONTAINS` or `∋`	Checks whether a value contains another value
`CONTAINSNOT` or `∌`	Checks whether a value does not contain another value
`CONTAINSALL` or `⊇`	Checks whether a value contains all other values
`CONTAINSANY` or `⊃`	Checks whether a value contains any other value
`CONTAINSNONE` or `⊅`	Checks whether a value contains none of the following values
`INSIDE` or `∈`	Checks whether a value is contained within another value
`NOTINSIDE` or `NOT IN` or `∉`	Checks whether a value is not contained within another value
`ALLINSIDE` or `⊆`	Checks whether all values are contained within other values
`ANYINSIDE` or `⊂`	Checks whether any value is contained within other values
`NONEINSIDE` or `⊄`	Checks whether no value is contained within other values
`OUTSIDE`	Checks whether a geometry type is outside of another geometry type
`INTERSECTS`	Checks whether a geometry type intersects another geometry type
`@@` or `@[ref]@`	Checks whether the terms are found in a full-text indexed field
`KNN` Since 1.3.0	Performs a K-Nearest Neighbors (KNN) search to find a specified number of records closest to a given data point, optionally using a defined distance metric. Supports customizing the number of results and choice of distance calculation method.

`&&` or `AND`

Checks whether both of two values are truthy.

RETURN 10 AND 20 AND 30;

30

`||` or `OR`

Checks whether either of two values are truthy.

RETURN 0 OR false OR 10;

10

`!`

Reverses the truthiness of a boolean value.

SELECT * FROM !(TRUE OR FALSE)

FALSE

`??`

Check whether either of two values are truthy and not NULL.

RETURN NULL ?? 0 ?? false ?? 10;

0

`?:`

Check whether either of two values are truthy.

RETURN NULL ?: 0 ?: false ?: 10;

10

`=` or `IS`

Check whether two values are equal.

RETURN true = "true";

false

RETURN 10 = "10";

false

RETURN 10 = 10.00;

true

RETURN 10 = "10.3";

false

RETURN [1, 2, 3] = [1, 2, 3];

true

RETURN [1, 2, 3] = [1, 2, 3, 4];

false

RETURN { this: "object" } = { this: "object" };

true

RETURN { this: "object" } = { another: "object" };

false

`!=` or `IS NOT`

Check whether two values are equal.

RETURN 10 != "15";

true

RETURN 10 != "test";

true

RETURN [1, 2, 3] != [3, 4, 5];

true

`==`

Check whether two values are exact. This operator also checks that each value has the same type.

RETURN 10 == 10;

true

RETURN 10 == "10";

false

RETURN true == "true";

false

`?=`

Check whether any value in an array equals another value.

RETURN [10, 15, 20] ?= 10;

true

`*=`

Check whether all values in an array equals another value.

RETURN [10, 10, 10] *= 10;

true

`~`

Compare two values for equality using fuzzy matching.

RETURN "test text" ~ "Test";

true

RETURN "true" ~ true;

false

RETURN ["test", "thing"] ~ "test";

false

`!~`

Compare two values for inequality using fuzzy matching.

RETURN "other text" !~ "test";

true

RETURN "test text" !~ "Test";

false

`?~`

Check whether any value in a set is equal to a value using fuzzy matching.

RETURN ["true", "test", "text"] ?~ true;

false

RETURN [1, 2, 3] ?~ "2";

false

`*~`

Check whether all values in a set are equal to a value using fuzzy matching.

RETURN ["TRUE", true, "true", "TrUe"] *~ true;

false

RETURN ["TEST", "test", "text"] *~ "test";

false

`<`

Check whether a value is less than another value.

RETURN 10 < 15;

true

`<=`

Check whether a value is less than or equal to another value.

RETURN 10 <= 15;

true

`>`

Check whether a value is less than another value.

RETURN 15 > 10;

true

`>=`

Check whether a value is less than or equal to another value.

RETURN 15 >= 10;

true

`+`

Add two values together.

RETURN 10 + 10;

20

RETURN "test" + " " + "this";

"test this"

RETURN 13h + 30m;

"13h30m"

`-`

Subtracts a value from another value.

RETURN 20 - 10;

10

RETURN 2m - 1m;

"1m"

`*` or `×`

Multiplies a value by another value.

RETURN 20 * 2;

40

`/` or `÷`

Divides a value with another value.

RETURN 20 / 2;

10

`%`

Returns the remainder of a division operation.

RETURN 5 % 4;

1

`**`

Raises a base value by another value.

RETURN 20 ** 3;

8000

`CONTAINS` or `∋`

Check whether a value contains another value.

RETURN [10, 20, 30] CONTAINS 10;

true

RETURN "this is some text" CONTAINS "text";

true

RETURN {
	type: "Polygon",
	coordinates: [[
		[-0.38314819, 51.37692386], [0.1785278, 51.37692386],
		[0.1785278, 51.61460570], [-0.38314819, 51.61460570],
		[-0.38314819, 51.37692386]
	]]
} CONTAINS (-0.118092, 51.509865);

true

`CONTAINSNOT` or `∌`

Check whether a value does not contain another value.

RETURN [10, 20, 30] CONTAINSNOT 15;

true

RETURN "this is some text" CONTAINSNOT "other";

true

RETURN {
	type: "Polygon",
	coordinates: [[
		[-0.38314819, 51.37692386], [0.1785278, 51.37692386],
		[0.1785278, 51.61460570], [-0.38314819, 51.61460570],
		[-0.38314819, 51.37692386]
	]]
} CONTAINSNOT (-0.518092, 53.509865);

true

`CONTAINSALL` or `⊇`

Check whether a value contains all of multiple values.

RETURN [10, 20, 30] CONTAINSALL [10, 20, 10];

true

`CONTAINSANY` or `⊃`

Check whether a value contains any of multiple values.

RETURN [10, 20, 30] CONTAINSANY [10, 15, 25];

true

`INSIDE` or `∈` or `IN`

Check whether a value is contained within another value.

RETURN 10 INSIDE [10, 20, 30];

true

RETURN "text" INSIDE "this is some text";

true

RETURN (-0.118092, 51.509865) INSIDE {
	type: "Polygon",
	coordinates: [[
		[-0.38314819, 51.37692386], [0.1785278, 51.37692386],
		[0.1785278, 51.61460570], [-0.38314819, 51.61460570],
		[-0.38314819, 51.37692386]
	]]
};

true

`NOTINSIDE` or `∉` or `NOT IN`

Check whether a value is not contained within another value.

RETURN 15 NOTINSIDE [10, 20, 30];

true

RETURN "other" NOTINSIDE "this is some text";

true

RETURN (-0.518092, 53.509865) NOTINSIDE {
	type: "Polygon",
	coordinates: [[
		[-0.38314819, 51.37692386], [0.1785278, 51.37692386],
		[0.1785278, 51.61460570], [-0.38314819, 51.61460570],
		[-0.38314819, 51.37692386]
	]]
};

true

`ALLINSIDE` or `⊆`

Check whether all of multiple values are contained within another value.

RETURN [10, 20, 10] ALLINSIDE [10, 20, 30];

true

`ANYINSIDE` or `⊂`

Check whether any of multiple values are contained within another value.

RETURN [10, 15, 25] ANYINSIDE [10, 20, 30];

true

`NONEINSIDE` or `⊄`

Check whether none of multiple values are contained within another value.

RETURN [15, 25, 35] NONEINSIDE [10, 20, 30];

true

`OUTSIDE`

Check whether a geometry value is outside another geometry value.

RETURN (-0.518092, 53.509865) OUTSIDE {
	type: "Polygon",
	coordinates: [[
		[-0.38314819, 51.37692386], [0.1785278, 51.37692386],
		[0.1785278, 51.61460570], [-0.38314819, 51.61460570],
		[-0.38314819, 51.37692386]
	]]
};

true

`INTERSECTS`

Check whether a geometry value intersects another geometry value.

RETURN {
	type: "Polygon",
	coordinates: [[
		[-0.38314819, 51.37692386], [0.1785278, 51.37692386],
		[0.1785278, 51.61460570], [-0.38314819, 51.61460570],
		[-0.38314819, 51.37692386]
	]]
} INTERSECTS {
	type: "Polygon",
	coordinates: [[
		[-0.11123657, 51.53160074], [-0.16925811, 51.51921169],
		[-0.11466979, 51.48223813], [-0.07381439, 51.51322956],
		[-0.11123657, 51.53160074]
	]]
};

true

`MATCHES`

Checks whether the terms are found in a full-text indexed field.

SELECT * FROM book WHERE title @@ 'rust web';


[
	{
		id: book:1,
		title: 'Rust Web Programming'
	}
]

Using the matches operator with a reference checks whether the terms are found, highlights the searched terms, and computes the full-text score.

SELECT id,
		search::highlight('<b>', '</b>', 1) AS title,
		search::score(1) AS score
FROM book
WHERE title @1@ 'rust web'
ORDER BY score DESC;

[
	{
		id: book:1,
		score: 0.9227996468544006f,
		title: '<b>Rust</b> <b>Web</b> Programming'
	}
]

`KNN`

K-Nearest Neighbors (KNN) is a fundamental algorithm used for classifying or regressing based on the closest data points in the feature space, with its performance and scalability critical in applications involving large datasets.

In practice, the efficiency and scalability of the KNN algorithm are crucial, especially when dealing with large datasets. Different implementations of KNN are tailored to optimize these aspects without compromising the accuracy of the results.

SurrealDB supports different K-Nearest Neighbors methods to perform KNN searches, each with unique requirements for syntax. Below are the details for each method, including how to format your query with examples:

Brute Force Method Since 1.3.0

Best for smaller datasets or when the highest accuracy is required.

SurrealQL Syntax
<|K,DISTANCE_METRIC|>

K: The number of nearest neighbors to retrieve.
DISTANCE_METRIC: The metric used to calculate distances, such as EUCLIDEAN or MANHATTAN.

CREATE pts:3 SET point = [8,9,10,11];
SELECT id FROM pts WHERE point <|2,EUCLIDEAN|> [2,3,4,5];

MTREE Index Method Since 1.3.0

Ideal for larger datasets where performance is crucial, and a consistent distance metric can be predefined.

SurrealQL Syntax
<|K|>

K: The number of nearest neighbors. The distance metric is predefined in the index, simplifying the syntax.

CREATE pts:3 SET point = [8,9,10,11];
DEFINE INDEX mt_pts ON pts FIELDS point MTREE DIMENSION 4 DIST EUCLIDEAN;
SELECT id FROM pts WHERE point <|2|> [2,3,4,5];

HNSW Method Since 1.5.0

Recommended for very large datasets where speed is essential and some loss of accuracy is acceptable.

SurrealQL Syntax
<|K,EF|>

K: The number of nearest neighbors.
EF: The size of the dynamic candidate list during the search, affecting the search's accuracy and speed.

CREATE pts:3 SET point = [8,9,10,11];
DEFINE INDEX mt_pts ON pts FIELDS point HNSW DIMENSION 4 DIST EUCLIDEAN EFC 150 M 12;
SELECT id FROM pts WHERE point <|10,40|> [2,3,4,5];

Operators

&& or AND​

|| or OR​

!​

??​

?:​

= or IS​

!= or IS NOT​

==​

?=​

*=​

~​

!~​

?~​

*~​

<​

<=​

>​

>=​

+​

-​

* or ×​

/ or ÷​

%​

**​

CONTAINS or ∋​

CONTAINSNOT or ∌​

CONTAINSALL or ⊇​

CONTAINSANY or ⊃​

INSIDE or ∈ or IN​

NOTINSIDE or ∉ or NOT IN​

ALLINSIDE or ⊆​

ANYINSIDE or ⊂​

NONEINSIDE or ⊄​

OUTSIDE​

INTERSECTS​

MATCHES​

KNN​

Brute Force Method Since 1.3.0​

MTREE Index Method Since 1.3.0​

HNSW Method Since 1.5.0​