% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_perturbed_table_bigquery.R
\name{create_perturbed_table_bigquery}
\alias{create_perturbed_table_bigquery}
\title{Create a perturbed frequency table in BigQuery and return it as a data frame}
\usage{
create_perturbed_table_bigquery(
  con,
  data,
  ptable,
  geog,
  tab_vars,
  record_key,
  use_existing_ons_id = TRUE,
  threshold = 10,
  return_query = FALSE
)
}
\arguments{
\item{con}{--\code{DBIConnection}.
An active BigQuery connection created with \code{DBI::dbConnect()}}

\item{data}{--\code{character}.
BigQuery table name for microdata in full format:
\code{"<PROJECT>.<DATASET>.<TABLE>"}.
One row per statistical unit (person, household, business, etc.),
and one column per variable (e.g. age, sex, health status)}

\item{ptable}{--\code{character}.
BigQuery table name for the p-table in full format:
\code{"<PROJECT>.<DATASET>.<TABLE>"}.}

\item{geog}{--\verb{character vector}.
Column name containing the desired geography level for the frequency table.
e.g., \code{c("Region")} or \code{c("LocalAuthority")}.
Use \code{c()} if no geography breakdown required.}

\item{tab_vars}{--\verb{character vector}.
Column names to tabulate, e.g., \code{c("Age", "Health", "Occupation")}.}

\item{record_key}{--\code{character}.
Column name with record keys required for perturbation,
e.g., \code{"Record_Key"}.
If data contains "ons_id" and use_existing_ons_id = TRUE,
set (record_key = NULL), as record key will be generated from "ons_id".}

\item{use_existing_ons_id}{-- \code{logical}
Whether to create record keys from ons_id, if ons_id exists in data.
It will be irrelevant if microdata does not contain ons_id.
Default is TRUE.}

\item{threshold}{--\code{integer}.
Suppression threshold; perturbed counts below this value are suppressed.
Default 10.}

\item{return_query}{--\code{logical}.
If \code{TRUE}, returns the generated SQL query without executing it.
Default \code{FALSE}.}
}
\value{
\itemize{
\item When \code{return_query = FALSE}: a \code{data.table} containing the perturbed
frequency table, sorted by \code{geog} and \code{tab_vars}.
\item When \code{return_query = TRUE}: a character string containing the query.
}
}
\description{
This function runs the perturbation method fully in BigQuery (via SQL) and
only downloads the result, which allows handling large datasets efficiently.
}
\details{
Function workflow:
\enumerate{
\item Generate BigQuery SQL query to run perturbation on BigQuery
\item If return_query = TRUE, return the query text and exit:
otherwise, execute the rest
\item Validate inputs using BigQuery
\item Run perturbation using BigQuery
\item Convert perturbed table to data.table and sort
}

The query build by this function does the following when executed:
\itemize{
\item Computes counts and cell keys for each unique combination of geographic
and tabulation variables.
\item Includes zero-count cells by generating the full cartesian product of
variable combinations.
\item Calculates pcv by ensuring the rows of ptable 501-750 are reused for
cell values above 750.
\item Applies perturbation values from a perturbation table based on cell keys
and pseudo cell values (pcv).
\item Suppresses cells below a specified threshold by setting their perturbed
count to NULL.
}
}
\examples{
# --- Return query text without executing it ---
query <- create_perturbed_table_bigquery(
  con        = NULL,
  data       = "my-gcp-project.survey.microdata",
  ptable     = "my-gcp-project.sdc.ptable",
  geog       = c("Region"),
  tab_vars   = c("AgeGroup", "HealthStatus", "Occupation"),
  record_key = "Record_Key",
  threshold  = 10,
  return_query = TRUE
)
cat(query)

}
