workset_builder: Builds a Workset of Hathi Trust vol IDs by querying the...

In xmarquez/hathiTools: Access the Hathi Trust Bookworm and Extracted Features Files from R

Builds a Workset of Hathi Trust vol IDs by querying the Workset Builder 2.0

Description

Queries the SOLR endpoint of the Workset Builder 2.0 (beta) at https://solr2.htrc.illinois.edu/solr-ef20/. This API is experimental, and so this function can fail at any time if the API changes.

Usage

workset_builder(
  token,
  title,
  name,
  imprint,
  pub_date,
  lang = "eng",
  volumes_only = TRUE,
  token_join = c("AND", "OR"),
  max_vols = Inf,
  query_string,
  verbose = FALSE
)

Arguments

token	The tokens to search for in the Hathi Trust Extracted Features files. Can be a vector of characters, e.g., c("liberal", "democracy"); if a character vector with more than one element, the results are interpreted using the value of token_join – by default AND, so that the query will find all volumes where all the tokens appear, though not necessarily in the same page (in the example, all volumes containing both "liberal" and "democracy"). If token_join is "OR" then the query will find all volumes where either of the tokens appear. Search is case-insensitive; phrases can be included (e.g., "liberal democracy"), and the database will then return matches where both terms appear in the same page (though not necessarily next to each other).
title	Title field. Multiple words will be joined with "AND"; can be a phrase (e.g., "Democracy in America").
name	Names associated with the book (e.g., author). Multiple terms will be joined with "AND"; can be a phrase (e.g., "Alexis de Tocqueville").
imprint	Imprint information (e.g., publisher). Multiple terms will be joined with "AND"; can be a phrase (e.g., "University of Chicago Press").
pub_date	Publication date in Hathi Trust metadata. Can be a range, e.g., 1800:1900, or a set of years, e.g., c(1800, 1805).
lang	Language. Default is "eng" (English); a string like "English" or any 2 or 3 letter ISO639 code (available in the dataset iso639 included with this package) is allowed. (If no language code is found, the default is to search all languages; set to NULL if you want to search all languages). Right now this function can only search one language at a time; if you wish to search for terms in more than one language, create multiple worksets and bind them together.
volumes_only	If TRUE (the default), returns only volume IDs plus a count of the number of times the tokens appear in the volume; FALSE returns both volume and page IDs where the tokens are found. Note the page IDs are 0-based; when looking for the page at the Hathi Digital Library site, it's necessary to add 1. browse_htids does this automatically.
token_join	The logical connector for the tokens in token, if more than one. Default is "AND"; the query will ask for all volumes where all tokens occur. "OR" means the query will ask for all volumes where any of the tokens occur.
max_vols	Maximum number of volumes to return. Default is Inf, all volumes. Unfortunately the calculation is done locally, rather than remotely, so generally even if it is set at a small number, you'll still need to download all returned htids.
query_string	You can pass a query string directly - this is very useful for complex queries. For a guide to SOLR query syntax, see https://solr.apache.org/guide/6_6/the-standard-query-parser.html#the-standard-query-parser; for information about what fields are available see the Workset Builder page https://solr2.htrc.illinois.edu/solr-ef20/
verbose	Whether to display the query string used. Default is FALSE. This is useful to learn how to use the more complex SOLR query syntax.

Value

A tibble with volume_ids, number of occurrences of the terms in the volume, and if volumes_only is FALSE a column for page ids.

Examples

# All volumes that mention "tylenol" and "paracetamol", not necessarily in the same page
workset_builder(c("tylenol", "paracetamol"), volumes_only = FALSE)

# All volumes mentioning "demagogue" published between 1800 and 1900
workset_builder("demagogue", pub_date = 1800:1900)

# All volumes mentioning "demagogue" with "Tocqueville" and "Reeve"
# in the author field
workset_builder("demagogue", name = c("Tocqueville", "Reeve"))

# All volumes with "Tocqueville" in the author field
workset_builder(name = "Tocqueville")

xmarquez/hathiTools documentation built on June 2, 2025, 5:12 a.m.