TCriteria is a powerful class, which allows to build SQL queries in more abstract way than just inline code, and what is very important it has records pagging support.
In the real world - mostly in web application - we want to receive a small chunk of data, plus total records count to implement pagination. This becomes little tricky if we need to apply a filter before fetching the result.
By adding "Clone" function to the TCriteria class it allows creating a filter on the dataset and use it for returning results and total records count in single, simple logic, without creating additional functions for each dataset. This feature is reusable in any data structure and helps to write less code.
Example of usage:
var
Products: TCriteria;
begin
Products := Db.Find;
if Filter.NewOnly then
Products := Products.
Add(TExpression.Eq('New', True));
.. other filters ...
Result.RecordsCount := Products.
Clone.
Select(TProjections.ProjectionList.Add(TProjections.Count('Id'))).
UniqueValue.
Values[0];
if Filter.Skip > 0 then
Products := Products.Skip(Filter.Skip);
if Filter.Take > 0 then
Products := Products.Take(Filter.Take);
Result.Rows := Products.List;
end;