Expressions

Expressions are path or formulas to access and modify your document data. Based on JSON path article (http://goessner.net/articles/JsonPath/), LiteDB support a near syntax to navigate in a single document. Path always returns an IEnumerable<BsonValue> in any case.

BsonExpression are the class that parse a string expression (or path) and compile into a LINQ Expression to be fast evaluate by LiteDB. Parser uses

• Path starts with $: $.Address.Street
• Int values starts with [0-9]*: 123
• Double values starts with [0-9].[0-9]: 123.45
• Strings are represented with a single ': 'Hello World'
• Null are just null
• Bool are represented using true or false keyword.
• Functions are represented with FUNCTION_NAME(par1, par2, ...): LOWER($.Name)

Examples:

• $.Price
• $.Price + 100
• SUM($.Items[*].Price)

var expr = new BsonExpression("SUM($.Items[*].Unity * $.Items[*].Price)");
var total = expr.Execute(doc, true).First().AsDecimal;

Expressions also can be used in:

• Create an index based on an expression:
  • collection.EnsureIndex("Name", true, "LOWER($.Name)")
  • collection.EnsureIndex(x => x.Name, true, "LOWER($.Name)")
• Query documents inside a collection based on expression (full scan search)
  • Query.EQ("SUBSTRING($.Name, 0, 1)", "T")
• Update shell command
  • db.customers.update $.Name = LOWER($.Name) where _id = 1
• Create new document result in SELECT shell command
  • db.customers.select $._id, ARRAY(UPPER($.Books[*].Title)) AS titles where $.Name startswith "John"

Path

• $ - Root
• $.Name - Name field
• $.Name.First - First field from a Name subdocument
• $.Books - Returns book array value
• $.Books[0] - Return first book inside books array
• $.Books[*] - Return all books inside books array
• $.Books[*].Title Return all titles from all books
• $.Books[-1] - Return last book inside books array

Path also support expression to filter child node

• $.Books[@.Title = 'John Doe'] - Return all books where title is John Doe
• $.Books[@.Price > 100].Title - Return all titles where book price are greater than 100

Inside array, @ represent current sub document. It's possible use functions inside expressions too:

• $.Books[SUBSTRING(LOWER(@.Title), 0, 1) = 'j'] - Return all books with title starts with T or t.

Functions

Functions are always works in IEnumerable<BsonValue> as input/output parameters.

• LOWER($.Name) - Returns IEnumerable with a single element
• LOWER($.Books[*].Title) - Returns IEnumerable with all values in lower case

Operators

Operators are function to implement same math syntax. Support

• ADD(<left>, <right>): <left> + <right> (If any side are string, concat values and return as string.)
• MINUS(<left>, <right>): <left> - <right>
• MULTIPLY(<left>, <right>): <left> * <right>
• DIVIDE(<left>, <right>): <left> / <right>
• MOD(<left>, <right>): <left> % <right>
• EQ(<left>, <right>): <left> = <right>
• NEQ(<left>, <right>): <left> != <right>
• GT(<left>, <right>): <left> != <right>
• GTE(<left>, <right>): <left> >= <right>
• LT(<left>, <right>): <left> < <right>
• LTE(<left>, <right>): <left> <= <right>
• AND(<left>, <right>): <left> && <right> (Left and right must be a boolean)
• OR(<left>, <right>): <left> || <right>: Left and right must be a boolean)
• IIF(<condition>, <ifTrue>, <ifFalse>): (Condition must be a boolean value)

String

String function will work only if your <values> are string. Any other data type will skip results

Function	Description
LOWER(<values>)	Same ToLower() from String. Returns a string
UPPER(<values>)	Same ToUpper() from String. Returns a string
SUBSTRING(<values>, <index>, <length>)	Same Substring() from String. Returns a string
LPAD(<values>, <totalWidth>, <paddingChar>)	Same PadLeft() from String. Returns a string
RPAD(<values>, <totalWidth>, <paddingChar>)	Same PadRight() from String. Returns a string
FORMAT(<values>, <format>)	Same Format() from String. Works if any data type (use RawValue). Returns a string

Aggregates

Function	Description
SUM(<values>)	Sum all number values and returns a number
COUNT(<values>)	Count all values and returns a integer
MIN(<values>)	Get min value in value list
MAX(<values>)	Get max value in value list
AVG(<values>)	Calculate average in list of values

All aggregates functions works in a single document and always with an IEnumerable selector of an array: (SUM($.Items[*].Price))

DataType

Function	Description
ARRAY(<values>)	Convert all values into a single array
IS_DATE(<values>)	Return true for each value that are date
IS_NUMBER(<values>)	Return true for each value that are a number
IS_STRING(<values>)	Return true for each value that are string

All function are static methods from BsonExpression.