corpusQuery-KorAPConnection-method: Search corpus for query terms

corpusQuery,KorAPConnection-methodR Documentation

Search corpus for query terms

Description

corpusQuery performs a corpus query via a connection to a KorAP-API-server

Usage

## S4 method for signature 'KorAPConnection'
corpusQuery(
  kco,
  query = if (missing(KorAPUrl)) {
    
    stop("At least one of the parameters query and KorAPUrl must be specified.", call. =
    FALSE)
 } else {
     httr2::url_parse(KorAPUrl)$query$q
 },
  vc = if (missing(KorAPUrl)) "" else httr2::url_parse(KorAPUrl)$query$cq,
  KorAPUrl,
  metadataOnly = TRUE,
  ql = if (missing(KorAPUrl)) "poliqarp" else httr2::url_parse(KorAPUrl)$query$ql,
  fields = c("corpusSigle", "corpusTitle", "textSigle", "pubDate", "pubPlace",
    "availability", "textClass", "dmozDomain", "wikiDomain", "snippet", "tokens"),
  accessRewriteFatal = TRUE,
  verbose = kco@verbose,
  expand = length(vc) != length(query),
  as.df = FALSE,
  context = NULL
)

Arguments

kco

KorAPConnection() object (obtained e.g. from KorAPConnection())

query

string that contains the corpus query. The query language depends on the ql parameter. Either query must be provided or KorAPUrl.

vc

string describing the virtual corpus in which the query should be performed. An empty string (default) means the whole corpus, as far as it is license-wise accessible.

KorAPUrl

instead of providing the query and vc string parameters, you can also simply copy a KorAP query URL from your browser and use it here (and in KorAPConnection) to provide all necessary information for the query.

metadataOnly

logical that determines whether queries should return only metadata without any snippets. This can also be useful to prevent access rewrites. Note that the default value is TRUE. If you want your corpus queries to return not only metadata, but also KWICs, you need to authorize your RKorAPClient application as explained in the authorization section of the RKorAPClient Readme on GitHub and set the metadataOnly parameter to FALSE.

ql

string to choose the query language (see section on Query Parameters in the Kustvakt-Wiki for possible values).

fields

character vector specifying which metadata fields to retrieve for each match. Available fields depend on the corpus. For DeReKo (German Reference Corpus), possible fields include:

Text identification:

textSigle, docSigle, corpusSigle - hierarchical text identifiers

Publication info:

author, editor, title, docTitle, corpusTitle - authorship and titles

Temporal data:

pubDate, creationDate - when text was published/created

Publication details:

pubPlace, publisher, reference - where/how published

Text classification:

textClass, dmozDomain, wikiDomain, textType, textTypeArt, idsColumn - topic domain, genre, text type and column

Administrative and technical info:

corpusEditor, availability, language, foundries - access rights and annotations

Content data:

snippet, tokens, tokenSource, externalLink - actual text content, tokenization, and link to source text

System data:

indexCreationDate, indexLastModified - corpus indexing info

Current DeReKo releases use dmozDomain and wikiDomain for topic domains; textClass is retained in the default request for older corpus releases. Use c("textSigle", "pubDate", "author") to retrieve multiple fields. Default fields provide basic text identification and publication metadata. The actual text content fields (snippet and tokens) are activated by default if metadataOnly is set to FALSE.

accessRewriteFatal

abort if query or given vc had to be rewritten due to insufficient rights (not yet implemented).

verbose

print some info

expand

logical that decides if query and vc parameters are expanded to all of their combinations. Defaults to TRUE, iff query and vc have different lengths

as.df

return result as data frame instead of as S4 object?

context

string that specifies the size of the left and the right context returned in snippet (provided that metadataOnly is set to false and that the necessary access rights are met). The format of the context size specification (e.g. ⁠3-token,3-token⁠) is described in the Service: Search GET documentation of the Kustvakt Wiki. If the parameter is not set, the default context size specification of the KorAP server instance will be used. Note that you cannot overrule the maximum context size set in the KorAP server instance, as this is typically legally motivated.

Value

Depending on the as.df parameter, a tibble or a KorAPQuery() object that, among other information, contains the total number of results in ⁠@totalResults⁠. Multiple queries return a summary table. With as.df = FALSE, it also retains query states for fetchAll(), fetchNext(), fetchSamplePages() and dispersionAnalysis(). Names of the query vector label the comparison columns. With as.df = TRUE, only the summary is retained. A corresponding URL to be used within a web browser is contained in ⁠@webUIRequestUrl⁠ Please make sure to check ⁠$collection$rewrites⁠ to see if any unforeseen access rewrites of the query's virtual corpus had to be performed.

Slow queries

Complex queries can take minutes on large corpora, especially on DeLiKo@DNB (⁠https://korap.dnb.de⁠), or exceed the time limit of the server, which leaves the results incomplete. As long as KorAP does not offer sampling by itself, a workaround is to restrict vc to a pseudo-random sample of texts, selected by the last digit of their sigle: "textSigle = /.*5/" selects about a tenth, "textSigle = /.*[0-4]/" about half of the texts. Combine the sample with other conditions using &, e.g. "textType = /.*Krimi.*/ & textSigle = /.*5/". Relative frequencies, and association scores that do not depend on the corpus size, such as logDice, remain estimates for the whole (virtual) corpus, whereas absolute frequencies, and with them log-likelihood scores, shrink with the sample. A sample saves about as much time as it leaves out if the server has recently read the index of the query terms, e.g. for the same query on another virtual corpus, but hardly any time otherwise, when most of the time goes into reading the index from disk. It thus pays off in series of queries on the same terms, such as a frequencyQuery() over many years or a collocationAnalysis(). Repeating a query on the same vc takes no time anyway, as its result comes from the local cache (see the cache parameter of KorAPConnection()). Queries that are fast anyway do not get faster, because selecting the sample takes some time itself.

References

https://ids-pub.bsz-bw.de/frontdoor/index/index/docId/9026

See Also

KorAPConnection(), fetchNext(), fetchRest(), fetchAll(), corpusStats()

Other corpus search functions: fetchAll,KorAPQuery-method, fetchAnnotations,KorAPQuery-method, fetchNext,KorAPQuery-method

Examples

## Not run: 

# Fetch basic metadata for "Ameisenplage"
KorAPConnection() |>
  corpusQuery("Ameisenplage") |>
  fetchAll()

# Fetch specific metadata fields for bibliographic analysis
query <- KorAPConnection() |>
  corpusQuery("Ameisenplage",
              fields = c("textSigle", "author", "title", "pubDate", "pubPlace", "textType"))
results <- fetchAll(query)
results@collectedMatches

## End(Not run)

## Not run: 

# Use the copy of a KorAP-web-frontend URL for an API query of "Ameise" in a virtual corpus
# and show the number of query hits (but don't fetch them).

KorAPConnection(verbose = TRUE) |>
  corpusQuery(
    KorAPUrl =
      "https://korap.ids-mannheim.de/?q=Ameise&cq=pubDate+since+2017&ql=poliqarp"
  )

## End(Not run)

## Not run: 

# Plot the time/frequency curve of "Ameisenplage"
KorAPConnection(verbose = TRUE) |>
  {
    . ->> kco
  } |>
  corpusQuery("Ameisenplage") |>
  fetchAll() |>
  slot("collectedMatches") |>
  mutate(year = lubridate::year(pubDate)) |>
  dplyr::select(year) |>
  group_by(year) |>
  summarise(Count = dplyr::n()) |>
  mutate(Freq = mapply(function(f, y) {
    f / corpusStats(kco, paste("pubDate in", y))@tokens
  }, Count, year)) |>
  dplyr::select(-Count) |>
  complete(year = min(year):max(year), fill = list(Freq = 0)) |>
  plot(type = "l")

## End(Not run)

RKorAPClient documentation built on Nov. 12, 2026, 5:11 p.m.