icat.query — Provide the Query class

class icat.query.Query(client, entity, attributes=None, aggregate=None, order=None, conditions=None, includes=None, limit=None, attribute=None)

Bases: object

Build a query to search an ICAT server.

The query uses the JPQL inspired syntax introduced with ICAT 4.3.0. It won’t work with older ICAT servers.

Parameters:
  • client (icat.client.Client) – the ICAT client.
  • entity – the type of objects to search for. This may either be an icat.entity.Entity subclass or the name of an entity type.
  • attributes – the attributes that the query shall return. See the setAttributes() method for details.
  • aggregate – the aggregate function to be applied in the SELECT clause, if any. See the setAggregate() method for details.
  • order – the sorting attributes to build the ORDER BY clause from. See the setOrder() method for details.
  • conditions – the conditions to build the WHERE clause from. See the addConditions() method for details.
  • includes – list of related objects to add to the INCLUDE clause. See the addIncludes() method for details.
  • limit – a tuple (skip, count) to be used in the LIMIT clause. See the setLimit() method for details.
  • attribute – alias for attributes, retained for compatibility. Deprecated, use attributes instead.
Raises:
  • TypeError – if entity is not a valid entity type or if both attributes and attribute are provided.
  • ValueError – if any of the keyword arguments is not valid, see the corresponding method for details.

Changed in version 0.18.0: add support for queries requesting a list of attributes rather then a single one. Consequently, the keyword argument attribute has been renamed to attributes (in the plural).

setAttributes(attributes)

Set the attributes that the query shall return.

Parameters:attributes (str or iterable of str) – the names of the attributes. This can either be a single name or a list of names. The result of the search will be a list with either a single attribute value or a list of attribute values respectively for each matching entity object. If attributes is None, the result will be the list of matching objects instead.
Raises:ValueError – if any name in attributes is not valid or if multiple attributes are provided, but the ICAT server does not support this.

Changed in version 0.18.0: also accept a list of attribute names. Renamed from setAttribute() to setAttributes() (in the plural).

setAggregate(function)

Set the aggregate function to be applied to the result.

Note that the Query class does not verify whether the aggregate function makes any sense for the selected result. E.g. the SUM of entity objects or the AVG of strings will certainly not work in an ICAT search expression, but it is not within the scope of the Query class to reject such nonsense beforehand. Furthermore, “DISTINCT” requires icat.server 4.7.0 or newer to work. Again, this is not checked by the Query class.

Parameters:function (str) – the aggregate function to be applied in the SELECT clause, if any. Valid values are “DISTINCT”, “COUNT”, “MIN”, “MAX”, “AVG”, “SUM”, or None. “:DISTINCT”, may be appended to “COUNT”, “AVG”, and “SUM” to combine the respective function with “DISTINCT”.
Raises:ValueError – if function is not valid.
setOrder(order)

Set the order to build the ORDER BY clause from.

Parameters:order (iterable or bool) – the list of the attributes used for sorting. A special value of True may be used to indicate the natural order of the entity type. Any false value means no ORDER BY clause. Rather then only an attribute name, any item in the list may also be a tuple of an attribute name and an order direction, the latter being either “ASC” or “DESC” for ascending or descending order respectively.
Raises:ValueError – if order contains invalid attributes that either do not exist or contain one to many relationships.
addConditions(conditions)

Add conditions to the constraints to build the WHERE clause from.

Parameters:conditions (dict) – the conditions to restrict the search result. This must be a mapping of attribute names to conditions on that attribute. The latter may either be a string with a single condition or a list of strings to add more then one condition on a single attribute. If the query already has a condition on a given attribute, it will be turned into a list with the new condition(s) appended.
Raises:ValueError – if any key in conditions is not valid.
addIncludes(includes)

Add related objects to build the INCLUDE clause from.

Parameters:includes (iterable of str) – list of related objects to add to the INCLUDE clause. A special value of “1” may be used to set (the equivalent of) an “INCLUDE 1” clause.
Raises:ValueError – if any item in includes is not a related object.
setLimit(limit)

Set the limits to build the LIMIT clause from.

Parameters:limit (tuple) – a tuple (skip, count).
Raises:TypeError – if limit is not a tuple of two elements.
copy()

Return an independent clone of this query.

setAttribute(attribute)

Alias for setAttributes().

Deprecated since version 0.18.0: use setAttributes() instead.