Struct SearchQuery

Source

pub struct SearchQuery { /* private fields */ }

Expand description

Builder for constructing PubMed search queries

Implementations§

Source §

impl SearchQuery

Source

pub fn new() -> Self

Create a new search query builder

§Example

use pubmed_client::pubmed::SearchQuery;

let query = SearchQuery::new();

Source

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");

Source

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

Source

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

Source

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");

Source

pub fn get_limit(&self) -> usize

Get the limit for this query

Source

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

Source

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

Get the sort order for this query

Source

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(())
}

Source

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(())
}

Source

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(())
}

Source §

impl SearchQuery

Source

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");

Source

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");

Source

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

Source

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");

Source

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");

Source

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");

Source

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");

Source

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");

Source

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");

Source

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");

Source

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();

Source

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();

Source

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");

Source

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

Source §

impl SearchQuery

Source

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

Source

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

Source

pub fn negate(self) -> Self

Negate this query using NOT logic

§Example

use pubmed_client::pubmed::SearchQuery;

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

Source

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

Source

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();

Source §

impl SearchQuery

Source

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

Source

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

Source

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

Source

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

Source

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

Source

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

Source

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

Source §

impl SearchQuery

Source

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");

Source

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");

Source

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");

Source

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");

Source

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");

Source

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");

Source

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");

Source

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");

Source

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();

Source

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();

Source

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();

Source

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();

Source

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

Source

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

Source

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

Source §

impl SearchQuery

Source

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());

Source

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();

Source

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();