Skip to content

WebQuery API

Jump to bottom
Peter edited this page Mar 12, 2014 · 12 revisions

ResultSetConstraintBuilder can be used to build up queries from a Map of Name-Value Pairs (such as from an HTTP Query String or HTTP Form POST). This functionality is designed to allow simple querying of the underlying database whilst also providing a high-level field constraint interface that is independent of hibernate (i.e. no HQL passed in from the web).

How To Express A Query

The Map of parameters is parsed as follows:

Control Parameters

The query string is parsed for the following parameters:

  • _offset - this form parameter is used to specify the start result in the result set
  • _limit - this form parameter is used to specify the maximum result set size
  • _order - this form parameter is used to order the result set. It can be repeated to order by a number of fields.

A typical example might be:

_offset=100
_limit=100
_order=id ASC

This returns result 100 to result 200, ordered by the “id” field ascending.

Constraint Parameters

The remaining parameters are parsed as constraints. They take the form of simple field-name=value constraints. Constraints are combined logically into database constraints using a simple logic, where constraints on the same field are ORred together and constraints on different fields are ANDed together, for example:

field1=a
field1=b
field2=x
field2=y

Is converted to a database constraint of (field1 = a OR field1 = b) AND (field 2 = x OR field2 = y)

Null And Not Null

There are 2 special values for a field:

  • _null - if used, translates to an IS NULL database constraint
  • _notnull - if used, translates to an IS NOT NULL database constraint

Applying Operators

Advanced operators are supported to simplify field constraints by providing a prefix:

  • equals: prefix _f_eq_ (also by specifying no prefix, since it is the default function)
  • not equals: prefix _f_neq_
  • starts with: prefix _f_starts_ (only possible on string fields)
  • contains: prefix _f_contains_ (only possible on string fields, uses SQL LIKE so this is a very slow operation)
  • range: prefix _f_range_ with the value expressed as MIN..MAX

Data Types

The data type is picked up based on the Hibernate field type. The supported types are:

  • string
  • number - encoded in decimal
  • boolean - encoded as case insensitive true/false, yes/no, on/off (canonical representation being true/false)
  • date - encoded as an ISO date-with-optional-time, parsed by Joda Time (e.g. 2001-01-01 or 2001-01-01T09:00:00.25+0100). Special values are provided, now (for the current instant in time), today (for the first instant of today), tomorrow (for the first instant of tomorrow) and yesterday (for the first instant of yesterday)
  • uuid - encoded as text (e.g. 3F2504E0-4F89-41D3-9A0C-0305E82C3301)
  • enum - encoded as case-sensitive enum value
  • timecode - encoded as SMPTE timecode with @timebase at the end hh:mm:ss:ff@nom[:denom] (e.g. 01:00:00:04@25 for 1 hour and 24 frames at 25 FPS)
  • sample count - encoded as samples@timebase (e.g. 1920@48000 for 1920 samples at 48kHz)
Clone this wiki locally