Download on Packal
ZotQuery is an Alfred workflow that grants the user access to the data stored in their Zotero application.
To date, it has only been tested on a Mac with both Zotero Firefox and Standalone installed.
ZotQuery should work with only Zotero Firefox or Standalone installed, but that is currently untested. If you are using the workflow successfully with either one only installed, please let me know. It has also only been tested on Alfred 2.1+. Finally, it was tested on the standard Python distribution for Mac OS X Mavericks (10.9), which is 2.7.6, and not on Python 3. Once again, if anyone is using the workflow successfully on another distribution of Python, please let me know.
When you first download the workflow, you will need to run
z:config first to configure the necessary settings before you attempt any queries. In fact,
ZotQuery will kick you to the
z:config command if you try any of the queries without having first configured your settings.
On first run, the configurator will begin by searching for, and creating if necessary,
ZotQuery’s workflow data folder, which can always be found at
/Users/$USER/Library/Application Support/Alfred 2/Workflow Data/com.hackademic.zotquery/.
Now, in version 5.5 and on,
ZotQuery no longer needs to install any Python dependencies. The workflow ships with all necessary components baked in. This has already removed a vast majority of the support issues.
The configurator next moves on to find all the necessary Zotero paths.
ZotQuery requires the full path to 3 things:
- your Zotero sqlite database
- your Zotero storage folder
- the folder that holds your linked attachments
The configurator attempts to find all necessary paths automatically, but if it fails, it will ask you to select one manually. The title of the dialog box will alert you to what path the configurator requires:
Once all paths are stored, the configurator moves on to set up your Zotero API information. This workflow utilizes the Zotero API to export citations of chosen items. In order for the user to utilize these functions, they must have and set up a Zotero private key. Step one requires your Zotero User ID:
If you do not have or do not know your Zotero User ID, click the
Where do I find my User ID? button. This will open Zotero’s “Feeds/API” tab, where you may need to login. Once logged in, you will see a page similar to this:
This shows a user who has two API keys set up, one for personal use and one for the iOS app PaperShip. If you do not have a Personal API key, you can easily set one up by clicking the “Create new private key” link. Your User ID will be a number, probably less than 8 digits. Insert it into the text field and click
Set User ID (Note: Applescript text input dialog boxes do not respond, typically, to the keyboard shortcut for paste, so you will likely need to right-click and manually paste in the ID).
Second, you will need to input your API Key:
ZotQuery reads this
settings.json file whenever it attempts to connect to the Zotero API, if you don’t insert the proper data here, the “Export Citation” and “Export Reference” (see below) functions will not work.
ZotQuery (now in version 4.0) will also allow you to set your export style and format. Once you have entered your API information, the configurator will move to setting your export preferences:
First, you will select the CSL Style that you wish to use. Currently
ZotQuery can export data in 5 different styles: Chicago (author-date), APA, MLA, Zotero’s own RTF-Scan format, and BibTeX. Now, in version 6.2,
ZotQuery will also allow users to export in the ODT-RTF Scannable Cites format (option not shown in image below). This will determine the format of exported citations and references.
All exported text is put in your clipboard, so you can use it anywhere in any text editor. You can also alter your export preferences at any point, using the
Once all settings and preferences are set, the configurator will finally build the JSON cache of your Zotero data.
ZotQuery will clone your Zotero database and also generate a JSON file with all pertinent information. Once cached,
ZotQuery is configured.
ZotQuery has 5 main functions:
- and Add
In general, the order of operations would be: cache, search, open/cite. This means, in order to search, you need to have an up-to-date cache, and in order to cite or open an item, you will first need to search and select it.
Search there are 8 options:
- General search
- Title-specific search
- Author-specific search
- Tag-specific search
- Collection-specific search
- Attachment-specific search
- Notes-specific search
- New items only
Note that all searches coerce both the query and the data into lowercase, so you can search using lowercase queries and still get matches.
The General search is launched by the keyword
zot or the short version
This will search your entire Zotero database for any use of the query provided. The search script is “loose,” that is, it searches for matches of the query “in” the data not matches that “equal” the data. This means you can search half words, words in the middle of titles, etc.
ZotQuery will not begin searching until you have entered at least 3 characters. This ensures faster, smarter results. Until you have typed at least 3 characters, you will see this result:
Once you complete your query, and the script catches up with you, you will see a list of all of your Zotero items that match the query. If your query doesn’t have any matches,
ZotQuery returns an error:
If, however, you have results,
ZotQuery presents them in a ranked order:
For ease of use, the workflow provides unique icons for the various item types:
- conference paper
If your item has an attachment, the icon changes to signal the addition as will the subtitle field. The subtitle field will include
Attachments: n, where n is the number of attachments:
The altered icons each have a small plus sign in the top-right corner:
- article + attachment
- book + attachment
- chapter + attachment
- conference paper + attachment
- other + attachment
The Author search is launched by
zot:a or the short version
This search only queries the last names of the authors of your Zotero data. For example:
zot:a thomas will return all the items that have an author (or editor, translator, etc.) with the last name “Thomas”.
The Title search is launched by
zot:t or the short version
This search only queries the title fields of your Zotero data. For example:
zot:t virgil will return all of the items whose title contains the word “Virgil”.
The final two searches (Tag and Collection) are two-step searches. In step-one, you search for a particular Tag or Collection; in step-two you search within that particular Tag or Collection for your query.
The Tag search is launched by
z:tag or the short version
This allows you to search through all of your Zotero tags.
Once you select a tag, Alfred will automatically initiate the
zot:tag search, which will search within that tag for your query. The
znt) query functions just like the general
zot query, except that it is limited to those items with the previously chosen tag.
The Collection search is similar. It is launched by
z:col, or by
zc, which begins a search for all of your Zotero collections.
As you type, it will filter any collections that contain the query.
Once you choose a particular collection, Alfred will initiate the
zot:c search (also
znc), which will search within that particular collection.
As above, the
zot:c search functions just like the simple
Finally, you can now (after version 4.1) search only items with attachments using the
z:att query (short version =
zat). This query allows you to quickly find pdfs or epubs in your Zotero library and open them in your default application. As of now,
z:att only allows for you to open the attached files.
Similarly, you can use
zn) to search through the notes for any items. This can prove very helpful for people who use Zotero as their notes repository for all of their secondary sources.
z:new search will bring all of the items added to Zotero since the last cache update. This feature is there to make it easier to find items if you do one long research run, adding lots of items to Zotero before re-using
z:new you can double check exactly what’s been added.
Together these 8 search options provide you with various ways to find the exact item you need. Once you find that item, you have a few options with what you can do next.
Once you select an item (in all the searches except
z:att), there are 5 options:
- Open Zotero to that item.
- Export a short reference to that item.
- Export a citation of that item.
- Open the item’s attachment (if it has any).
- Append a citation of the item to a temporary bibliography
If you merely hit
return on your chosen item, option 1 will occur and Zotero will open to that item.
If you hit
option+return when you choose your item, you will export a short reference to that item.
Depending on your style and format settings, your reference will be of various types.
If you hit
control+return, you will export a full citation of the item in your chosen format.
Next, if you hit
shift+return, you will open the attachment of that item.
Finally, if you hit
fn+return, you will append a citation of the item to a temporary bibliography file.
This bibliography file is stored in the workflow’s cache folder. You can add as many citations to it as you wish. This function allows you to dynamically build a Bibliography/Works Cited page. When you have put all the needed citations in the temporary file, you need only run the
z:bib command to export them.
This will take all of the citations in the temporary bibliography file, organize them in alphabetical order, and copy the result to the clipboard. A result in Markdown format will resemble this:
The temporary bibliography file is not the only way, however, to automatically generate a full Bibliography/Works Cited page. Since many Zotero users, myself included, use either Tags or Collections to organize their library into writing projects,
ZotQuery also allows the user to export a full formatted bibliography (in alphabetical order) for any Tag or Collection.
When you are searching for a Tag or a Collection with
z:col, you can use
control+return to export a bibliography of that Tag or Collection, instead of simply searching within that Tag or Collection by hitting
Thus, if you organize the citations for particular project within a certain Collection or under a certain Tag, you can create full, formatted Works Cited pages on the fly from
Taken together, these export options make
ZotQuery an academic’s best friend in the writing process. You can insert in-text references, full citations, or generate entire Works Cited all from
ZotQuery. These citations, references, and bibliographies can also now be Rich Text in addition to Markdown. This allows users who write in Microsoft Word, Pages, or Scrivener to utilize
ZotQuery. You can also open Zotero directly to an item (for quick meta-data editing) or even open an item’s attachment to double check a quote.
There are, however, a few caveats and possible configurations. First, these final options (export reference, export citations, append citation, and generate works cited) all use Zotero’s web API, and so they require an internet connection. If you are not connected to the internet, all will fail (gracefully). Second, the workflow defaults to Chicago (author-date) style both for short references and full citations (examples above). If you wish to use another of Zotero’s CSL styles, you will need to change the style via the
z:settings command. Since
ZotQuery now exports BibTeX and RTF-Scan cite keys, even users who prefer to write in [MultiMarkdown](http://fletcherpenney.net/multimarkdown/ “MultiMarkdown - fletcherpenney.net”) and convert to [LaTeX](http://www.latex-project.org/ “LaTeX – A document preparation system”) can utilize
Note: These features will also require that you have the proper Zotero API data in the
settings.json file. For instructions on setting this up, see above.
There is also the Caching function. All of the query scripts are querying a JSON cache of your Zotero database. This file is created and then updated with the keyword
This function will find your Zotero sqlite database, read its contents, and create a JSON cache of the pertinent information.
When you first download the workflow, the configurator will run this command in order to create the cache that all of the query scripts will read. You will always be able to update the cache with this command as well, although the workflow is configured to auto-update the cache after every query execution; that is, after you do any action on an item (open, reference, citation, append). This means that after you perform an action on an item, the workflow will check if the cache needs updating and if so, the workflow will update it in the background.
Note, however, that if you have altered your Zotero data and are about to use
ZotQuery, you will need to force an update using
z:cache before any of the queries have access to the new information. As a general rule of thumb, I will force update the cache each time I sit down to a lot of work with
ZotQuery, but will let it auto-update most of the time.
Aside from the core features,
ZotQuery comes with some additional features. First,
ZotQuery comes with the ability to set up a keyboard shortcut to launch the title-specific search. I use
command+shift+Z as my hotkey. If you setup the hotkey, you can launch immediately into the title search (with a snazzy interface):
You can also change this hotkey to launch whichever query you like.
ZotQuery also has the ability to be an option in your Alfred fallback searches. In order to setup
ZotQuery as a fallback search option, open Alfred’s preferences and go to the
Features tab. Near the bottom of the page you will see a button to
Setup fallback results:
When you click that button a panel will slide out of top:
+ button and select
ZotQuery from the
Workflow Trigger list. You can even re-order the fallback searches, and put
ZotQuery near the top. When setup, this will allow you to search in Alfred like this:
And have it immediately become a
It’s also possible to manually determine what
ZotQuery will use to search for the various query types. NOTE: This is probably a power-user feature and not for those who don’t know their way around JSON.
In order to alter the search scope for any query type, you will need to find and open the
zot_filters.json file in
ZotQuery’s storage folder (
Storage to open that folder). If you edit this file, it changes what
ZotQuery looks at for the various filters. The file is (obviously) in JSON format. The keys are the various types of filters (
in-collection, etc). For each key, there is a list of items that it will search. This items are themselves lists with two items (except for
notes, which is only one item). To remove an item, be sure to remove its entirety:
1 2 3 4
[ "data", "title" ],
You could also use a scripting language to read the JSON, manipulate the dictionary, then overwrite the file with new JSON.
Another “power-user” feature allows users to limit the overall scope of
ZotQuery to only their personal library. Since
ZotQuery now indexes and caches any Group Libraries that you may be a part of, these items are searchable from
ZotQuery. However, it is occasionally the case that user’s don’t want to search these items, but only their own personal items. In order to restrict
ZotQuery’s scope to only your personal library, you only need to change a few things.
If you open Alfred and
ZotQuery, and you open the Run Script action connected to
z:cache you will find this:
python zotquery.py --cache True False
These three arguments tell zotquery to use the caching object (
--cache), to force a cache update (
True) and to not limit the scope to only the user’s personal library (
False). As detailed in the description at the top of
zotquery.py, the last argument is a Boolean value for whether or not to limit the scope of the cache to the user’s personal library. By default, it is set to
False, which means that group libraries are included in
ZotQuery’s cache. If you change this to
ZotQuery will only cache your personal library, and thus will only search your personal library.
ZotQuery also has a cache updater that runs each time you perform an action. This is the Run Script action beneath the “Citation Copied!” notification for each filter type. If you open this Run Script action you will see:
python zotquery.py --cache False False.
This will check to see if the cache needs updating (thus the
False force argument), and will include all libraries. To exclude group libraries, change each of these Run Script actions to:
python zotquery.py --cache False True.
So that’s how you use
ZotQuery. It’s a powerful tool. I hope you like it.