Query Search

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:

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)

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 query language. The language consists of field specifiers and constants joined with operators.

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

Field specifiers

Field specifiers

You use field specifiers to say what value from the topic you are interested in.

You use field specifiers to say what value from the topic you are interested in.

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

All meta-data in a topic is referenced according 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 (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)
• META:PREFERENCE
  • for each preference in the topic
    • name
    • value

• 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)
• META:PREFERENCE
  • for each preference in the topic
    • name
    • value

See MetaData for details of what all these entries mean.

See MetaData 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.

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:

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. 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

• 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

Fields in this plan are referenced using a simple field specifier syntax:

Fields in this plan are referenced using a simple field specifier syntax:

Note: at some point Foswiki 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.

Note: at some point Foswiki 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:

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

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

If X would conflict with the name of an entry or alias (e.g. it's moved or maybe parent), you can prepend the name of the form followed by a dot, as shown in the last example.

If X would conflict with the name of an entry or alias (e.g. it's moved or maybe parent), you can prepend the name of the form followed by a dot, as shown in the last example.

Constants

Constants

You use constants for the values that you compare with fields. Constants are either strings, or numbers.

You use constants for the values that you compare with fields. Constants are either strings, or numbers.

String Constants

String Constants

String constants are always delimited by single-quotes. You can use backslash \ to include the following special characters:

String constants are always delimited by single-quotes. You can use backslash \ to include the following special characters:

All other occurrences of backslashes are carried through into the string, so \d means \d (unless the string is used as a regular expression, in which case it means any digit).

All other occurrences of backslashes are carried through into the string, so \d means \d (unless the string is used as a regular expression, in which case it means any digit).

Numerical constants

Numerical constants

Numbers can be any signed or unsigned integer or floating point number using standard scientific notation e.g. -1.2e-3 represents -0.0012

Numbers can be any signed or unsigned integer or floating point number using standard scientific notation e.g. -1.2e-3 represents -0.0012

Operators

Operators

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

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

The same operators are supported by the %IF and %QUERY macros. You can get the current time for date comparisons using SpreadSheetPlugin, thus: %CALC{"$TIME()"}% If you want to know if a field is undefined (has never been given a value) then you can compare it with undefined (this requires that no field called undefined exists in the form). 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.

The same operators are supported by the %IF and %QUERY macros. You can get the current time for date comparisons using SpreadSheetPlugin, thus: %CALC{"$TIME()"}% If you want to know if a field is undefined (has never been given a value) then you can compare it with undefined (this requires that no field called undefined exists in the form). 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.

Text and Meta Text

Text and Meta Text

There are two fields that contain the topic text, text and metatext. text just contains the raw text of the topic, as you would see if you viewed the topic raw. metatext contains the text of the topic with MetaData embedded. This can be useful when you want to generate output based on processing meta-data.

There are two fields that contain the topic text, text and metatext. text just contains the raw text of the topic, as you would see if you viewed the topic raw. metatext contains the text of the topic with MetaData embedded. This can be useful when you want to generate output based on processing meta-data.

Putting it all together

Putting it all together

When a query is applied to a topic, the goal is to reduce to a TRUE or FALSE value that indicates whether the topic matches that query or not. If the query returns TRUE, then the topic is included in the search results.

When a query is applied to a topic, the goal is to reduce to a TRUE or FALSE value that indicates whether the topic matches that query or not. If the query returns TRUE, then the topic is included in the search results.

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.

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.

Gotcha

Gotcha

• 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

• 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

Examples

Examples

Query 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!)

• 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!)

Search examples

Search examples

Find all topics that are children of this topic in the current web

Find all topics that are children of this topic in the current web

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

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

Find all topics that have an attachment called 'grunge.gif'

Find all topics that have an attachment called 'grunge.gif'

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

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

Find all topics that have form ColourForm where the form field 'Shades' is 'green' or 'yellow' but not 'brown'

Find all topics that have form ColourForm where the form field 'Shades' is 'green' or 'yellow' but not 'brown'

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

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

Find all topics that have PNG attachments that have been added since 26th March 2007

Find all topics that have PNG attachments that have been added since 26th March 2007

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

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

Find all topics that have a field 'Threat' set to 'Amber' and 'cold virus' somewhere in the topic text.

Find all topics that have a field 'Threat' set to 'Amber' and 'cold virus' somewhere in the topic text.

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

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

Find all topics newer than one week old

Find all topics newer than one week old

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

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

Related Topics: SearchHelp, VarSEARCH, FormattedSearch, Foswiki:Projekte/Projekte/System/QuerySearchPatternCookbook

Related Topics: SearchHelp, VarSEARCH, FormattedSearch, Foswiki:System/QuerySearchPatternCookbook