esearch

The esearch command uses the ESearch utility to search an NCBI database for a query and finds the unique identifiers (UIDs; in the case of a PubMed search, PMIDs) for all records that match the search query.

Input

A search string, such as you would put into the web version of PubMed.

Output

A snippet of XML that includes a count of the number of records that match the search query, e.g.:

<ENTREZ_DIRECT>
    <Db>pubmed</Db>
    <WebEnv>NCID_1_1079563_130.14.18.34_9001_1472819698_1672866789_0MetA0_S_MegaStore_F_1</WebEnv>
    <QueryKey>1</QueryKey>
    <Count>1273159</Count> 
    <Step>1</Step>
</ENTREZ_DIRECT>

In addition, esearch outputs the UIDs for the records that match the search query, and stores them on the History server, using the WebEnv and Query Key specified in the XML snippet.

Arguments

The esearch command allows the following arguments:

• -db: The database you wish to search.
  • Example: -db pubmed
• -query: Your search string, enclosed in double quotes. Note: if your search string includes quotation marks, you will need to “escape” these quotes by prefacing them with a backslash (“\”) character. This tells EDirect to interpret the quotation marks as just another character, and not a special character that marks the end of the -query argument. Otherwise, EDirect would interpret the first set of double quotation marks in your search string as marking the end of the query, and the rest of the string would not be searched.
  • Example: -query "breast cancer AND 2016[pdat]"
  • Example: -query "smith bh[author] AND \"science\"[journal]" (demonstrates “escaping” quotes with “\”)
• -sort: Specifies the order in which your results will be sorted. The name of the sort order should be enclosed in double quotes (see examples below). Each database has different available sort orders.
  • For PubMed, the valid sort orders are:
    • First Author
    • Journal
    • Last Author
    • Pub Date
    • Recently Added
    • Relevance
    • Title
  • Example: -sort "First Author"
  • Example: -sort "Relevance"
• -datetype: When limiting results by date, this specifies which of the several date fields on a record is used to limit. This argument should be used with the -days argument, or with -mindate and -maxdate. Available date types vary by database.
  • For PubMed, valid datetype values include:
    • CRDT: Create Date (For records added after December 18, 2008, this is the date the citation was first added to PubMed. For more details, see the entry for “Create Date” in MEDLINE/PubMed Data Element (Field) Descriptions.)
    • EDAT: Entrez Date (For records added after October 9, 2008, this is the date the citation was added to PubMed, except for records added more than twelve months after the date of publication. For more details, see the entry for “Entrez Date” in MEDLINE/PubMed Data Element (Field) Descriptions.)
    • PDAT: Publication Date (The article’s publication date.)
    • MHDA: MeSH Date (The date the citation was indexed with MeSH. If the citation has not yet been indexed, this will be the same as the Entrez Date.)
  • Example: -datetype PDAT
  • Note: You can also impose a date restriction on your search within your -query, just as you would when searching the web version of PubMed. For more information on searching PubMed by date, see PubMed Help: Searching by date.
• -days: Limits results to records with dates no more than the specified number of days in the past, based on the date field specified in the -datetype argument.
  • Example: -datetype EDAT -days 5 (limits results to records added to the database in the last 5 days)
• -mindate/-maxdate: Limits results to records with dates in a certain range, based on the date field specified in the -datetype argument. To specify a date range, you must provide both a -mindate and a -maxdate argument, as well as a -datetype argument.
  • Example: -datetype PDAT -mindate 1990 -maxdate 2000 (limits results to articles published between 1990 and 2000, inclusive)
• -spell: Corrects misspellings in your search query.
  • Example: -query "neploasms" -spell (corrects the spelling of “neploasms” to “neoplasms”)
• -log: In addition to the default XML snippet output, also shows the full E-utilities URL and the full query translation (like you would find in the “Search details” box on the web version of PubMed).
  • Example: esearch -db pubmed -query "heart attack" -log

Examples:

Search PubMed for “seasonal affective disorder”:

esearch -db pubmed -query "seasonal affective disorder"

Search PubMed for articles on cancer in the journal “Science”, published between 2014 and 2016:

esearch -db pubmed -query "cancer AND \"science\"[journal]" -datetype PDAT -mindate 2014 -maxdate 2016

Search PubMed for articles on diabetes and pregnancy, and sort results by relevance:

esearch -db pubmed -query "diabetes AND pregnancy" -sort "Relevance"

Search PubMed for “heart attack” and see the query translation:

esearch -db pubmed -query "heart attack" -log