Feature Proposal: A query cookbook is essential to help break people in

Motivation

What's in a topic

• 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

• versions
  • for each older version (most recent first, including the latest)
    • repeat of all the above fields.

Simple Tasks

Search for field values using AND and OR

%SEARCH{"form.name ~ '*PersonForm' AND (Job = 'Politician' OR Job = 'Lawyer') AND Character IN ('Honest', 'Trustworthy', 'Reliable')" type="query"}%

Test if somebody is a direct member of a group

%IF{"'%GROUPINFO{"MaintainGroup" expand="0"}%'=~'\bSvenDowideit\b'" then="yes" else="no"}%

%IF{"'SvenDowideit' IN (%GROUPINFO{"NewUIGroup" format="\\'$username\\'" separator=", " expand="0"}%)" then="yes" else="no"}%

List the titles of all form-fields that have the value 'Yes'

%QUERY{"fields[value = 'Yes'].title"}%

Search in a referenced topic

%SEARCH{"form.name ~ '*PersonForm' AND Skills/[text =~ /Taxidermy/]" type="query"}%

Search for topics in certain states

%SEARCH{"State IN ('Complete','Rejected') AND Customer IN ('IBM', 'Sony')" type="query"}%

Get the attachment count of the current topic

%QUERY{"length(attachments)"}%

Get the attachment count of shown vs hidden topics

No. Attachments %QUERY{"length('System.FamFamFamContrib'/length(attachments[NOT lc(attr)=~'h'])"}%/%QUERY{"length('System.FamFamFamContrib'/attachments[lc(attr)=~'h'])"}% (shown/hidden)

lc(attr)=~'h' could be written as the simpler attr='h', but the attr value in a META:FILEATTACHMENTrecord may contain more than one attribute, and perhaps not all (legacy) applications are known to use lower-case 'h'.

• lc() : lower-case
• =~ : 'contains' (regular expression) operator

Search for topics with both shown AND hidden attachments, display counts

%SEARCH{
  "length(attachments[lc(attr)=~'h']) > 0 AND length(attachments[NOT lc(attr)=~'h']) > 0"
  type="query"
  web="Extensions"
  limit="3"
  header="---++ [[$web.%HOMETOPIC%][$web]]
| *Topic* | *Shown* | *Hidden* |"
  format="| [[$web.$topic][$topic]] | $percntQUERY{\"length('$web.$topic'/attachments[lc(attr)=~'h'])\"}$percnt | $percntQUERY{\"length('$web.$topic'/attachments[NOT lc(attr)=~'h'])\"}$percnt |"
}%

Extensions

Display all non-hidden *.png attachments

%SEARCH{
  "attachments[name~'*.png' AND NOT lc(attr)=~'h']"
  type="query"
  web="Extensions"
  limit="3"
  header="---++ [[$web.%HOMETOPIC%][$web]]"
  format="   * [[$web.$topic][$topic]]
$percntFORMAT{
   \"$percntQUERY{'$web.$topic'/attachments[name~'*.png' AND NOT lc(attr)=~'h'].name}$percnt\"
   type=\"string\"
   format=\"      * [[%PUBURLPATH%/$web/$topic/$dollaritem][$dollaritem]]\"
}$percnt"
}%

Extensions

• ApprovalPlugin
  • ApprovalFlow.png
• BibtexPlugin
  • bibtex-cite-ex.png
  • bibtex-inline-ex.png
  • bibtex-ref-ex.png
  • bibtex-select-ex.png
• BioKbPlugin
  • _BioKb_accept2.png
  • _BioKb_not2.png
  • igp_400_raaswiki.png
  • igp_800_raaswiki.png
  • raaswiki.png

Working with Dates

Report a topic as "unloved" if it was last edited before 1st Jan 2010

Topic is %IF{"info.date < d2n('1 Jan 2010')" then="unloved" else="loved"}%

%%IF{"info.date > now - 7*24*60*60" then="N" else="NOP"}%%

%QUERY{"('Development.QueryAcrossTopicRevisions'/versions[info.date < d2n('1 Dec 2010')])[0].info.version"}%

Working with Versions

Find the version numbers of all revisions that were authored by a user

%QUERY{"versions[info.author='SamuelJohnson'].info.version"}%

Find the authors of all revisions

%QUERY{"'MyBiography'/versions[state='Authorised'].info.author"}%

%SEARCH{"versions[-1].info.author='GalileoGalilei'" type="query"}%

%QUERY{"versions[2,1,0],info.author" style="json"}%

Find all contributors for a topic

%QUERY{"versions.info.author"}%

Technical Resources

expr       ::= and_expr 'or' expr | and_expr;
and_expr   ::= not_expr 'and' and_expr | not_expr;
not_expr   ::= 'not' comma_expr | comma_expr;
comma_expr ::= cmp_expr ',' comma_expr | cmp_expr;
cmp_expr   ::= add_expr cmp_op cm_expr | add_expr;
cmp_op     ::= '<=' | '>=' | '<' | '>' | '=' | '=~' | '~' | '!=' | 'in';
add_expr   ::= mul_expr add_op add_expr | mul_expr;
mul_expr   ::= ref_expr mul_op mul_expr | ref_expr;
mul_op     ::= '*' | 'div';
ref_expr   ::= u_expr ref_op ref_expr | u_expr;
ref_op     ::= '/' | '.';
u_expr     ::= value uop u_expr | value;
uop        ::= 'lc' | 'uc' | 'd2n' | 'length' | '-' | 'int';
value      ::= name | string | number;
number     ::= unsigned floating point number, 'C' syntax
string     ::= single-quoted constant string

Discussion

• Changes to how the software behaves to the end user where features are added or removed
• Changes to the markup language
• Changes to the syntax of the macros in core and default plugins
• Changes to the API used by extensions
• Changes to the storage formats that affects how e.g. searches work

• Code refactorings where the functions remain the same
• Bug fixes
• Documentation improvements and enhancements
• Any changes to none default plugins

• Political and marketing decisions where a proposer seeks a community decision
• Changes to foswiki.org website where it is nice to get a broad consensus before changing significant setups or design

%INCLUDE{"%SYSTEMWEB%.QueryBuilder" FORM="RnT.ProposalForm" EXTRA="exclude=\"TopicType|SubjectArea|WorkflowStatus\""}%

<div class="hidden">
%STARTSECTION{name="querysearch"}%
<input type="submit" class="foswikiSubmit" id="startEdit" value="Edit and lock the selected topics" />
<input type="submit" class="foswikiButton" id="deselectAllTopics" value="Clear all" /> 
<input type="submit" class="foswikiButton" id="selectAllTopics" value="Select all" />
| *Edit* | *Proposal* | *Program* | *Technology Domain* | *Author* | *Associated Call* |
%%URLPARAM{trigger}%{"
TopicType = 'ProposalTopic' AND %URLPARAM{querystr}%
" type="query" web="%BASEWEB%" excludetopic="*Template" format="| \
<input type='checkbox' name='topiclist' value='$topic' class='topicTitles' checked /> | \
[[$topic]] %BR% $percntFORMFIELD{$quotTitle$quot topic=$quot$web.$topic$quot}$percnt | \
$percntFORMFIELD{$quotProgram$quot topic=$quot$web.$topic$quot}$percnt | \
$percntFORMFIELD{$quotTechnologyDomain$quot topic=$quot$web.$topic$quot}$percnt | \
$percntFORMFIELD{$quotAuthor$quot topic=$quot$web.$topic$quot}$percnt | \
$percntFORMFIELD{$quotAssociatedCall$quot topic=$quot$web.$topic$quot}$percnt |"
nonoise="on" order="created" reverse="on"}%
%ENDSECTION{name="querysearch"}%
</div>