GoogleSQL for BigQuery supports the following security functions.
Function list
| Name | Summary |
|---|---|
SECURE_CONTEXT
|
Returns the value of a request-scoped secure context parameter provided at query run time. |
SESSION_USER
|
Get the email address or principal identifier of the user that's running the query. |
SECURE_CONTEXT
SECURE_CONTEXT(key)
Description
Returns the value of a request-scoped secure context parameter provided at query
run time. You can use SECURE_CONTEXT in logical views to
dynamically filter and evaluate data based on context variables—such as user
attributes, department IDs, or tenant identifiers—passed in the query request
body, without creating separate static views for each attribute value.
Definitions
key: A constant, non-NULLSTRINGliteral or query parameter representing the name of the secure context parameter to retrieve.keyisn't coercible.
Details
Passing secure context in query requests: Pass secure context parameters in the
secureContextfield of the BigQueryjobs.queryrequest payload, or inconfiguration.query.secureContextforjobs.insert. For example, the followingjobs.querypayload passes two parameters:{ "query": "SELECT * FROM my_dataset.sales_view", "useLegacySql": false, "secureContext": { "secureParameterEntries": { "user_dept": "Sales", "user_region": "US" } } }To pass multiple values in a single parameter, serialize the values as a JSON array string or a delimited string, and parse them in the view by using
JSON_VALUE_ARRAYorSPLIT.Parameter and request limits:
- Parameter keys must be 1 to 127 characters long and match the regular
expression
^[a-zA-Z_][a-zA-Z0-9_]*$. The key should start with an ASCII letter or underscore, followed only by ASCII letters, digits, or underscores. - Each parameter value must be a
STRINGof up to 1 MiB (1,048,576 UTF-8 bytes). Non-string JSON values—such as numbers, booleans, arrays, objects, orNULL—are rejected. - A request can include up to 10,000 entries in
secureParameterEntries, and up to 10 MiB (10,485,760 UTF-8 bytes) combined across all parameter values. The request is subject to the overall 10 MB API request size limit.
- Parameter keys must be 1 to 127 characters long and match the regular
expression
Sessions: When you use multi-statement query sessions, you must supply secure context parameters when you create the session by specifying
createSession: true. After a session is created, subsequent queries in the same session automatically inherit the initial session context and can't modify or supply newsecureContextparameters.Job metadata, execution plans, and audit logs:
- BigQuery omits
secureContextentries from job metadata returned byjobs.get,jobs.list, andINFORMATION_SCHEMA.JOBS*views. - When a query evaluates
SECURE_CONTEXT, BigQuery clears execution plan stage details (statistics.query.queryPlan) from job statistics. - Omitting
secureContextfrom job metadata and clearing execution plan details provide defense in depth against leaking parameter values through job history and query plans, rather than preventing an untrusted logical view from readingsecureContext. - Parameter names and values are recorded in BigQuery Data Access
audit logs in the
secureContextValuesfield. They might be truncated if the log entry exceeds audit log size limits. If you pass sensitive attributes insecureContext, restrict access to Data Access audit logs by granting a predefined role such as Private Logs Viewer (roles/logging.privateLogViewer). For more information, see Control access to logs.
- BigQuery omits
Query caching: Queries that evaluate
SECURE_CONTEXTaren't cached, even whenuseQueryCacheis set totrue. For more information, see Use cached query results.Security and architecture best practices: Dynamic context parameterization with
SECURE_CONTEXTis intended for large-scale multi-tenant systems and dynamic, attribute-based access control where maintaining separate tables or datasets per tenant is impractical due to data scale.SECURE_CONTEXTevaluates parameters supplied in the API request payload rather than in SQL text, and session parameters remain immutable after creation. Allow only trusted applications or middle-tier services to setsecureContextparameters. The trusted application must authenticate the client and supply the verified context parameters on its behalf. Don't let untrusted end users, clients, or AI agents set or modify these parameters directly, because doing so lets them spoof context attributes and bypass the view's access controls.Any logical view that a query can access can call
SECURE_CONTEXTand return the resolved parameter values in query results—including views in other projects or datasets that the backend service account can read. When you run untrusted or AI-generated SQL, apply the following controls in addition toSECURE_CONTEXT:- Enforce view allowlists deterministically in middleware: Don't rely
on AI prompt instructions alone to restrict which views a query
references. Use parameterized query templates or a semantic layer, or
validate every referenced resource against an allowlist of
administrator-authored views before running the query by parsing the SQL
abstract syntax tree (AST) or inspecting
statistics.query.referencedLogicalViews(andstatistics.query.referencedTablesfor base tables) from a dry run. - Restrict cross-project access and view creation or updates: Enforce
a VPC Service Controls perimeter and IAM
Principal Access Boundary (PAB) policies to prevent the
backend service account from reading views in untrusted external
projects. Don't grant
bigquery.tables.createorbigquery.tables.updatepermissions to untrusted principals on any dataset that your backend service account can read. These permissions shouldn't be granted through custom roles or by using predefined roles such as BigQuery Data Editor (roles/bigquery.dataEditor).
For most multi-tenant architecture workloads, standardized table-level or dataset-level tenant isolation combined with IAM-based access control, Row-Level Security (RLS) policies, and Column-Level Security (CLS) remain Google's recommended best practices to ensure strict tenant isolation and prevent data leakage.
For more information about multi-tenant architectures and access control, see the following resources:
- Enforce view allowlists deterministically in middleware: Don't rely
on AI prompt instructions alone to restrict which views a query
references. Use parameterized query templates or a semantic layer, or
validate every referenced resource against an allowlist of
administrator-authored views before running the query by parsing the SQL
abstract syntax tree (AST) or inspecting
Limitations
- View and statement support:
SECURE_CONTEXTis only supported within logical view definitions. CallingSECURE_CONTEXTdirectly at the top level of an ad hoc query, within materialized views, within temporary session views, or within user-defined functions (UDFs) and table-valued functions (TVFs) returns an error.- Running
CREATE VIEWorALTER VIEWstatements whilesecureContextis set on the request or session returns an error. - Calling the
ERRORfunction in a query that evaluates aSECURE_CONTEXTview returns an error.
- Supported types: Values supplied in the secure context must be
STRINGvalues. - Error mode:
SECURE_CONTEXTdoesn't support theSAFE.prefix. CallingSAFE.SECURE_CONTEXT(key)returns an analysis error. - Missing parameter handling: If a query evaluates
SECURE_CONTEXT('my_param')andmy_paramisn't provided in the request's secure context, the query fails and returns an error. Side-channel exposure: A
SECURE_CONTEXTfilter is evaluated inside a view and isn't a hard isolation boundary. A caller that can submit arbitrary SQL against the view might infer the existence or values of rows that the filter excludes—through crafted expressions that fail on filtered-out rows, query statistics such as bytes processed, or query duration. Don't rely on a view filter alone to separate tenants when the SQL reaching the view is untrusted, such as SQL generated by an AI agent.For a comparison of the isolation strength of authorized views, row-level security, and separate tables, see the following resources:
Return type
STRING
Examples
The following example creates a logical view my_dataset.sales_view that
filters rows using the SECURE_CONTEXT function:
CREATE OR REPLACE VIEW my_dataset.sales_view AS
WITH
Orders AS (
SELECT 1001 AS order_id, 'Sales' AS department, 250.00 AS amount
UNION ALL
SELECT 1002 AS order_id, 'Engineering' AS department, 500.00 AS amount
UNION ALL
SELECT 1004 AS order_id, 'Sales' AS department, 430.50 AS amount
)
SELECT
order_id,
department,
amount
FROM Orders
WHERE department = SECURE_CONTEXT('user_dept');
The following example queries my_dataset.sales_view when the API request
payload contains
secureContext: {"secureParameterEntries": {"user_dept": "Sales"}}. The view
evaluates SECURE_CONTEXT('user_dept') as 'Sales':
SELECT * FROM my_dataset.sales_view;
/*----------+------------+--------+
| order_id | department | amount |
+----------+------------+--------+
| 1001 | Sales | 250.00 |
| 1004 | Sales | 430.50 |
+----------+------------+--------*/
The following example filters rows against multiple allowed values by passing
"[\"US\", \"EU\"]" for allowed_regions in
secureContext.secureParameterEntries. The query parses the regions in the
view by using the JSON_VALUE_ARRAY function:
CREATE OR REPLACE VIEW my_dataset.regional_sales_view AS
WITH
RegionalOrders AS (
SELECT 1001 AS order_id, 'US' AS region, 250.00 AS amount
UNION ALL
SELECT 1002 AS order_id, 'APAC' AS region, 500.00 AS amount
UNION ALL
SELECT 1003 AS order_id, 'EU' AS region, 310.00 AS amount
)
SELECT
order_id,
region,
amount
FROM RegionalOrders
WHERE region IN UNNEST(JSON_VALUE_ARRAY(SECURE_CONTEXT('allowed_regions')));
SELECT * FROM my_dataset.regional_sales_view;
/*----------+--------+--------+
| order_id | region | amount |
+----------+--------+--------+
| 1001 | US | 250.00 |
| 1003 | EU | 310.00 |
+----------+--------+--------*/
SESSION_USER
SESSION_USER()
Description
For first-party users, returns the email address of the user that's running the query. For third-party users, returns the principal identifier of the user that's running the query. For more information about identities, see Principals.
Return Data Type
STRING
Example
SELECT SESSION_USER() as user;
/*----------------------+
| user |
+----------------------+
| jdoe@example.com |
+----------------------*/