Expressions

Deep-dive into what kind of SQL expressions can be written in Dart

Expressions are pieces of sql that return a value when the database interprets them. The Dart API from moor allows you to write most expressions in Dart and then convert them to sql. Expressions are used in all kinds of situations. For instance, where expects an expression that returns a boolean.

In most cases, you’re writing an expression that combines other expressions. Any column name is a valid expression, so for most where clauses you’ll be writing a expression that wraps a column name in some kind of comparison.

Comparisons

Every expression can be compared to a value by using equals. If you want to compare an expression to another expression, you can use equalsExpr. For numeric and datetime expressions, you can also use a variety of methods like isSmallerThan, isSmallerOrEqual and so on to compare them:

// find all animals with less than 5 legs:
(select(animals)..where((a) => a.amountOfLegs.isSmallerThanValue(5))).get();

// find all animals who's average livespan is shorter than their amount of legs (poor flies)
(select(animals)..where((a) => a.averageLivespan.isSmallerThan(a.amountOfLegs)));

Future<List<Animal>> findAnimalsByLegs(int legCount) {
  return (select(animals)..where((a) => a.legs.equals(legCount))).get();
}

Boolean algebra

You can nest boolean expressions by using the top-level and, or and not functions exposed by moor:

// find all animals that aren't mammals and have 4 legs
select(animals)..where((a) => and(not(a.isMammal), a.amountOfLegs.equals(4)))

Nullability

To check whether an expression returns null, you can use the top-level isNull function, which takes any expression and returns a boolean expression. The expression returned will resolve to true if the inner expression resolves to null and false otherwise. As you would expect, isNotNull works the other way around.

Date and Time

For columns and expressions that return a DateTime, you can use the top-level year, month, day, hour, minute and second functions to extract individual fields from that date:

select(users)..where((u) => year(u.birthDate).isLessThan(1950))

To obtain the current date or the current time as an expression, use the currentDate and currentDateAndTime constants provided by moor.

IN and NOT IN

You can check whether an expression is in a list of values by using the isIn function:

select(animals)..where((a) => isIn(a.amountOfLegs, [3, 7, 4, 2]))

Again, the isNotIn function works the other way around.

Custom expressions

If you want to inline custom sql into Dart queries, you can use a CustomExpression class. It takes a sql parameter that let’s you write custom expressions:

const inactive = CustomExpression<bool, BoolType>("julianday('now') - julianday(last_login) > 60");
select(users)..where((u) => inactive);

Note: It’s easy to write invalid queries by using CustomExpressions too much. If you feel like you need to use them because a feature you use is not available in moor, consider creating an issue to let us know. If you just prefer sql, you could also take a look at compiled sql which is typesafe to use.

Last modified September 14, 2019: Add documentation on Dart expressions (1d7b4d0)