Query Search

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

Field specifiers

• name - name of the topic
• web - name of the web the topic is within
• text - the body text of the topic (without embedded meta-data)
• META:FILEATTACHMENT
  • for each attachment
    • name
    • attr
    • path
    • size
    • user
    • rev
    • date
    • comment
• META:TOPICPARENT
  • name
• META:TOPICINFO
  • author
  • date
  • format
  • version - topic version (integer)
• META:TOPICMOVED
  • by
  • date
  • from
  • to
• META:FORM - the main form of the topic
  • name
• META:FIELD - the fields in the form.
  • for each field in the form
    • name - name of the field
    • title - title of the field
    • value - what is stored in the field
    • form - name of the form the field is in (currently always equal to META:FORM.name)
    • attributes - string stored in the attributes, like H for hidden
• META:PREFERENCE
  • for each preference in the topic
    • name
    • value

• versions
  • for each older version (most recent first)
    • repeat of all the above fields (except versions).
    • See Working with versions for more details.

• attachments means the same as META:FILEATTACHMENT
• info means the same as META:TOPICINFO
• parent means the same as META:TOPICPARENT. Note: parent is itself a map; use parent.name to access the name of the parent topic
• moved means the same as META:TOPICMOVED
• form means the same as META:FORM, so to test if a topic has a form named 'UserForm' you test for "form.name ~ '*.UserForm'"
• 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
• extensions may add additional aliases when they register new meta-data types

• Lastname
• PersonForm.Lastname
• Lastname.value

Basic Types

• String - string constants are delimited by single quotes. Any values taked from topics (such as field values) are by default interpreted as strings. The empty string evaluates to boolean 'false', as does the string "0". All others evaluate to 'true'.
• Number - numerical constants can be expressed using standard floating point number notation. Strings can also be used wherever a number is expected, in which case the string will be parsed as a number. Numerical 0 evaluates to boolean 'false', all others to 'true'.
• Undefined - an undefined value is a placeholder for a value.
• Array - ordered collections of values
• Structure - also known as a "hash", a structure is an associative array that maps names to values. Topics are structures, with fields as described above.

Boolean values

Constants

String Constants

Numerical constants

Named constants

Operators

The same operators are supported by the %IF and %QUERY macros.

If you want to know if a field is undefined (has never been given a value) then you can compare it with undefined.

In the operators ( = != ~ =~ < > <= >= NOT AND OR) an undefined operand is treated the same as numerical 0. For lc uc d2n an undefined operand will give an undefined result. For length and undefined operand will give a result of 0.

Putting it all together

Case sensitivity

• operator names (and and AND are the same)
• constants (now and NOW are the same)

Working with arrays

versions[0,-1]

versions[-1,info.author='RoaldDahl']

Working with versions

versions[info.author='RoaldDahl']

versions[info.author='RoaldDahl'].Published

Gotchas

• Remember that in the query language, 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
• Query operations are performed in the context of =%WEB% and =%TOPIC%. This can cause confusion when they are used in an %INCLUDEed topic, where you might expect them to operate in the context of the including topic, rather than the included topic.

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 settings 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!)
• length(fields[NOT lc(attributes)=~'h']) - the number of fields that are not hidden
• lc(name)=~'.*ann.*' - Would match Anne, Maryann, MaryAnn, AnnMarie...

Search examples

%SEARCH{"parent.name='%TOPIC%' OR parent.name='%WEB%.%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')]" type="query"}%

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

%SEARCH{"info.date >= %CALC{"$TIMEADD($TIME(), -7, day)"}%" type="query"}%

%SEARCH{"lc(name)=~lc('.*%URLPARAM{"q"}%.*')" type="query"}%