/****************************************************************************
**
** 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 object-indexes.html
\title Object Indexes

\target object index

\section1 Defining an Index on Objects

\target Index

An index is defined by creating an \l Index object in the
 database. There are two forms of \l Index, a simple one that uses a
 property or properties of the objects, and a more flexible form that
 uses a function on the object which emits the values to use in the index.

\table
\row
\li _type
\li Index

\row
\li name
\li The name of this index. If not specified and propertyName is
specified, name defaults to propertyName. If propertyFunction is
specified, then name must be specified.

\row
\li objectType
\li An optional string or array of strings, naming the object types to
be indexed. If not specified, all objects in the main object table of
a partition will be indexed.

If specified for non-view types, the index should have a name that is
distinct from its propertyName.

\row
\li propertyName
\li A string naming the property to be indexed. Mutually exclusive with
propertyFunction.

\row
\li propertyFunction
\li A string containing a JavaScript function which emits a custom
sort key for an object using jsondb.emit(). Mutually exclusive with
propertyName.

\row
\li propertyType
\li A string naming the type of the value to be indexed.

Valid types are "string" (the default) and "number".

\row
\li locale
\li A string, naming the locale type of the values to be indexed for
the collation index. \l {QLocale::} {QLocale(QString)}

\row
\li collation
\li A string, naming the collation type of the values to be indexed, used
for collation index. Please read Collation type section in
\l {Unicode Locale Data Markup Language (LDML): Key Type Definitions}.

\row
\li caseSensitive
\li A bool. This property defines whether this index is sorted using case
sensitive string comparison.

\row
\li casePreference
\li A string, naming the case preference type of the values to be indexed,
used for collation index. Allowed values are "IgnoreCase", "PreferUpperCase"
and "PreferLowerCase".

\endtable

\section1  Stability of Sort in JSON DB

The database is a set of objects with no natural ordering. Any time that we need
objects in a particular order, we use an index that orders the objects by a
particular field and comparison operator. It is unlikely that the sorting in one
index will be stable with respect to other indexes on that object.

\section1 jsondb Proxy

For indexes that use a JavaScript function, when the propertyFunction
runs it has access to a client interface to the database. This proxy
has one function: \l jsondb.emit.

\table
\row
\li \l {jsondb.emit}{jsondb.emit}(propertyValue)
\endtable

\section3 jsondb.emit

Emits a computed property value. \l jsondb.emit may be called zero or
more times in a propertyFunction. For each value emitted from the
function, an entry is created in the index which points to the object
being indexed.

See \l {Creating an Index}.

*/