Search-Query Documentation
Search Query is a Python package designed to load, lint, translate, save, improve, and automate academic literature search queries. It is extensible and currently supports PubMed, EBSCOHost, and Web of Science. The package can be used programmatically, through the command line, or as a pre-commit hook. It has zero dependencies and integrates in a variety of environments. The parsers and linters are battle-tested on peer-reviewed searchRxiv queries.
Installation
To install search-query, run:
pip install search-query
Quickstart
Creating a query programmatically is simple:
from search_query import OrQuery, AndQuery
# Typical building-blocks approach
digital_synonyms = OrQuery(["digital", "virtual", "online"], field="abstract")
work_synonyms = OrQuery(["work", "labor", "service"], field="abstract")
query = AndQuery([digital_synonyms, work_synonyms])
A query can also be parsed from a string or a JSON search file (see the overview of platform identifiers):
from search_query.parser import parse
query_string = '("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract])'
query = parse(query_string, platform="pubmed")
The built-in linter functionality validates queries by identifying syntactical errors:
from search_query.parser import parse
query_string = '("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract]'
query = parse(query_string, platform="pubmed")
# Output:
# ❌ Fatal: unbalanced-parentheses (PARSE_0002)
# - Unbalanced opening parenthesis
# Query: ("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract]
# ^^^
Once a query object is created, it can be translated for different databases.
The translation illustrates how the search for Title/Abstract is split into two elements:
1from search_query.parser import parse
2
3query_string = '("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract])'
4pubmed_query = parse(query_string, platform="pubmed")
5wos_query = pubmed_query.translate(target_syntax="wos")
6print(wos_query.to_string())
7# Output:
8# (AB="digital health" OR TI="digital health") AND (AB="privacy" OR TI="privacy")
The translated query can be saved as follows:
1from search_query import SearchFile
2
3search_file = SearchFile(
4 search_string=wos_query.to_string(),
5 platform="wos",
6 version="1",
7 authors=[{"name": "Tom Brady"}],
8 record_info={},
9 date={}
10)
11
12search_file.save("search-file.json")
Demo
A Jupyter Notebook demo (hosted on Binder) is available here:
Functional overview
The search-query package supports the entire lifecycle of academic search query management. Below is a high-level overview of the core functionalities:
