.. _tut-queries:

============================
Tutorial: Performing Queries
============================

:Author: Stefan Eletzhofer
:Date:   2012-05-22

Abstract
========

In this tutorial chapter you'll learn how to use *nexiles.tools.api* to
perform queries programmatically.

Queries
=======

So lets get started and perform a query.  You'll use the
:py:mod:`nexiles.tools.api.query.query` function::

    >>> from nexiles.tools.api.query import query
    >>> result = query(api, type="document", limit=10)

This will perform a query for the *resource* `documents` -- which stands
for the Windchill PDMlink business object `WTDocument` (see
:ref:`resources`) -- and limits the query to 10 results.

Let's inspect the results::

    >>> len(items)
    5
    >>> results[0].keys()
    {u'name': u'Important Document.doc', u'oid': u'OR:wt.doc.WTDocument:4711', u'url': u'http://...'}

What's this?

- The query returns a **sequence of mappings** as a result
- The mappings contain the *name* and the *oid* of the result item, and a
  *url*.
- The *url* points to the *specific* REST resource for that result.  This
  means, that the above query did **not** return the full objects, but
  *pointers* to them.

.. note:: Obviously, you'll get different results -- but you get the idea.

Workspace Queries
-----------------

You can query for *workspaces*, too.  Lets find **all** workspaces::

    >>> results = query(api, type="workspace")

The usual *name* filter also works.  Let's filter by name::

    >>> results = query(api, type="workspace", name="foo")

Queries for users, creators or modifiers
----------------------------------------

Getting all *users* is easy::

    >>> result = query(api, type="user")

Let's query all **EPMDocuments** modified by `orgadmin`::

    >>> result = query(api, type="epmdocument", modifier="orgadmin")

Let's query all **EPMDocuments** modified **and** created by `orgadmin`::

    >>> result = query(api, type="epmdocument", modifier="orgadmin",
    ... creator="orgadmin")

Complex queries
---------------

What about a more complex query?  I hear you -- so let's start with simple
wildcards::

    >>> results = query(api, name="Important*.doc")
    >>> results = query(api, number="10*", name="*.doc")

Let's query for all *EPMDocuments* which are in the workspace `foo`::

    >>> results = query(api, type="epmdocument", workspace="foo")

or all the `din` parts which are in any workspace which name starts with
`ws_`::

    >>> results = query(api, type="part", name="din*.prt", workspace="ws_*")

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