Class SearchQuery

Builder for constructing PubMed search queries programmatically

Provides a fluent API for building complex PubMed search queries with support for:

Basic search terms
Date filtering
Article type and language filtering
Open access filtering
Boolean logic operations (AND, OR, NOT)
MeSH terms and author filtering

Example

const query = new SearchQuery()
  .query("covid-19")
  .publishedInYear(2024)
  .articleType("Clinical Trial")
  .freeFullTextOnly();

const articles = await client.executeQuery(query);

Constructors

constructor

new SearchQuery(): SearchQuery
Create a new empty search query builder

Returns SearchQuery
- Defined in index.d.ts:188

Accessors

limit

get limit(): number
Get the limit for this query

Returns number
Maximum number of results (default: 20)
Example
```
const query = new SearchQuery().query("cancer").limit(100);
query.getLimit(); // 100
```
- Defined in index.d.ts:262

Methods

abstractContains

abstractContains(text: string): this
Search in article abstracts only
Parameters
- text: string
  Abstract text to search for
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .abstractContains("neural networks");
```
- Defined in index.d.ts:456

affiliation

affiliation(institution: string): this
Filter by institution/affiliation
Parameters
- institution: string
  Institution name to search for
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("cardiology")
  .affiliation("Harvard Medical School");
```
- Defined in index.d.ts:605

ageGroup

ageGroup(ageGroup: string): this
Filter by age group
Parameters
- ageGroup: string
  Age group to filter by (e.g., "Child", "Adult", "Aged")
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("pediatric medicine")
  .ageGroup("Child");
```
- Defined in index.d.ts:658

and

and(other: SearchQuery): SearchQuery
Combine this query with another using AND logic
Parameters
- other: SearchQuery
  Another SearchQuery to combine with
Returns SearchQuery
New SearchQuery with combined logic
Example
```
const q1 = new SearchQuery().query("covid-19");
const q2 = new SearchQuery().query("vaccine");
const combined = q1.and(q2);
combined.build(); // "(covid-19) AND (vaccine)"
```
- Defined in index.d.ts:687

animalStudiesOnly

animalStudiesOnly(): this
Filter to animal studies only

Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("preclinical research")
  .animalStudiesOnly();
```
- Defined in index.d.ts:644

articleType

articleType(typeName: string): this
Filter by a single article type
Parameters
- typeName: string
  Article type (case-insensitive) Supported types: "Clinical Trial", "Review", "Systematic Review", "Meta-Analysis", "Case Reports", "Randomized Controlled Trial" (or "RCT"), "Observational Study"
Returns this
Self for method chaining
Throws
Error if article type is not recognized
Example
```
const query = new SearchQuery()
  .query("cancer")
  .articleType("Clinical Trial");
```
- Defined in index.d.ts:347

articleTypes

articleTypes(types: string[]): this
Filter by multiple article types (OR logic)
Parameters
- types: string[]
  Array of article type names (case-insensitive)
Returns this
Self for method chaining
Throws
Error if any article type is not recognized
Example
```
const query = new SearchQuery()
  .query("treatment")
  .articleTypes(["RCT", "Meta-Analysis"]);
```
- Defined in index.d.ts:362

author

author(name: string): this
Filter by author name
Parameters
- name: string
  Author name to search for
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("machine learning")
  .author("Williams K");
```
- Defined in index.d.ts:563

build

build(): string
Build the final PubMed query string

Returns string
Query string for PubMed E-utilities API
Throws
Error if no search terms have been added
Example
```
const query = new SearchQuery()
  .query("covid-19")
  .query("treatment");
query.build(); // "covid-19 treatment"
```
- Defined in index.d.ts:250

customFilter

customFilter(filter: string): this
Add a custom filter
Parameters
- filter: string
  Custom filter string in PubMed syntax
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("research")
  .customFilter("humans[mh]");
```
- Defined in index.d.ts:672

exclude

exclude(excluded: SearchQuery): SearchQuery
Exclude articles matching the given query
Parameters
- excluded: SearchQuery
  SearchQuery representing articles to exclude
Returns SearchQuery
New SearchQuery with exclusion logic
Example
```
const base = new SearchQuery().query("cancer treatment");
const exclude = new SearchQuery().query("animal studies");
const filtered = base.exclude(exclude);
filtered.build(); // "(cancer treatment) NOT (animal studies)"
```
- Defined in index.d.ts:729

firstAuthor

firstAuthor(name: string): this
Filter by first author
Parameters
- name: string
  First author name to search for
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("cancer")
  .firstAuthor("Smith J");
```
- Defined in index.d.ts:577

freeFullTextOnly

freeFullTextOnly(): this
Filter to articles with free full text (open access)

Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("cancer")
  .freeFullTextOnly();
```
- Defined in index.d.ts:391

fullTextOnly

fullTextOnly(): this
Filter to articles with full text links (including subscription-based)

Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("diabetes")
  .fullTextOnly();
```
- Defined in index.d.ts:404

grantNumber

grantNumber(grantNumber: string): this
Filter by grant number
Parameters
- grantNumber: string
  Grant number to search for
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .grantNumber("R01AI123456");
```
- Defined in index.d.ts:496

group

group(): SearchQuery
Add parentheses around the current query for grouping

Returns SearchQuery
New SearchQuery wrapped in parentheses
Example
```
const query = new SearchQuery()
  .query("cancer")
  .or(new SearchQuery().query("tumor"))
  .group();
query.build(); // "((cancer) OR (tumor))"
```
- Defined in index.d.ts:744

hasAbstract

hasAbstract(): this
Filter to articles that have abstracts

Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("genetics")
  .hasAbstract();
```
- Defined in index.d.ts:430

humanStudiesOnly

humanStudiesOnly(): this
Filter to human studies only

Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("drug treatment")
  .humanStudiesOnly();
```
- Defined in index.d.ts:631

journal

journal(name: string): this
Filter by journal name
Parameters
- name: string
  Journal name to search for
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("cancer")
  .journal("Nature");
```
- Defined in index.d.ts:483

language

language(lang: string): this
Filter by language
Parameters
- lang: string
  Language name (case-insensitive) Supported: "English", "Japanese", "German", "French", "Spanish", etc. Unknown languages are passed through as custom values.
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("cancer")
  .language("English");
```
- Defined in index.d.ts:378

lastAuthor

lastAuthor(name: string): this
Filter by last author
Parameters
- name: string
  Last author name to search for
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("genomics")
  .lastAuthor("Johnson M");
```
- Defined in index.d.ts:591

meshMajorTopic

meshMajorTopic(term: string): this
Filter by MeSH major topic
Parameters
- term: string
  MeSH term to filter by as a major topic
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .meshMajorTopic("Diabetes Mellitus, Type 2");
```
- Defined in index.d.ts:522

meshSubheading

meshSubheading(subheading: string): this
Filter by MeSH subheading
Parameters
- subheading: string
  MeSH subheading to filter by
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .meshTerm("Diabetes Mellitus")
  .meshSubheading("drug therapy");
```
- Defined in index.d.ts:549

meshTerm

meshTerm(term: string): this
Filter by MeSH term
Parameters
- term: string
  MeSH term to filter by
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .meshTerm("Neoplasms");
```
- Defined in index.d.ts:509

meshTerms

meshTerms(terms: string[]): this
Filter by multiple MeSH terms
Parameters
- terms: string[]
  Array of MeSH terms to filter by
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .meshTerms(["Neoplasms", "Antineoplastic Agents"]);
```
- Defined in index.d.ts:535

negate

negate(): SearchQuery
Negate this query using NOT logic

Returns SearchQuery
New SearchQuery with NOT logic
Example
```
const query = new SearchQuery().query("cancer").negate();
query.build(); // "NOT (cancer)"
```
- Defined in index.d.ts:714

or

or(other: SearchQuery): SearchQuery
Combine this query with another using OR logic
Parameters
- other: SearchQuery
  Another SearchQuery to combine with
Returns SearchQuery
New SearchQuery with combined logic
Example
```
const q1 = new SearchQuery().query("diabetes");
const q2 = new SearchQuery().query("hypertension");
const combined = q1.or(q2);
combined.build(); // "(diabetes) OR (hypertension)"
```
- Defined in index.d.ts:702

orcid

orcid(orcidId: string): this
Filter by ORCID identifier
Parameters
- orcidId: string
  ORCID identifier to search for
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .orcid("0000-0001-2345-6789");
```
- Defined in index.d.ts:618

pmcOnly

pmcOnly(): this
Filter to articles with PMC full text

Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("genomics")
  .pmcOnly();
```
- Defined in index.d.ts:417

publishedAfter

publishedAfter(year: number): this
Filter to articles published after a specific year
Parameters
- year: number
  Year after which articles were published
Returns this
Self for method chaining
Throws
Error if year is outside valid range
Example
```
const query = new SearchQuery()
  .query("crispr")
  .publishedAfter(2020);
```
- Defined in index.d.ts:314

publishedBefore

publishedBefore(year: number): this
Filter to articles published before a specific year
Parameters
- year: number
  Year before which articles were published
Returns this
Self for method chaining
Throws
Error if year is outside valid range
Example
```
const query = new SearchQuery()
  .query("genome")
  .publishedBefore(2020);
```
- Defined in index.d.ts:329

publishedBetween

publishedBetween(startYear: number, endYear?: number | null): this
Filter by publication date range
Parameters
- startYear: number
  Start year (inclusive)
- OptionalendYear: number | null
  End year (inclusive, optional)
Returns this
Self for method chaining
Throws
Error if years are outside valid range
Example
```
// Filter to 2020-2024
const query = new SearchQuery()
  .query("cancer")
  .publishedBetween(2020, 2024);

// Filter from 2020 onwards
const query2 = new SearchQuery()
  .query("treatment")
  .publishedBetween(2020);
```
- Defined in index.d.ts:299

publishedInYear

publishedInYear(year: number): this
Filter to articles published in a specific year
Parameters
- year: number
  Year to filter by (must be between 1800 and 3000)
Returns this
Self for method chaining
Throws
Error if year is outside valid range
Example
```
const query = new SearchQuery()
  .query("covid-19")
  .publishedInYear(2024);
```
- Defined in index.d.ts:277

query

query(term: string): this
Add a search term to the query

Terms are accumulated and will be space-separated in the final query.
Parameters
- term: string
  Search term string
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("covid-19")
  .query("treatment");
query.build(); // "covid-19 treatment"
```
- Defined in index.d.ts:205

setLimit

setLimit(limit: number): this
Set the maximum number of results to return
Parameters
- limit: number
  Maximum number of results (clamped to 1-10,000 range)
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .query("cancer")
  .setLimit(50);
```
- Defined in index.d.ts:235

sort

sort(sortOrder: string): this
Set the sort order for search results
Parameters
- sortOrder: string
  Sort order (case-insensitive) Supported: "relevance", "pub_date", "author", "journal"
Returns this
Self for method chaining
Throws
Error if sort order is not recognized
Example
```
const query = new SearchQuery()
  .query("cancer")
  .sort("pub_date");
```
- Defined in index.d.ts:760

terms

terms(terms: string[]): this
Add multiple search terms at once

Each term is processed like query(). Empty strings are filtered out.
Parameters
- terms: string[]
  Array of search term strings
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .terms(["covid-19", "vaccine", "efficacy"]);
query.build(); // "covid-19 vaccine efficacy"
```
- Defined in index.d.ts:221

titleContains

titleContains(text: string): this
Search in article titles only
Parameters
- text: string
  Title text to search for
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .titleContains("machine learning");
```
- Defined in index.d.ts:443

titleOrAbstract

titleOrAbstract(text: string): this
Search in both title and abstract
Parameters
- text: string
  Text to search for in title or abstract
Returns this
Self for method chaining
Example
```
const query = new SearchQuery()
  .titleOrAbstract("CRISPR gene editing");
```
- Defined in index.d.ts:469

Class SearchQuery

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Returns SearchQuery

Accessors

limit

Returns number

Example

Methods

abstractContains

Parameters

Returns this

Example

affiliation

Parameters

Returns this

Example

ageGroup

Parameters

Returns this

Example

and

Parameters

Returns SearchQuery

Example

animalStudiesOnly

Returns this

Example

articleType

Parameters

Returns this

Throws

Example

articleTypes

Parameters

Returns this

Throws

Example

author

Parameters

Returns this

Example

build

Returns string

Throws

Example

customFilter

Parameters

Returns this

Example

exclude

Parameters

Returns SearchQuery

Example

firstAuthor

Parameters

Returns this

Example

freeFullTextOnly

Returns this

Example

fullTextOnly

Returns this

Example

grantNumber

Parameters

Returns this

Example

group

Returns SearchQuery

Example

hasAbstract

Returns this

Example

humanStudiesOnly