.. _module-query:

================
Module: query.py
================

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

Abstract
========

This module offers functions to **query** for business objects.

Usage Example
=============

Query for documents::

    >>> from nexiles.tools.api import get_api
    >>> from nexiles.tools.api.query import query
    >>> api = get_api(...)
    >>> query(api, type="document", name="*.doc", limit=10)

Query for different types -- see also :ref:`resources`::

    >>> query(api, type="epmdocument", name="nx*.asm", limit=100)
    >>> query(api, type="product", name="offer*")
    >>> query(api, type="part", number="1030*45")
    >>> query(api, type="organization")
    >>> query(api, type="user")

See also :ref:`tut-queries` in the :ref:`tutorial`.

Supported Queries
=================

:API VERSION: The `since version` column specifies the version of the
              **nexiles.tools** needed to perform the query.

+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| parameter   | meaning                        | since version | example                                                   | default |
+=============+================================+===============+===========================================================+=========+
| number      | query for a object number      | 1.0           | query(api, type="product", number="1234")                 | none    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| name        | query for objects named        | 1.0           | query(api, type="part", name="holder_17.prt")             | none    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| cadname     | query for object cadname       | 1.1           | query(api, type="epmdocument", cadname="HOLDER_17.PRT")   | none    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| description | query for description          | 1.0           | query(api, type="product", description="Wagon Big #1234") | none    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| state       | query for lifecycle state      | 1.1           | query(api, type="epmdocument", state="RELEASED")          | none    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| limit       | limit the query result set     | 1.0           | query(api, type="epmdocument", limit=100)                 | none    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| latest      | only return the latest objects | 1.0           | query(api, type="epmdocument", latest=False)              | True    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| workspace   | specify a workspace name       | 1.2dev        | query(api, type="epmdocument", workspace="FOO WS")        | none    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| creator     | specify the creator user name  | 1.2dev        | query(api, type="part", creator="orgadmin")               | none    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| modifier    | specify the modifier user name | 1.2dev        | query(api, type="document", modifier="fred")              | none    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+
| principal   | specify the principal name     | 1.2dev        | query(api, type="workspace", principal="fred")            | none    |
+-------------+--------------------------------+---------------+-----------------------------------------------------------+---------+


.. note:: the 'description' is not available for all business objects.

.. note:: the 'cadname' is only available for EPMDocument types.

.. note:: the 'latest', 'creator', 'modifier' filters are only allowed for iterable types.

All the above queries may be mixed.

String query notes
------------------

- All queries for strings are done **case insensitive**.
- All queries for strings may contain wild cards.


Module Documentation
====================

.. automodule:: nexiles.tools.api.query
   :members:


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