% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/statcan_find.R
\name{statcan_find}
\alias{statcan_find}
\title{Find Statistics Canada tables using a natural-language query}
\usage{
statcan_find(query, lang = c("eng", "fra"), n = 5L, refresh = FALSE)
}
\arguments{
\item{query}{One non-empty character string describing the desired data.}

\item{lang}{Language of the table titles: \code{"eng"} or \code{"fra"}.}

\item{n}{Maximum number of candidates to return, from 1 to 20.}

\item{refresh}{Logical; if \code{TRUE}, request a fresh catalogue and fresh
candidate metadata from WDS.}
}
\value{
A data frame of ranked candidates. \code{id} contains the table number,
\code{score} is the relevance score, and \code{match_reason} explains the ranking.
Coverage dates describe the table as a whole. \code{geography_match} is \code{TRUE}
when WDS metadata confirms every geography in the query, \code{FALSE} when it
does not, and \code{NA} when no geography was requested or validation was not
possible.
}
\description{
Interprets a short description of the data needed and returns ranked
Statistics Canada table candidates. The query can contain a topic, Canadian
geography, and reference year or range. For example,
\code{"R&D expenditures in Quebec since 2020"} is interpreted as a research and
development expenditure topic, a Quebec geography constraint, and coverage
beginning in 2020.
}
\details{
This function finds tables; it does not download or filter their
observations. Use the returned \code{id} with \code{\link[=statcan_data]{statcan_data()}}, then apply any
required geography and date filters to the downloaded data. Rankings are a
discovery aid, so review the candidate title before downloading a large
table.

The catalogue is cached for 24 hours. When a geography is present in the
query, metadata for a small set of leading candidates is retrieved through
WDS to confirm that the geography is a table member. That metadata is cached
for seven days. If metadata is temporarily unavailable, candidates can
still be returned with \code{geography_match = NA}.
}
\examples{
\dontrun{
matches <- statcan_find(
  "R&D expenditures in Quebec since 2020",
  lang = "eng"
)
matches[, c("title", "id", "match_reason")]
}
}
