The getref 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.
The getnote command used to locate extended notes is very similar. The specifics of this command will be described in the subsequent section.
The syntax for the search string follows these rules:
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 getref * will not work, but you may use getref ":ID:>0" instead to list all entries in the database (beware, this may be a lot).
Every search item has the following general form:
| Warning |
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 ("=", "~", "!=", "!~", "<", ">"). If your value should start with a space, include the value in quotation marks or protect the space with a backslash. |
The sequence ":XY:" denotes the reference data field to search in. The names are mostly taken from the RIS specification. Possible field names are:
Type of the reference.
The unique identifier of a reference. This is the numeric identifier that refdb assigns to each new reference.
The unique citation key of a reference. This is the alphanumeric string that was either supplied by the user or automatically generated by refdb.
The title of the reference, of the secondary title, and of the series title, respectively. :TA: performs a search in all title levels.
The name of an author, of a secondary author/editor, and of a series author, respectively.
The publication date and the secondary date, respectively.
The notes that user can add to the reference.
A keyword.
The reprint status of the reference.
The location of an offprint (physical, URL, or path)
The start page.
The end page.
The abbreviated name, the full name, the user abbreviation 1, and the user abbreviation 2 of a journal name, respectively.
The volume number.
The name of an editor.
The issue (article) or chapter (book part) number.
City of publication of a book.
Name of the publishing company.
The user-defined fields 1 through 5. In certain cases, U5 contains the number of the paper copy of the reference (see the addref command).
The abstract of the reference.
The ISSN or ISBN number.
The Miscellaneous fields 1 through 3.
The link fields 1 through 4.
The address of the contact person.
The URL of a web page related to the reference.
In addition to the above field specifiers, there are a few that allow to retrieve references based on extended notes attached to them:
The ID of an extended note.
The alphanumeric key of an extended note.
References are matched according to these rules:
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 search-string is a plain-text string.
Along the same lines, "~" and "!~" denote equality and non-equality for regular expression matches. The search-string 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 regular expressions
Note: Some database engines, like SQLite, do not support Unix-style regular expressions. Use SQL regular expressions instead.
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 examples below.
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.
If the search-string contains spaces, the whole string must be enclosed by single quotation marks or the spaces must be escaped with a backslash "\".
Several search items can be combined by the Boolean operators "AND", "OR", " AND NOT". They can be grouped by brackets "()".
Note: If you use the operator "AND NOT", the search item it refers to has to be enclosed in brackets. See the examples below.
The author (:AU:) and keyword (:KW:) searches allow an abbreviated syntax if you search for several authors or keywords at a time. The construct:
can be written as:
To specify an "OR" search, use "|" instead of "&".
Note: If an item in the search contains spaces, they have to be escaped by backslashes, as in "Amino\ Acid\ Sequence".
The getnote 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:
The unique id of an extended note.
The unique citation key of an extended note.
The date of an extended note.
The title of an extended note.
A keyword. This is a keyword attached to a note in order to categorize the latter, similar to a keyword in a reference.
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.
The name of an author or editor. Use this field specifier to locate notes that are linked to a particular author.
The full, abbreviated, or user-abbreviated name of a periodical. Use this field specifier to locate notes that are linked to a periodical.
The id of a reference. Use this field specifier to locate notes linked to a particular reference.
The citation key of a reference. Use this field specifier to locate notes linked to a particular reference.
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 regular expressions section. We will not use any of the fancy switches of the getref command here, so the output will always be a simple listing on the screen.
Note: 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.
We'll start with some easy queries. First we want to display a reference with a specific ID (25 in this example):
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.
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:
If this did not bring us close enough, we may try to include a coauthor:
At this point we could narrow down the search by excluding other authors that often published with Dr. Miller, but are irrelevant here:
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.
refdbc: 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)) |
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":
If you want to see all notes which are attached to a reference with the citation key "Miller1999", use the following command:
Regular expressions may have unwanted side effects at times. Consider the keyword "52-67-5 (Penicillamine)" (a chemical name as used by the Pubmed database). Doing a literal match is straightforward:
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:
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:
Tip: Remember that if you extend or modify a previous query, you don't have to retype everything: Just use the up arrow key to scroll through the previous commands, or use Ctrl-r to search for a specific query in the history.