% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/retrieveClassificationTable.R
\name{retrieveClassificationTable}
\alias{retrieveClassificationTable}
\title{Retrieve a full classification table from CELLAR or FAO}
\usage{
retrieveClassificationTable(
  endpoint,
  prefix,
  conceptScheme,
  language = "en",
  level = "ALL",
  showQuery = FALSE,
  knownSchemes = NULL,
  preferMappingOnly = FALSE
)
}
\arguments{
\item{endpoint}{Character. Repository to query. Must be either "CELLAR" or "FAO".}

\item{prefix}{Character. Classification prefix used for matching and URI resolution
(e.g. "cn2022", "cpc21", "isic4").}

\item{conceptScheme}{Character. Local identifier of the scheme (often identical to
\code{prefix}). The function automatically resolves this to the canonical
ConceptScheme URI published in the endpoint.}

\item{language}{Character. Desired language for labels, scope notes and exclusion notes.
Default: "en".}

\item{level}{Character. One of:
\itemize{
  \item "ALL" (default): return all levels in the hierarchy;
  \item a specific depth value (e.g. "2") to filter concepts at that depth only.
}}

\item{showQuery}{Logical.
\itemize{
  \item FALSE (default): returns only the classification table;
  \item TRUE: returns a list containing the SPARQL query, the resolved scheme URI, and the table itself.
}}

\item{knownSchemes}{Optional. A data.frame supplying authoritative mappings of the
form \code{Prefix, ConceptScheme, URI[, Endpoint]}. When provided, this overrides
automatic discovery. To be obtained using \code{classificationList(endpoint)}.}

\item{preferMappingOnly}{Logical. If TRUE, the function never attempts SPARQL
discovery and uses only information in \code{knownSchemes} or \code{classificationList(endpoint)}.
Default: FALSE.}
}
\value{
If \code{showQuery = FALSE}, a \code{data.frame} with one row per concept and columns:
\itemize{
  \item \strong{Concept}: full concept URI;
  \item \strong{Code}: \code{skos:notation} coerced to string;
  \item \strong{Label}: preferred or alternative label in the requested language;
  \item \strong{Depth}: \code{xkos:depth} if available;
  \item \strong{BroaderList}: broader concept URIs (pipe-separated);
  \item \strong{BroaderCodeList}: broader concept notations (pipe-separated);
  \item \strong{IncludeNotes}: \code{skos:scopeNote} values (double-pipe-separated);
  \item \strong{ExcludeNotes}: \code{xkos:exclusionNote} values (double-pipe-separated).
}

If \code{showQuery = TRUE}, returns a list with:
\itemize{
  \item \code{SPARQL.query} – the executed SPARQL string;
  \item \code{scheme_uri} – the resolved ConceptScheme URI;
  \item \code{ClassificationTable} – the data.frame described above.
}
}
\description{
Retrieves the complete structure of a statistical classification published in
either CELLAR or FAO repositories based on a Prefix–ConceptScheme pair obtained
using \code{classificationList()}.

The resulting table is suitable for classification browsing, integrity checks,
hierarchical analysis, documentation, and downstream correspondence mapping.
}
\examples{
\dontrun{
# Retrieve full CN2022 classification (English)
cn <- retrieveClassificationTable(
  endpoint      = "CELLAR",
  prefix        = "cn2022",
  conceptScheme = "cn2022",
  language      = "en"
)

# Retrieve CPC v2.1 from FAO and inspect query
out <- retrieveClassificationTable(
  endpoint      = "FAO",
  prefix        = "cpc21",
  conceptScheme = "cpc21",
  showQuery     = TRUE
)
cat(out$SPARQL.query)
}

}
