= Google BigQuery Standard SQL Component
:doctitle: Google BigQuery Standard SQL
:shortname: google-bigquery-sql
:artifactid: camel-google-bigquery
:description: Access Google Cloud BigQuery service using SQL queries.
:since: 2.23
:supportlevel: Stable
:tabs-sync-option:
:component-header: Only producer is supported
//Manually maintained attributes
:group: Google
:camel-spring-boot-name: google-bigquery

*Since Camel {since}*

*{component-header}*

The Google BigQuery SQL component provides access
to https://cloud.google.com/bigquery/[Cloud BigQuery Infrastructure] via
the https://developers.google.com/apis-explorer/#p/bigquery/v2/bigquery.jobs.query[Google Client Services API].

The current implementation supports only standard SQL
https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax[DML queries].

Maven users will need to add the following dependency to their pom.xml
for this component:

[source,xml]
------------------------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-google-bigquery</artifactId>
    <!-- use the same version as your Camel core version -->
    <version>x.x.x</version>
</dependency>

------------------------------------------------------

[[GoogleBigQuery-AuthenticationConfiguration]]

== Authentication Configuration

Google BigQuery component authentication is targeted for use with the GCP Service Accounts.
For more information please refer to https://cloud.google.com/docs/authentication[Google Cloud Platform Auth Guide]

Google security credentials can be set explicitly by providing the path to the GCP credentials file location.

Or they are set implicitly, where the connection factory falls back on
https://developers.google.com/identity/protocols/application-default-credentials#howtheywork[Application Default Credentials].

When you have the **service account key** you can provide authentication credentials to your application code.
Google security credentials can be set through the component endpoint:

[source,java]
--------------------------------------------------------
String endpoint = "google-bigquery-sql://project-id:query?serviceAccountKey=/home/user/Downloads/my-key.json";
--------------------------------------------------------

You can also use the base64 encoded content of the authentication credentials file if you don't want to set a file system path.

[source,java]
--------------------------------------------------------
String endpoint = "google-bigquery-sql://project-id:query?serviceAccountKey=base64:<base64 encoded>";
--------------------------------------------------------

Or by setting the environment variable `GOOGLE_APPLICATION_CREDENTIALS` :

--------------------------------------------------------
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/my-key.json"
--------------------------------------------------------

== URI Format

--------------------------------------------------------
google-bigquery-sql://project-id:query?[options]
--------------------------------------------------------

Examples:
--------------------------------------------------------
google-bigquery-sql://project-17248459:delete * from test.table where id=@myId

google-bigquery-sql://project-17248459:delete * from ${datasetId}.${tableId} where id=@myId
--------------------------------------------------------
where

 * parameters in form $\{name} are extracted from message headers and formed the translated query.
 * parameters in form @name are extracted from body or message headers and sent to Google Bigquery. The `com.google.cloud.bigquery.StandardSQLTypeName` of the parameter is detected from the type of the parameter using `<T> QueryParameterValue<T>.of(T value, Class<T> type)`

You can externalize your SQL queries to files in the classpath or file system as shown:

--------------------------------------------------------
google-bigquery-sql://project-17248459::classpath:delete.sql
--------------------------------------------------------


// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
include::partial$component-endpoint-headers.adoc[]
// component options: END

== Producer Endpoints

Google BigQuery SQL endpoint expects the payload to be either empty or a map of query parameters.

== Query Types

The component supports both SELECT and DML (INSERT, UPDATE, DELETE) queries:

* **SELECT queries** - Return data based on configured `outputType` (SELECT_LIST or STREAM_LIST)
* **DML queries** - Return the number of affected rows as `Long`

== Output Types

The component supports two output types for SELECT queries, configured using the `outputType` parameter

=== SELECT_LIST (default)

Returns all query results as a `List<Map<String, Object>>` loaded into memory.

*Characteristics:*

* All rows from current page loaded into memory
* Message body: `List<Map<String, Object>>`
* Manual pagination via `pageSize` and `pageToken` parameters
* Sets `CamelGoogleBigQueryNextPageToken` header for next page
* Sets `CamelGoogleBigQueryJobId` header for continued pagination with same job
* Results can be accessed multiple times

=== STREAM_LIST

Returns an `Iterator<Map<String, Object>>` for memory-efficient streaming of large result sets. Rows are loaded lazily as the iterator is consumed.

*Characteristics:*

* Message body: `Iterator<Map<String, Object>>`
* Pagination handled automatically by BigQuery SDK using `pageSize` for internal page fetching
* Does NOT set `CamelGoogleBigQueryNextPageToken` or `CamelGoogleBigQueryJobId` headers
* Does NOT support manual `pageToken` control
* Memory-efficient - only current page in memory
* Iterator can only be consumed once

*Note:* The `.streaming()` modifier on Split EIP is required to prevent loading all rows into memory before splitting.

*When to use STREAM_LIST:*

* Result sets with millions of rows
* Memory-constrained environments
* One-time sequential processing of rows
* When using Split EIP in streaming mode

== Data Type Mapping

BigQuery result types are mapped to Java types:

[cols="1,1,3"]
|===
|BigQuery Type|Java Type|Notes

|INT64
|Long
|

|FLOAT64
|Double
|

|NUMERIC
|BigDecimal
|

|STRING
|String
|

|BOOL
|Boolean
|

|BYTES
|byte[]
|

|DATE
|String
|ISO 8601 format

|DATETIME
|String
|ISO 8601 format

|TIME
|String
|ISO 8601 format

|TIMESTAMP
|String
|ISO 8601 format with timezone

|STRUCT (RECORD)
|Map<String, Object>
|Recursively converted to nested maps

|ARRAY (REPEATED)
|List<Object>
|Elements recursively converted based on their type

|RANGE
|Map<String, Object>
|Map with range start and end values

|NULL
|null
|
|===


include::spring-boot:partial$starter.adoc[]
