/usr/share/doc/refdb/refdb-manual/ch14s04.html is in refdb-doc 1.0.2-3ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The query language</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="home" href="index.html" title="RefDB handbook" /><link rel="up" href="ch14.html" title="Chapter 14. Tools for reference and notes management" /><link rel="prev" href="ch14s03.html" title="Extended notes output formats" /><link rel="next" href="ch14s05.html" title="Regular expressions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">The query language</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch14s03.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Tools for reference and notes management</th><td width="20%" align="right"> <a accesskey="n" href="ch14s05.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect1-query-language"></a>The query language</h2></div></div></div><p>The <a class="link" href="re11.html#app-c-command-getref" title="getref"><span class="command"><strong>getref</strong></span></a> command is probably the most heavily used command. You use it to retrieve the references that you collected and saved in the database. To find a certain article or several related articles, all you have to do is to express your query in a language that RefDB understands. The first section describes how to formulate search strings for your queries.</p><p>The <a class="link" href="re11.html#app-c-command-getnote" title="getnote"><span class="command"><strong>getnote</strong></span></a> command used to locate extended notes is very similar. The specifics of this command will be described in the subsequent section.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect-description-reference-query-language"></a>The reference query language</h3></div></div></div><p>The syntax for the search string follows these rules:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>You can search for any fields in the RefDB database. As a matter of fact, you have to specify at least one field for your query. Something like <span class="command"><strong>getref *</strong></span> will not work, but you may use <span class="command"><strong>getref ":ID:>0"</strong></span> instead to list all entries in the database (beware, this may be a <span class="emphasis"><em>lot</em></span>).</p></li><li class="listitem"><p>Every search item has the following general form:</p><div class="informalexample"><p>:XY:[=|~|!=|!~|<>|<|>|<=|>=]<em class="replaceable"><code>string</code></em></p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>The current implementation of RefDB is very picky about spaces. Please make sure that you do not insert spaces or other whitespace on either side of the operators ("=", "~" and so on). If your value happens to start with a space, include the value in quotation marks or protect the space with a backslash.</p></div><p>The sequence ":XY:" denotes the reference data field to search in. The names are mostly taken from the RIS specification. Possible field names are:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">:TY:</span></dt><dd><p>Type of the reference.</p></dd><dt><span class="term">:ID:</span></dt><dd><p>The unique identifier of a reference. This is the numeric identifier that RefDB assigns to each new reference.</p></dd><dt><span class="term">:CK:</span></dt><dd><p>The unique citation key of a reference. This is the alphanumeric string that was either supplied by the user or automatically generated by RefDB.</p></dd><dt><span class="term">:TI:, :T2:, :T3:, :TX:</span></dt><dd><p>The title of the reference, of the secondary title, and of the series title, respectively. :TX: performs a search in all title levels.</p></dd><dt><span class="term">:AU:, :A2:, :A3:, :AX:</span></dt><dd><p>The name of an author, of a secondary author/editor, and of a series author, respectively. :AX: performs a search in all author levels.</p></dd><dt><span class="term">:PY:, :Y2:</span></dt><dd><p>The publication date and the secondary date, respectively.</p></dd><dt><span class="term">:N1:</span></dt><dd><p>The notes that user can add to the reference.</p></dd><dt><span class="term">:KW:</span></dt><dd><p>A keyword.</p></dd><dt><span class="term">:RP:</span></dt><dd><p>The reprint status of the reference.</p></dd><dt><span class="term">:AV:</span></dt><dd><p>The location of an offprint (physical, URL, or path)</p></dd><dt><span class="term">:SP:</span></dt><dd><p>The start page.</p></dd><dt><span class="term">:EP:</span></dt><dd><p>The end page.</p></dd><dt><span class="term">:JO:, :JF:, :J1:, :J2:</span></dt><dd><p>The abbreviated name, the full name, the user abbreviation 1, and the user abbreviation 2 of a journal name, respectively.</p></dd><dt><span class="term">:VL:</span></dt><dd><p>The volume number.</p></dd><dt><span class="term">:ED:</span></dt><dd><p>The name of an editor.</p></dd><dt><span class="term">:IS:</span></dt><dd><p>The issue (article) or chapter (book part) number.</p></dd><dt><span class="term">:CY:</span></dt><dd><p>City of publication of a book.</p></dd><dt><span class="term">:PB:</span></dt><dd><p>Name of the publishing company.</p></dd><dt><span class="term">:U1: through :U5:</span></dt><dd><p>The user-defined fields 1 through 5. In certain cases, U5 contains the number of the paper copy of the reference (see the <a class="link" href="re11.html#app-c-command-addref" title="addref"><span class="command"><strong>addref</strong></span></a> command).</p></dd><dt><span class="term">:N2:</span></dt><dd><p>The abstract of the reference.</p></dd><dt><span class="term">:SN:</span></dt><dd><p>The ISSN or ISBN number.</p></dd><dt><span class="term">:L1: through :L4:</span></dt><dd><p>The link fields 1 through 4.</p></dd><dt><span class="term">:AD:</span></dt><dd><p>The address of the contact person.</p></dd><dt><span class="term">:UR:</span></dt><dd><p>The URL of a web page related to the reference.</p></dd></dl></div><p>Some pseudo-fields help to retrieve the contents of the RIS fields M1 through M3. RefDB provides these pseudo-fields to better identify the contents of these fields. Please be aware that these pseudo-fields apply only to particular reference types. If in doubt, consult the <a class="ulink" href="http://www.referencemanager.com/support/docs/ReferenceManager11.pdf" target="_top">Reference Manager manual</a> which contains a list of how the M1-M3 fields are used by each reference type.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">:DO:</span></dt><dd><p>The <a class="ulink" href="http://www.doi.org/index.html" target="_top">digital objects identifier.</a></p></dd><dt><span class="term">:TO:</span></dt><dd><p>The type of work.</p></dd><dt><span class="term">:AR:</span></dt><dd><p>The area of a map</p></dd><dt><span class="term">:OS:</span></dt><dd><p>The operating system of a computer program</p></dd><dt><span class="term">:DG:</span></dt><dd><p>The type of degree of a thesis.</p></dd><dt><span class="term">:RT:</span></dt><dd><p>Running time of audiovisual data.</p></dd><dt><span class="term">:CI:</span></dt><dd><p>International class code of a patent.</p></dd><dt><span class="term">:CU:</span></dt><dd><p>US class code of a patent.</p></dd><dt><span class="term">:SE:</span></dt><dd><p>The email address of the sender.</p></dd><dt><span class="term">:RE:</span></dt><dd><p>The email address of the recipient.</p></dd><dt><span class="term">:MT:</span></dt><dd><p>The type of media.</p></dd><dt><span class="term">:NV:</span></dt><dd><p>The total number of volumes in a series</p></dd><dt><span class="term">:EI:</span></dt><dd><p>The edition of a book.</p></dd><dt><span class="term">:CO:</span></dt><dd><p>The type of computer used for a software or data.</p></dd><dt><span class="term">:CF:</span></dt><dd><p>The location of a conference</p></dd><dt><span class="term">:RN:</span></dt><dd><p>The registry number.</p></dd><dt><span class="term">:CL:</span></dt><dd><p>The classification of an audiovisual material.</p></dd><dt><span class="term">:SC:</span></dt><dd><p>The section of a magazine or newspaper</p></dd><dt><span class="term">:PN:</span></dt><dd><p>The number of a pamphlet.</p></dd><dt><span class="term">:CN:</span></dt><dd><p>The number of a chapter.</p></dd></dl></div><p>In addition to the above field specifiers, there are a few that allow to retrieve references based on extended notes attached to them:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">:NID:</span></dt><dd><p>The ID of an extended note.</p></dd><dt><span class="term">:NCK:</span></dt><dd><p>The alphanumeric key of an extended note.</p></dd></dl></div><p>References are matched according to these rules:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>The alphanumerical fields are matched by (non-)equality to a literal string or to a regular expression. For literal matches the operators "=" and "!=" are accepted, denoting equality and non-equality, respectively. The <em class="replaceable"><code>search-string</code></em> is a plain-text string.</p><p>Along the same lines, "~" and "!~" denote equality and non-equality for regular expression matches. The <em class="replaceable"><code>search-string</code></em> can contain any legal characters and constructs as in standard Unix regular expressions. By default, the query matches if the search string is contained anywhere in the target string. If you need a left-match, a right-match, or a full match, use the regexp special characters "^" (match the beginning of a line) and "$" (match the end of a line) to your needs. For further information about regular expressions, see the section <a class="link" href="ch14s05.html" title="Regular expressions">regular expressions</a></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.</p><p>If you use regular expressions, be aware that you will have to escape characters with a special meaning if you want them to be matched literally. For further details, see the <a class="link" href="ch14s04.html#sect2-query-examples" title="Some example queries">examples</a> below.</p></div></li><li class="listitem"><p>The numerical fields can be matched by equality, non-equality, or by greater-than/less-than comparisons. In these cases, use "!=", ">", and "<" instead of the "=", respectively.</p></li><li class="listitem"><p>If the <em class="replaceable"><code>search-string</code></em> contains spaces, the whole string must be enclosed by single quotation marks or the spaces must be escaped with a backslash "\".</p></li></ul></div></li><li class="listitem"><p>Several search items can be combined by the Boolean operators "AND", "OR", " AND NOT". They can be grouped by brackets "()".</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If you use the operator "AND NOT", the search item it refers to has to be enclosed in brackets. See the <a class="link" href="ch14s04.html#sect2-query-examples" title="Some example queries">examples</a> below.</p></div></li><li class="listitem"><p>The author (:AU:) and keyword (:KW:) searches allow an abbreviated syntax if you search for several authors or keywords at a time. The construct:</p><div class="informalexample"><p>:AU:=name1 AND :AU:=name2 AND :AU:=name3 ...</p></div><p>can be written as:</p><div class="informalexample"><p>:AU:='& name1 name2 name3 ...'</p></div><p>To specify an "OR" search, use "|" instead of "&".</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If an item in the search contains spaces, they have to be escaped by backslashes, as in "Amino\ Acid\ Sequence".</p></div></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect-description-notes-query-language"></a>The notes query language</h3></div></div></div><p>The <a class="link" href="re11.html#app-c-command-getnote" title="getnote">getnote</a> command uses essentially the same query language as described above. However, there is a different set of field specifiers that you can use to locate extended notes:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">:NID:</span></dt><dd><p>The unique id of an extended note.</p></dd><dt><span class="term">:NCK:</span></dt><dd><p>The unique citation key of an extended note.</p></dd><dt><span class="term">:NPY:</span></dt><dd><p>The date of an extended note.</p></dd><dt><span class="term">:NTI:</span></dt><dd><p>The title of an extended note.</p></dd><dt><span class="term">:NKW:</span></dt><dd><p>A keyword. This is a keyword attached to a note in order to categorize the latter, similar to a keyword in a reference.</p></dd><dt><span class="term">:KW:</span></dt><dd><p>A keyword. This is a keyword that the note is linked to, i.e. a keyword that the note was attached to in order to supply additional information.</p></dd><dt><span class="term">:AU:</span></dt><dd><p>The name of an author or editor. Use this field specifier to locate notes that are linked to a particular author.</p></dd><dt><span class="term">:JF:, :JO:, :J1:, :J2:</span></dt><dd><p>The full, abbreviated, or user-abbreviated name of a periodical. Use this field specifier to locate notes that are linked to a periodical.</p></dd><dt><span class="term">:ID:</span></dt><dd><p>The id of a reference. Use this field specifier to locate notes linked to a particular reference.</p></dd><dt><span class="term">:CK:</span></dt><dd><p>The citation key of a reference. Use this field specifier to locate notes linked to a particular reference.</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect2-query-examples"></a>Some example queries</h3></div></div></div><p>This section shows a few example queries to help you get familiar with the syntax. If you are not familiar with the regular expressions used here, please peruse the <a class="link" href="ch14s05.html" title="Regular expressions">regular expressions section</a>. We will not use any of the fancy switches of the <a class="link" href="re11.html#app-c-command-getref" title="getref"><span class="command"><strong>getref</strong></span></a> command here, so the output will always be a simple listing on the screen.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>These examples assume that your database engine supports Unix regular expressions. This holds true for MySQL and PostgreSQL, wherease SQLite uses the simpler SQL regular expressions instead.</p></div><p>We'll start with some easy queries. First we want to display a reference with a specific ID (25 in this example):</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :ID:=25</code></strong>
</pre></div><p>Next we want to list all references by a specific author. We'll use only the last name here. If several authors share this last name, we have to specify the initials as well, as shown in the second example. In the first example we use a regular expression match, denoted by the tilde operator. This obviates the need to know the full name precisely. The second example uses a literal match instead. Note the use of the caret "^" in the first example which makes sure that the name actually starts with the capital M. Otherwise, a last name like "DeMillerette" would match as well. This trick is not required in the second example as the literal match always implies a full match.</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :AU:~^Miller</code></strong>
</pre><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :AU:=Miller,J.D.</code></strong>
</pre></div><p>If Dr. Miller was a productive person, our previous query may have returned dozens of references. Now we try to filter out the paper or the papers that we really need. In the next example, we restrict the results to the years 1995 through 1999:</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :AU:~^Miller AND :PY:>1994 AND :PY:<2000</code></strong>
</pre></div><p>If this did not bring us close enough, we may try to include a coauthor:</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :AU:=~Miller AND :AU:~^Doe AND :PY:>1994 AND :PY:<2000</code></strong>
</pre></div><p>At this point we could narrow down the search by excluding other authors that often published with Dr. Miller, but are irrelevant here:</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :AU:~^Miller AND :AU:~^Doe AND NOT (:AU:~^Jones) AND :PY:>1994 AND :PY:<2000</code></strong>
</pre></div><p>Unfortunately, this is still a venerable list of publications. Now we try to include a few keywords. This is now a pretty complex query. It will return all references by the authors Miller and Doe between 1995 and 1999 with either the keyword "blood" or the keyword "animal" or the keywords "guanyl" and "cyclase", the latter only if both are present. The truncated spelling of "guanyl" ensures that both "guanylyl" and "guanylate" (which are interchangeable) will match. The funny expressions with the angle brackets ensure that the keywords will match regardless of whether they start with a capital letter or not.</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :AU:~^Miller AND :AU:~^Doe AND :PY:>1994 AND :PY:<2000 AND
(:KW:~[bB]lood OR :KW:~[aA]nimal OR (:KW:~[gG]uanyl AND :KW:~[cC]yclase))</code></strong>
</pre></div><p>And now for something completely different. If you've added a couple extended notes to your database, you can retrieve references that are attached to a specific extended note, e.g. to the note with the citation key "biochemistry1999":</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :NCK:=biochemistry1999</code></strong>
</pre></div><p>If you want to see all notes which are attached to a reference with the citation key "Miller1999", use the following command:</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getnote :CK:=Miller1999</code></strong>
</pre></div><p>Regular expressions may have unwanted side effects at times. Consider the keyword "52-67-5 (Penicillamine)" (a chemical name as used by the <a class="ulink" href="http://ncbi.nlm.nih.gov" target="_top">Pubmed</a> database). Doing a literal match is straightforward:</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :KW:='52-67-5 (Penicillamine)'</code></strong>
</pre></div><p>However, if we use the same argument for a regexp match, we won't get the desired results. The parentheses have a special meaning in regular expressions. Therefore we have to escape them if we want a literal match:</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :KW:~'\(Penicillamine\)'</code></strong>
</pre></div><p>Things are a little different again if you run a database engine that does not use Unix regular expressions, but SQL regular expressions instead. These know only '%' and '_' as special characters, and you have to escape them by doubling:</p><div class="informalexample"><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>getref :KW:~'100%%'</code></strong>
</pre></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Remember that if you extend or modify a previous query, you don't have to retype everything: Just use the <span class="keycap"><strong>up arrow key</strong></span> to scroll through the previous commands, or use <span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>r</strong></span> to search for a specific query in the history.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch14s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch14.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch14s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Extended notes output formats </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Regular expressions</td></tr></table></div></body></html>
|