/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page queries.html
\title Queries

\section1 Basics

Central to the use of a large object store is the ability to query efficiently
for objects from within the object store. The JsonDB query language was
originally modeled on of the JSON Query language (see
\l {http://docs.persvr.org/documentation/jsonquery}). It has subsequently been
updated for faster performance and features have been added that make it more
suitable for our application.

A simple query consists of square brackets surrounding an expression
(e.g., [EXPR]). A complex query is a string of simple queries concatenated
together (e.g., [EXPR1][EXPR2][EXPR3]). Each expression filters or applies an
action.

\section1 Valid Expressions

\table
\row
\row
\li \c {[?_type="Person"]}
\li Return all objects that are Person types.
\row
\li \c {[*]}
\li All objects in the database.
\row
\li \c {[?name exists][/_type]}
\li All objects with a "name" field in the database, sorted by _type.
\row
\li \c {[?name notExists][/_type]}
\li All objects not containing a "name" field in the database, sorted by _type.

Note that this constraint precludes the use of an index on the "name"
field, because only objects containing a "name" property will appear
in the index on "name".
\row
\li \c {[?name = %thename ][/_type]}
\li All objects from the database where the "name" field is the same as the
binding for thename in the bindings object provided to find, sorted by _type.
\row
\li \c {[?name != "nancy"]}
\li All objects in the database with an "name" field not equal to "nancy".
\row
\li \c {[?name < "nancy"]}
\li All objects in the database with an "name" field less than "nancy".
\row
\li \c {[?name <= "nancy"]}
\li All objects in the database with an "name" field less than or equal to
"nancy".
\row
\li \c {[?name > "nancy"]}
\li All objects in the database with an "name" field greater than "nancy".
\row
\li \c {[?name >= "nancy"]}
\li All objects in the database with an "name" field greater than or equal to
"nancy".
\row
\li \c {[?count != 47]}
\li All objects in the database with a "count" field not equal to 47.
\row
\li \c {[?count < 47]}
\li All objects in the database with a "count" field less than 47.
\row
\li \c {[?count <= 47]}
\li All objects in the database with a "count field less than or equal to 47.
\row
\li \c {[?count > 47]}
\li All objects in the database with a "count" field greater than 47.
\row
\li \c {[?count >= 47]}
\li All objects in the database with a "count" field greater than or equal to 47.
\row
\li \c {[?email contains "foo@example.com"]}
\li All objects in the database with an "email" field containing the string
"foo@example.com".
\row
\li \c {[?sizes contains 3]}
\li All objects in the database with a "sizes" field containing the int 3.
\row
\li \c {[?sizes contains %three ]}
\li All objects in the database with a "sizes" field containing the value bound
to three in the bindings object provided to find.
\row
\li \c {[?sizes notContains 3]}
\li All objects in the database with a "sizes" field not containing the int 3.
\row
\li \c {[?size in [3, 4, 5]]}
\li All objects in the database with a "size" field that is contained in the
list [3, 4, 5].
\row
\li \c {[?size notIn [3, 4, 5]]}
\li All objects in the database with a "size" field that is not contained in the
list [3, 4, 5].
\row
\li \c {[?name =~ "/fr.*d/"]}
\li Objects with a name field matching the regular expression "fr.*d", case
sensitive.
\row
\li \c {[?name =~ "!fr/ed.*!"]}
\li Objects with a name field matching the regular expression "fr/ed.*", case
sensitive.
\row
\li \c {[?name =~ "!fred.*!i"]}
\li Objects with a name field matching the regular expression "fred.*", case
insensitive.
\row
\li \c {[?name =~ "!fred*!w"]}
\li Objects with a name field matching the wildcard expression "fred*", case
sensitive.
\row
\li \c {[?name =~ "!fred*!wi"]}
\li Objects with a name field matching the wildcard expression "fred*", case
insensitive.
\row
\li \c {[?name !=~ "!fred*!wi"]}
\li Objects with a name field not matching the wildcard expression "fred*", case
insensitive.
\row
\li \c {[?name startsWith "fred"]}
\li Objects with a name field that start with "fred".
\row
\li \c {[?_type="MESSAGE"][?HasAttachments="true"][\DateTimeSent]}
\li Message objects with attachments, sorted in reverse chronological order.
\row
\li \c {[?_type="MESSAGE"][= { subject: Subject, sent: DateTimeSent, sender: Sender.Mailbox.EmailAddress } ]}
\li List of new objects containing of subject, sent time, and sender email
address from message objects.
\row
\li \c {[?_type="MESSAGE"][count]}
\li Count the number of objects of type "MESSAGE"]
\endtable

\section1 OR-queries

Query constraints can be combined with OR-syntax, e.g.

\table
\row
\li \c {[?_type="Person" | _type="Superman"]}
\li Return all objects that are Person or Superman types.
\row
\li \c {[?_type="Person"][?name exists | age > 18]}
\li All Person objects with a "name" field or with an age field greater than 18.
\endtable

\section1 Query optimization

In general, sorting can only be done on properties for which JSON DB has an
index. Any query with a sort order given for which there is no index, will
result in an error. For a query without explicitly provided sort order, a full
object scan is performed. This should be avoided for all but the smallest data
sets.

See \l {Object Indexes}

*/