Query Builder Guide

Keyword Searches

Simply enter a word or phrase to search for all documents containing that word or phrase. Enter a series of words or phrases, separated by commas, to search for all documents containing all of them. For example, the query licence, appeal, Secretary of State will search for documents containing all three terms.

Use an asterisk to match zero or more non-space characters; use a question mark to match exactly one non-space character.

Words and phrases can be combined with the AND, OR and NOT operators, or their abbreviations: &&, || and !. For example, the query apple AND NOT banana (which can also be written apple && !banana) finds documents that contain the word "apple" and do not contain the word "banana". The AND operator has precedence over the OR operator, so a OR b AND c OR d is equivalent to a OR (b AND c) OR d. Parentheses can be used to enforce an alternate precedence, such as (a OR b) AND (c OR d). Furthermore, the comma acts as an AND operator with a lower precedence than the OR; therefore, a OR b, c OR d is equivalent to (a OR b) AND (c OR d).

Proximity Searches

To search for words or phrases appearing near one another, enter a number followed by any valid keyword search within brackets or parentheses. Parentheses match only when the terms appear in the given order; square brackets match regardless of order. For example, the query 20[licence,appeal] matches documents containing "licence" and "appeal" within twenty words of each other. The query 20(licence,appeal) matches only if the word "licence" precedes the word "appeal" by no more than twenty words.

Element Searches

To search for words or phrases appearing within a given element of a document, enter the name of the element followed by a keyword search within brackets or parentheses. For example, the query title(finance) matches documents whose title contains the word "finance", and the query subject[police,England] matches documents whose subject field contains both the word "police" and the word "England".

Some elements are structural components of a document, and may appear many times within a document. Queries targeted at such elements return all matching elements within a document, with links directly to the matching document section on www.legislation.gov.uk. For example, the query chapter(appeal, Secretary of State) matches all chapters containing those terms, with links to the matching chapters.

The following elements are supported:

title
longtitle
intro
headnote
subject
subsubject
made
laid
CIF
part
chapter
xheading
para
subpara
schedule
footnote
annotation
signature
signee
job
department
explanatory

Element searches too can be combined using the AND, OR and NOT connectors, as, for example, title(pension) AND subject[police,England].

Element Fields

Certain element searches can be further restricted by certain fields specific to them. They include:

The 'prospective' field for part(), chapter(), xheading(), para(), and schedule() searches. Permitted values are 'true' and 'false'. For example, the query para(prospective=true, Secretary of State) yields only prospective paragraphs containing the phrase 'Secretary of State'.
The 'confers-power' and 'blanket-amendment' fields for para() searches, also boolean values. The query para(confers-power=true) matches only paragraphs that confer a power.
The 'type' field for annotations, which may be equal to any any of the following values: 'F', 'C', 'E', 'I', 'P', 'M', or 'X'. For example, the query annotation(type=C) will match only C Notes (non-textual modifications), and the query annotation(type=F, repealed) will match only F Notes (textual amendments) containing the word 'repealed'.
The 'extent' field for part(), chapter(), para(), and schedule() searches. Like extent restrictions on document searchs, element searches can be restricted to certain geographical extents. For example, para(extent=E) matches only paragraphs extending to England. For a list of acceptable values, see below.

Nested Element Searches

Some element searches can be nested within one another. For example, the query part[para[licence,may] AND para[commit*,offence]] yields parts of documents that contain both a paragraph with the first two terms and a paragraph with the second two. The following nested searches are supported:

part
- number
- heading
- chapter
- xheading
- para
- subpara
- eu-title
- eu-section
chapter
- number
- heading
- xheading
- para
- subpara
- eu-section
xheading
- heading
- para
- subpara
para
- number
- heading
- subpara
subpara
- number
schedule
- number
- heading
- part
- chapter
- xheading
- para
- subpara
eu-title
- number
- heading
- chapter
- eu-section
- para
eu-section
- number
- heading
- eu-subsection
- para
eu-subsection
- number
- heading
- para

Proximity searches can be nested within element searches. For example, the query title(5[apple,pear]) matches documents whose title contains "apple" and "pear" within five words of each other.

Type Restrictions

Searches can be restricted to document type by adding "type = {type}" to the query string. For example, the query "title(pension) && type=ukpga" matches only those documents whose title contains the word "pension" and that are UK Public General Acts. The principal (non-draft) document types are: ukpga, ukla, asp, anaw, mwa, ukcm, nia, aosp, aep, aip, apgb, uksi, wsi, ssi, nisi, nisr, ukci, ukmo, uksro, mnia, apni, eur, eudn, eudr, and eut. In addition, the query "type=primary" matches all primary legislation ('ukpga', 'asp', etc.), "type=secondary" matches all secondary legislation ('uksi', 'ssi', etc.), "type=uk" matches all UK legislation ('primary' + 'secondary'), and "type=eu" matches all EU legislation ('eur', 'eudn', 'eudr' and 'eut'). A query with no type restriction is the same as "type=all", which matches all document types except drafts.

The database also contains draft Statutory Instruments. To search all drafts, enter "type=draft". In addition, the following individual draft types are available: ukdsi, sdsi and nidsr. Because drafts are excluded from the default 'all' type, to search all documents, both final and draft, one must enter "type=all OR type=draft".

Document Versions and Languages

Searches can be directed to specific versions of the documents, with the 'version' keyword. It accepts three values: 'original', which limits searches to the as enacted or as made version of document; 'current', which targets the now current version; or any date in the form YYYY-MM-DD, which matches revised documents in their state on the given date. For example, version=original will search the as enacted or as made versions, and version=2014-01-01 will match documents as they were on January 1, 2014. If no version is specified, the current version is searched.

By default, searchs are run against the English version of documents, but some documents are also available in Welsh. To search Welsh documents, include language=welsh or language=cymraeg. (Because only original versions of documents are currently available in Welsh, Welsh searches target these original versions by default.)

Range Queries

Although most elements in legislative documents contain natural language text, some elements contain numbers or dates. Searches can be restricted to documents whose values in such fields fall within a specified range. For example, to limit a search to documents within a given year, append "year = {year}" to the query. For example, title(pension) AND year=2000 searches for only those documents from 2000 with "pension" in the title. The valid operators are =, >, <, >=, <=, and !=. Range queries can be specified for the following fields:

year, an integer
number, an integer
enacted, a date in the format YYYY-MM-DD
made, a date
laid, a date
CIF, a date
modified, a date
ISBN, a string
any one of the computed values described below, each an integer (e.g., total-paragraphs > 20)

Furthermore, searches can be ordered by any of the fields above using the "orderby" instruction followed by an equals sign. For example, the query type=ukpga && orderby=year yields Public General Acts in order of the year in which they were enacted. Using a minus sign before a field name orders the results in descending order, and orders can be combined with a single ampersand. Therefore, the query type=ukpga && orderby=-year&number yields Public General Acts ordered first by year, in descending order, and then by number, in ascending order.

Extent Restrictions

Searches can be restricted by document extent, such as extent=E or extent=E+W. The possible values are 'E', 'W', 'S', or 'NI'. Two or more values can be combined with the plus '+' operator, such as 'E+W' or 'E+W+S'. Wildcards are permitted, in the form 'E+*' or 'E+W+*', and match all extents that include the given extent(s).

Counting

Clicking the "Search" button fetches a page of documents satisfying the query request. To see the total number of documents matching the query, click the "Count all" button. For example, to see the number of UK Statutory Instruments made in 2015, enter the query type=uksi && year=2015 and click "Count all".

Not only documents can be counted; one can count almost anything countable within the documents by using the "count()" instruction. For example, to see the number of paragraphs in all of the 2015 UK Statutory Instruments, enter type=uksi && year=2015 && count(total-paragraphs). To see the number of schedules and the number of footnotes, enter type=uksi && year=2015 && count(schedules,total-footnotes). If a query targets structural elements of documents, one can count the number of matching elements with "count(matching-elements)". For example, the query type=uksi && year=2015 && chapter(finance) && count(matching-elements) counts the number of paragraphs containing the word "finance" in UK Statutory Instruments from 2015.

The following counters are supported:

documents
body-paragraphs
schedule-paragraphs
schedules
total-parts
total-chapters
total-xheadings
total-paragraphs
total-subparas
total-tables
total-tablerows
total-tablecolumns
total-tablecells
total-formulas
total-images
total-blockamendments
total-inlineamendments
total-amendments
total-footnotes
total-annotations
total-f-notes
total-c-notes
total-e-notes
total-i-notes
total-p-notes
total-m-notes
total-x-notes
total-citations
total-definitions
matching-elements
matching-parts
matching-chapters
matching-xheadings
matching-paragraphs
matching-subparas
total-ENparas
total-relatedEN
total-relatedEM
total-relatedPN
total-relatedIA
days-made-laid (number of days between made date and laid date)
days-made-cif (number of days between made date and coming-into-force date)
days-laid-cif (number of days between laid date and coming-into-force date)
prospective-paragraphs
unapplied-effects
unapplied-textual-amendments
total-pit (number of "point in time" versions of the matching document)
matching-pit (number of "point in time" versions that also match the search query)
total-words
matching-words
total-unique-words
matching-unique-words

In addition, including a "count" instruction in a query and clicking "Search" yields a page of results showing the counted values for each matching document. For example, entering type=uksi && count(total-footnotes) and clicking "Search" will yield a page of results showing the number of footnotes in each statutory instrument. Clicking search with the query type=uksi && count(days-made-laid) will show the number of days between the date on which the statutory instrument was made and the date on which it was laid.

Finally, counts can be used both to restrict and to order instance searches. In other words, any of the counter names can be used with a quantitative operator to form a range query, such as type=uksi && count(schedules) && schedules>=5. And any of the counter names can be used in an "orderby" instruction, such as type=uksi && count(schedules) && orderby=-schedules, which yields the first page of statutory instruments with the greatest number of schedules.

Grouping of Count Data

Count data can be grouped by one of several fields, which contain a limited number of unique values. Use the "groupby" instruction, followed by an equals sign and one of the fields below. For example, enter the query type=uksi && year>2005 && year<=2015 && groupby=department and click "Count all" to see the number of statutory instruments in each department.

Grouping is permitted by the following fields:

subject
subsubject
department
signee
extent
year

Counts can also be grouped by both a field and the year, such as "groupby=department&year".

Finally, grouped counts can be ordered by whatever has been counted. For example, counting the query type=uksi && year>2005 && year<=2015 && groupby=department && orderby=-documents lists the departments by the number of documents in each, in descending order.