%SEARCH{
 "parent.name = 'Family'"
 type="query"
 nonoise="on"
 format="| [[%PUBURL%/%WEB%/$topic/$percntCALC{\"$LISTITEM($LISTSIZE($query(attachments.name)), $query(attachments.name))\"}$percnt][$topic]] |"
}%

• topictitle - title of the topic

• preferences[name='FaveColor' AND value='Tangerine'] - true if the topic has the given preference setting and value

• • arraysize

• • arraysize

• • arraysize

• Remember that in the query language, TWiki topic names are constants. You cannot write Main.JohnSmith/UserForm.FirstName because Main.JohnSmith will be interpreted as a form field name. If you want to refer to topics you must enclose the topic name in single quotes i.e. 'Main.JohnSmith'/UserForm.FirstName

• attachments[name~'*.gif'].arraysize > 3 - true if there are at least 4 .gif files attached to the topic
• (fields[name='Firstname'].value='Emma' OR fields[name='Firstname'].value='John') AND fields[name='Lastname'].value='Peel' - true for 'Emma Peel' and 'John Peel' but not 'Robert Peel' or 'Emma Thompson'

• Person/(ClothesForm[name='Headgear'].value ~ '*Bowler*' AND attachments[name~'*hat.gif' AND date < d2n('2007-01-01')]) - true if the form attached to the topic has a field called Person that has a value that is the name of a topic, and that topic contains the form ClothesForm, with a field called Headgear, and the value of that field contains the string 'Bowler', and the topic also has at least one attachment that has a name matching *hat.gif and a date before 1st Jan 2007. (Phew!)

Results from TWiki web retrieved at 16:53 (GMT)

<--/twikiTopRow-->

<--/twikiSummary-->

<--/twikiBottomRow-->

<--/patternSearchResult-->

<--/patternSearchResultCount-->

• • rev - topic revision (12) to match %REVINFO{'$rev'}% and FormattedSearch $rev
  • version - internal Store topic version (1.12 for rcs based Stores)

Gotcha

• Remember that in the query language, TWiki topic names are constants. You cannot write Main.UserTopic/UserForm.firstName because Main.UserTopic will be interpreted as a form field name. If you want to refer to topics you must enclose the topic name in quotes i.e. 'Main.UserTopic'/UserForm.firstName

• preferences[name='FaveColour' AND value='Tangerine'] - true if the topic has the given preference setting and value

Query Search

Query searches help you search the contents of forms attached to your topics, as well as the values of other meta-data attached to the topic. Using query searches you can search:

1. The fields of forms
2. Parent relationships
3. File attachment information (but not the attached files themselves)

Query searches are defined using a simple SQL-like query language. The language consists of field specifiers and constants joined with operators.

Field specifiers

All meta-data in a topic is referenced according to a to a simple plan.

• name - name of the topic
• web - name of the web the topic is within
• text - the body text of the topic
• META:FILEATTACHMENT
  • for each attachment
    • name
    • attr
    • path
    • size
    • user
    • rev
    • date
    • comment
• META:TOPICPARENT
  • name
• META:TOPICINFO
  • author
  • date
  • format
  • version
• META:TOPICMOVED
  • by
  • date
  • from
  • to
• META:FORM - the main form of the topic
  • name (known as the formname)
• META:FIELD - the fields in the form.
  • for each field in the form
    • name
    • title
    • value
• META:PREFERENCE
  • for each preference in the topic
    • name
    • value

See TWikiMetaData for details of what all these entries mean.

Most things at the top level of the plan - META:TOPICPARENT, META:TOPICINFO etc - are structures which are indexed by keys. For example, META:TOPICINFO has 4 entries, which are indexed by the keys author, date, format and version. META:FILEATTACHMENT, META:FIELD and META:PREFERENCE are all arrays, which means they can have any number of records under them. Arrays are indexed by numbers - for example, the first entry in the META:FIELD array is entry 0.

It's a bit clumsy having to type META:FILEATTACHMENT every time you want to refer to the array of attachments in a topic, so there are some predefined aliases that make it a bit less typing:

• attachments means the same as META:FILEATTACHMENT
• info means the same as META:TOPICINFO
• parent means the same as META:TOPICPARENT
• moved means the same as META:TOPICMOVED
• form means the same as META:FORM
• fields means the same as META:FIELD, You can also use the name of the form (the value of form.name e.g. PersonForm)
• preferences means the same as META:PREFERENCE

This plan is referenced using a simple syntax:

Syntax <-- -->	Means	Examples
X	refers to the field named X.	info, META:TOPICMOVED, attachments, name.
X[N]	where X is an array and N is an integer number >= 0, gets the Nth element of the array X	attachments[3]
X[query]	refers to all the elements of the array X that match query. If query is of the form name='Y' then you can use the same X.Y syntax as is used for accessing structures.	attachments[size>1024], DocumentForm[name!='Summary' AND value~'top secret'].value, DocumentForm.Summary
X.Y	refers to the entry with the key Y in the structure named X	info.date, moved.by, META:TOPICPARENT.name
X/Y	accesses Y from the topic specified by the value of X. X must evaluate to a topic name	parent.name/(form.name='ExampleForm') will evaluate to true if (1) the topic has a parent, (2) the parent topic has the main form type ExampleForm.

Note: at some point TWiki may support multiple forms in the same topic. For this reason you are recommended not to use the fields shortcut when accessing form fields, but always use the name of the form instead.

There is a shortcut for accessing form fields. If you use the name of a field (for example, LastName) in the query without a . before it, that is taken to mean "the value of the field named this". This works if and only if the field name isn't the same as of the top level entry names or their aliases described above. For example, the following expressions will all evaluate to the same thing:

• PersonForm[name='Lastname'].value
• Lastname
• PersonForm.Lastname

Constants

Operators

Field specifiers and constants are combined using operators to create queries.

The same operators are supported for %IF statements.

Putting it all together

A query matches if the query returns one or more values when it is applied to the topic. So if I have a very simple query, such as "attachments", then this will return TRUE for all topics that have one or more attachments. If I write "attachments[size>1024 AND name ~ '*.gif']" then it will return TRUE for all topics that have at least one attachment larger than 1024 bytes with a name ending in .gif.

Examples

Query examples

• attachments[name='purdey.gif'] - true if there is an attachment call purdey.gif on the topic
• (fields[name='Firstname'].value='Emma' OR fields[name=Firstname].value='John') AND fields[name='Lastname'].value='Peel' - true for 'Emma Peel' and 'John Peel' but not 'Robert Peel' or 'Emma Thompson'
• (Firstname='Emma' OR Firstname='John') AND Lastname='Peel' - shortcut form of the previous query
• HistoryForm[name='Age'].value>2 - true if the topic has a HistoryForm, and the form has a field called Age with a value > 2
• HistoryForm.Age > 2 - shortcut for the previous query
• =preferences[name='FaveColour' AND value='Tangerine'] - true if the topic has the given preference setting and value
• Person/(ClothesForm[name='Headgear'].value ~ '*Bowler*' AND attachments[name~'*hat.gif' AND date < d2n('2007-01-01')]) - true if the form attached to the topic has a field called Person that has a value that is the name of a topic, and that topic contains the form ClothesForm, with a field called Headgear, and the value of that field contains the string 'Bowler', and the topic also has at least one attachment that has a name matching *hat.gif and a date before 1st Jan 2007. (Phew!)

Search examples

%SEARCH{"parent.name = '%TOPIC%'" web="%WEB%" type="query"}%

%SEARCH{"attachments[name='grunge.gif']" type="query"}%

%SEARCH{"(lc(Shades)='green' OR lc(Shades)='yellow') AND NOT(lc(Shades) ~ 'brown')" type="query"}%

%SEARCH{"attachments[name ~ '*.png' AND date >= d2n('2007-03-26')"}%

%SEARCH{"Threat='Amber' AND text ~ '*cold virus*'"}%