icat.query — Provide the Query class

class icat.query.Query(client, entity, attributes=None, aggregate=None, order=None, conditions=None, includes=None, limit=None, join_specs=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.

  • join_specs – a mapping to override the join specification for selected related objects. See the setJoinSpecs() method for details.

Raises:

  • TypeError – if entity is not a valid entity type or if any of the keyword arguments have an invalid type, see the corresponding method for details.

  • 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 than a single one. Consequently, the keyword argument attribute has been renamed to attributes (in the plural).

Changed in version 0.19.0: add the join_specs argument.

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.

setJoinSpecs(join_specs)

Override the join specifications.

Parameters:

join_specs (dict) – a mapping of related object names to join specifications. Allowed values are “JOIN”, “INNER JOIN”, “LEFT JOIN”, and “LEFT OUTER JOIN”. Any entry in this mapping overrides how this particular related object is to be joined. The default for any relation not included in the mapping is “JOIN”. A special value of None for join_specs is equivalent to the empty mapping.

Raises:

  • TypeError – if join_specs is not a mapping.

  • ValueError – if any key in join_specs is not a name of a related object or if any value is not in the allowed set.

New in version 0.19.0.

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. The attribute name can be wrapped with a JPQL function (such as “LENGTH(title)”). Rather than 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 any attribute in order is not valid or if any attribute appears more than once in the resulting ORDER BY clause.

Changed in version 0.19.0: allow one to many relationships in order. Emit a QueryOneToManyOrderWarning rather than raising a ValueError in this case.

Changed in version 0.20.0: allow a JPQL function in the attribute.

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. The attribute name (the key of the condition) can be wrapped with a JPQL function (such as “UPPER(title)”). If the query already has a condition on a given attribute, the previous condition(s) will be retained and the new condition(s) added to that.

Raises:

ValueError – if any key in conditions is not valid.

Changed in version 0.20.0: allow a JPQL function in the attribute.

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.

property select_clause

The SELECT clause of the query.

New in version 0.21.0.

property join_clause

The JOIN clause of the query.

New in version 0.21.0.

property where_clause

The WHERE clause of the query.

New in version 0.21.0.

property order_clause

The ORDER BY clause of the query.

New in version 0.21.0.

property include_clause

The INCLUDE clause of the query.

New in version 0.21.0.

property limit_clause

The LIMIT clause of the query.

New in version 0.21.0.

copy()

Return an independent clone of this query.