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])

We can also parse a query 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")

A useful feature of parsers is the built-in linter functionality, which helps us to validate the query 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 we have created a query object, we can translate it for different databases. Note how the syntax is translated and how the search for Title/Abstract is spit into two elements:

from search_query.parser import parse

query_string = '("digital health"[Title/Abstract]) AND ("privacy"[Title/Abstract])'
pubmed_query = parse(query_string, platform="pubmed")
wos_query = pubmed_query.translate(target_syntax="wos")
print(wos_query.to_string())
# Output:
# (AB="digital health" OR TI="digital health") AND (AB="privacy" OR TI="privacy")

Demo

A Jupyter Notebook demo (hosted on Binder) is available here:

Functional Overview

The search-query package is built to support researchers throughout the entire lifecycle of academic search query management. Below is a high-level overview of the core functionalities: