Struct SearchQuery 

pub struct SearchQuery { /* private fields */ }

Builder for constructing PubMed search queries

Implementations

impl SearchQuery

pub fn new() -> Self

Create a new search query builder

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new();

pub fn query<S: Into<String>>(self, terms: S) -> Self

Add search terms

Arguments

• terms - Search terms to add

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("covid-19 treatment");

pub fn terms<S: AsRef<str>>(self, terms: &[S]) -> Self

Add multiple search terms

Arguments

• terms - Multiple search terms

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .terms(&["covid-19", "treatment", "vaccine"]);

pub fn limit(self, limit: usize) -> Self

Set the maximum number of results to return

Arguments

• limit - Maximum number of results

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("cancer")
    .limit(100);

pub fn build(&self) -> String

Build the final query string

Returns

A PubMed query string that can be used with E-utilities

Example

use pubmed_client::pubmed::SearchQuery;

let query_string = SearchQuery::new()
    .query("covid-19")
    .build();

assert_eq!(query_string, "covid-19");

pub fn get_limit(&self) -> usize

Get the limit for this query

pub fn sort(self, sort: SortOrder) -> Self

Set the sort order for search results

Arguments

• sort - Sort order for the search results

Example

use pubmed_client::pubmed::{SearchQuery, SortOrder};

let query = SearchQuery::new()
    .query("cancer")
    .sort(SortOrder::PublicationDate);

pub fn get_sort(&self) -> Option<&SortOrder>

Get the sort order for this query

pub async fn search(&self, client: &PubMedClient) -> Result<Vec<String>>

Execute the search using the provided PubMed client

Arguments

• client - PubMed client to use for the search

Returns

Returns a list of PMIDs matching the query

Example

use pubmed_client::{PubMedClient, pubmed::SearchQuery};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let pmids = SearchQuery::new()
        .query("covid-19")
        .limit(10)
        .search(&client)
        .await?;

    println!("Found {} articles", pmids.len());
    Ok(())
}

pub async fn search_and_fetch( &self, client: &PubMedClient, ) -> Result<Vec<PubMedArticle>>

Execute the search and fetch full article metadata

Arguments

• client - PubMed client to use for the search

Returns

Returns a list of PubMed articles with metadata

Example

use pubmed_client::{PubMedClient, pubmed::SearchQuery};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let articles = SearchQuery::new()
        .query("machine learning medicine")
        .limit(5)
        .search_and_fetch(&client)
        .await?;

    for article in articles {
        println!("{}: {}", article.pmid, article.title);
    }
    Ok(())
}

pub async fn search_with_details( &self, client: &PubMedClient, ) -> Result<SearchResult>

Execute the search and return detailed results including query translation

This method uses the NCBI history server and returns a SearchResult that includes the query translation (how PubMed interpreted the query), total count, and session information for paginated fetching.

Arguments

• client - PubMed client to use for the search

Returns

Returns a SearchResult with PMIDs, total count, query translation, and history session

Example

use pubmed_client::{PubMedClient, pubmed::SearchQuery};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PubMedClient::new();
    let result = SearchQuery::new()
        .query("asthma")
        .limit(10)
        .search_with_details(&client)
        .await?;

    println!("Total: {}", result.total_count);
    if let Some(translation) = &result.query_translation {
        println!("PubMed interpreted query as: {}", translation);
    }
    Ok(())
}

impl SearchQuery

pub fn mesh_major_topic<S: Into<String>>(self, mesh_term: S) -> Self

Filter by MeSH major topic

Arguments

• mesh_term - MeSH term to filter by as a major topic

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .mesh_major_topic("Diabetes Mellitus, Type 2");

pub fn mesh_term<S: Into<String>>(self, mesh_term: S) -> Self

Filter by MeSH term

Arguments

• mesh_term - MeSH term to filter by

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .mesh_term("Neoplasms");

pub fn mesh_terms<S: AsRef<str>>(self, mesh_terms: &[S]) -> Self

Filter by multiple MeSH terms

Arguments

• mesh_terms - MeSH terms to filter by

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .mesh_terms(&["Neoplasms", "Antineoplastic Agents"]);

pub fn mesh_subheading<S: Into<String>>(self, subheading: S) -> Self

Filter by MeSH subheading

Arguments

• subheading - MeSH subheading to filter by

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .mesh_term("Diabetes Mellitus")
    .mesh_subheading("drug therapy");

pub fn first_author<S: Into<String>>(self, author: S) -> Self

Filter by first author

Arguments

• author - First author name to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("cancer treatment")
    .first_author("Smith J");

pub fn last_author<S: Into<String>>(self, author: S) -> Self

Filter by last author

Arguments

• author - Last author name to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("genomics")
    .last_author("Johnson M");

pub fn author<S: Into<String>>(self, author: S) -> Self

Filter by any author

Arguments

• author - Author name to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("machine learning")
    .author("Williams K");

pub fn affiliation<S: Into<String>>(self, institution: S) -> Self

Filter by institution/affiliation

Arguments

• institution - Institution name to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("cardiology research")
    .affiliation("Harvard Medical School");

pub fn orcid<S: Into<String>>(self, orcid_id: S) -> Self

Filter by ORCID identifier

Arguments

• orcid_id - ORCID identifier to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("computational biology")
    .orcid("0000-0001-2345-6789");

pub fn organism_mesh<S: Into<String>>(self, organism: S) -> Self

Filter by organism using MeSH terms (scientific or common name)

Arguments

• organism - Organism name (scientific or common name)

Examples

use pubmed_client::pubmed::SearchQuery;

// Using scientific name
let query = SearchQuery::new()
    .query("gene expression")
    .organism_mesh("Mus musculus");

// Using common name
let query = SearchQuery::new()
    .query("metabolism")
    .organism_mesh("Mice");

// Using bacteria
let query = SearchQuery::new()
    .query("antibiotic resistance")
    .organism_mesh("Escherichia coli");

pub fn human_studies_only(self) -> Self

Filter to human studies only

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("drug treatment")
    .human_studies_only();

pub fn animal_studies_only(self) -> Self

Filter to animal studies only

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("preclinical research")
    .animal_studies_only();

pub fn age_group<S: Into<String>>(self, age_group: S) -> Self

Filter by age group

Arguments

• age_group - Age group to filter by (e.g., “Child”, “Adult”, “Aged”)

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("pediatric medicine")
    .age_group("Child");

pub fn custom_filter<S: Into<String>>(self, filter: S) -> Self

Add a custom filter

Arguments

• filter - Custom filter string in PubMed syntax

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("research")
    .custom_filter("humans[mh]");

impl SearchQuery

pub fn and(self, other: SearchQuery) -> Self

Combine this query with another using AND logic

Arguments

• other - Another SearchQuery to combine with

Example

use pubmed_client::pubmed::SearchQuery;

let query1 = SearchQuery::new().query("covid-19");
let query2 = SearchQuery::new().query("vaccine");
let combined = query1.and(query2);

pub fn or(self, other: SearchQuery) -> Self

Combine this query with another using OR logic

Arguments

• other - Another SearchQuery to combine with

Example

use pubmed_client::pubmed::SearchQuery;

let query1 = SearchQuery::new().query("diabetes");
let query2 = SearchQuery::new().query("hypertension");
let combined = query1.or(query2);

pub fn negate(self) -> Self

Negate this query using NOT logic

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("cancer")
    .negate();

pub fn exclude(self, excluded: SearchQuery) -> Self

Exclude articles matching the given query

Arguments

• excluded - SearchQuery representing articles to exclude

Example

use pubmed_client::pubmed::SearchQuery;

let base_query = SearchQuery::new().query("cancer treatment");
let exclude_query = SearchQuery::new().query("animal studies");
let filtered = base_query.exclude(exclude_query);

pub fn group(self) -> Self

Add parentheses around the current query for grouping

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("cancer")
    .or(SearchQuery::new().query("tumor"))
    .group();

impl SearchQuery

pub fn date_range(self, start_year: u32, end_year: Option<u32>) -> Self

Filter by publication date range

Arguments

• start_year - Start year (inclusive)
• end_year - End year (inclusive, optional)

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("immunotherapy")
    .date_range(2020, Some(2023));

pub fn published_between<S, E>(self, start: S, end: Option<E>) -> Self

where S: Into<PubDate>, E: Into<PubDate>,

Filter by publication date range with flexible precision

Arguments

• start - Start date (can be year, (year, month), or (year, month, day))
• end - End date (optional, same format as start)

Examples

use pubmed_client::pubmed::SearchQuery;

// Year range
let query = SearchQuery::new()
    .query("covid vaccines")
    .published_between(2020, Some(2023));

// Month precision
let query = SearchQuery::new()
    .query("pandemic response")
    .published_between((2020, 3), Some((2021, 12)));

// Day precision
let query = SearchQuery::new()
    .query("outbreak analysis")
    .published_between((2020, 3, 15), Some((2020, 12, 31)));

// Open-ended (from date onwards)
let query = SearchQuery::new()
    .query("recent research")
    .published_between(2023, None::<u32>);

pub fn published_in_year(self, year: u32) -> Self

Filter to articles published in a specific year

Arguments

• year - Year to filter by

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("artificial intelligence")
    .published_in_year(2023);

pub fn entry_date_between<S, E>(self, start: S, end: Option<E>) -> Self

where S: Into<PubDate>, E: Into<PubDate>,

Filter by entry date (when added to PubMed database)

Arguments

• start - Start date (can be year, (year, month), or (year, month, day))
• end - End date (optional, same format as start)

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("recent discoveries")
    .entry_date_between(2023, Some(2024));

pub fn modification_date_between<S, E>(self, start: S, end: Option<E>) -> Self

where S: Into<PubDate>, E: Into<PubDate>,

Filter by modification date (when last updated in PubMed database)

Arguments

• start - Start date (can be year, (year, month), or (year, month, day))
• end - End date (optional, same format as start)

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("updated articles")
    .modification_date_between(2023, None::<u32>);

pub fn published_after<D>(self, date: D) -> Self

where D: Into<PubDate>,

Filter to articles published after a specific date

Arguments

• date - Date after which articles were published (can be year, (year, month), or (year, month, day))

Examples

use pubmed_client::pubmed::SearchQuery;

// After a specific year
let query = SearchQuery::new()
    .query("crispr")
    .published_after(2020);

// After a specific month
let query = SearchQuery::new()
    .query("covid treatment")
    .published_after((2020, 3));

// After a specific date
let query = SearchQuery::new()
    .query("pandemic response")
    .published_after((2020, 3, 15));

pub fn published_before<D>(self, date: D) -> Self

where D: Into<PubDate>,

Filter to articles published before a specific date

Arguments

• date - Date before which articles were published (can be year, (year, month), or (year, month, day))

Examples

use pubmed_client::pubmed::SearchQuery;

// Before a specific year
let query = SearchQuery::new()
    .query("genome sequencing")
    .published_before(2020);

// Before a specific month
let query = SearchQuery::new()
    .query("early research")
    .published_before((2020, 3));

// Before a specific date
let query = SearchQuery::new()
    .query("pre-pandemic studies")
    .published_before((2020, 3, 15));

impl SearchQuery

pub fn title_contains<S: Into<String>>(self, title: S) -> Self

Search in article titles only

Arguments

• title - Title text to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .title_contains("machine learning");

pub fn abstract_contains<S: Into<String>>(self, abstract_text: S) -> Self

Search in article abstracts only

Arguments

• abstract_text - Abstract text to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .abstract_contains("deep learning neural networks");

pub fn title_or_abstract<S: Into<String>>(self, text: S) -> Self

Search in both title and abstract

Arguments

• text - Text to search for in title or abstract

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .title_or_abstract("CRISPR gene editing");

pub fn journal<S: Into<String>>(self, journal: S) -> Self

Filter by journal name

Arguments

• journal - Journal name to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("cancer treatment")
    .journal("Nature");

pub fn journal_abbreviation<S: Into<String>>(self, abbreviation: S) -> Self

Filter by journal title abbreviation

Arguments

• abbreviation - Journal abbreviation to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("stem cells")
    .journal_abbreviation("Nat Med");

pub fn grant_number<S: Into<String>>(self, grant_number: S) -> Self

Filter by grant number

Arguments

• grant_number - Grant number to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .grant_number("R01AI123456");

pub fn isbn<S: Into<String>>(self, isbn: S) -> Self

Filter by ISBN

Arguments

• isbn - ISBN to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .isbn("978-0123456789");

pub fn issn<S: Into<String>>(self, issn: S) -> Self

Filter by ISSN

Arguments

• issn - ISSN to search for

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .issn("1234-5678");

pub fn free_full_text_only(self) -> Self

Filter to articles with free full text only

Includes PMC, Bookshelf, and publishers’ websites.

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("cancer")
    .free_full_text_only();

pub fn full_text_only(self) -> Self

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

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("machine learning")
    .full_text_only();

pub fn pmc_only(self) -> Self

Filter to articles with PMC full text only

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("diabetes")
    .pmc_only();

pub fn has_abstract(self) -> Self

Filter to articles with abstracts

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("genetics")
    .has_abstract();

pub fn article_types(self, types: &[ArticleType]) -> Self

Filter by article types

Arguments

• types - Article types to include

Example

use pubmed_client::pubmed::{SearchQuery, ArticleType};

let query = SearchQuery::new()
    .query("hypertension")
    .article_types(&[ArticleType::ClinicalTrial, ArticleType::Review]);

pub fn article_type(self, article_type: ArticleType) -> Self

Filter by a single article type (convenience method)

Arguments

• article_type - Article type to filter by

Example

use pubmed_client::pubmed::{SearchQuery, ArticleType};

let query = SearchQuery::new()
    .query("diabetes treatment")
    .article_type(ArticleType::ClinicalTrial);

pub fn language(self, language: Language) -> Self

Filter by language

Arguments

• language - Language to filter by

Example

use pubmed_client::pubmed::{SearchQuery, Language};

let query = SearchQuery::new()
    .query("stem cells")
    .language(Language::English);

impl SearchQuery

pub fn validate(&self) -> Result<()>

Validate the query structure and parameters

Returns

Returns an error if the query is invalid, Ok(()) otherwise

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new().query("covid-19");
assert!(query.validate().is_ok());

pub fn optimize(self) -> Self

Optimize the query for better performance

Returns

Returns an optimized version of the query

Example

use pubmed_client::pubmed::SearchQuery;

let optimized = SearchQuery::new()
    .query("covid-19")
    .published_after(2020)
    .optimize();

pub fn get_stats(&self) -> (usize, usize, usize)

Get query statistics and information

Returns

Returns a tuple of (term_count, filter_count, estimated_complexity)

Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new()
    .query("machine learning")
    .published_after(2020)
    .free_full_text_only();

let (terms, filters, complexity) = query.get_stats();

Trait Implementations

impl Clone for SearchQuery

fn clone(&self) -> SearchQuery

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SearchQuery

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SearchQuery

fn default() -> Self

Returns the “default value” for a type.