.. _quickstart:

==========
Quickstart
==========

Abstract
========

This section gives a quick start in using the query module.  Por a
detailled API reference, see :ref:`api`.

Concepts
========

To use this module you need to be prepared to send multiple requests to
the server.  Each request will be processed and the response will contain
typically the result of the *next* page.

Sessions, Queries
-----------------

Paged queries are **persisten** on the server.  The query is performed on
the server, and the query spec is remembered.  To identify "your" query
uniquely, the server returns a **session ID**.

Composite Queries
-----------------

The module is capable of performing *composite queries*.  To enable this,
specify *multiple queries* in the `query_open` API call.

Simple Usage Example
====================

Let's say you want to query all *EPM Documents* which name starts with
`SQR`.  You want a maximum of 50 results per page and you want to start at
offset 0.  The requests you need to issue for that would be::

    .../services/query/1.0/query?limit=50&start=0&q={"name":"SQR*"}
    .../services/query/1.0/query/12345?page=0
    .../services/query/1.0/query/12345?page=1
    .../services/query/1.0/query/12345?page=2
    .../services/query/1.0/query/12345?page=3
    .../services/query/1.0/query/12345?page=4&close=1

The `122345` would be the **session ID** which is returned in the first
response.

.. note:: Please see also :ref:`queries`

.. note:: Note how the query specified is in **JSON** format.  Also note
   that the type `EPMDocument` is not specified -- that's the default.

.. note:: The page access order is arbitrary, and pages can be fetched
   multiple times.  No restrictions apply.

.. note:: The **last** request may contain the `close=1` URL parameter to
   close the session.  Alternatively, issue a HTTP `DELETE` to the
   `query_session_close` API.


.. _response-format::

Response Format
---------------

The responses look all similar::

    {
        "count": 50,
        "total_count": 347,
        "page": 1,
        "limit": 50,
        "pos": 50,
        "closed": False,
        "session_id": 12345,
        "url": <<URL to **this** result>>,
        "next": <<URL to the NEXT page>>,
        "previous": <<URL to the PREVIOUS page>>,
        "close": <<URL to close the session>>,
        "items": [
            { "oid": ..., ...., ....  },
            { "oid": ..., ...., ....  },
            { "oid": ..., ...., ....  },
            { "oid": ..., ...., ....  },
            { "oid": ..., ...., ....  },
        ]
    }

.. vim: set ft=rst tw=75 nocin nosi ai sw=4 ts=4 expandtab: