Andrea Cosentino created CAMEL-24574:
----------------------------------------
Summary: camel-google-bigquery - clarify that ${name} is literal
substitution and steer value parameters to @name
Key: CAMEL-24574
URL: https://issues.apache.org/jira/browse/CAMEL-24574
Project: Camel
Issue Type: Improvement
Components: camel-google-bigquery
Reporter: Andrea Cosentino
Assignee: Andrea Cosentino
The google-bigquery-sql endpoint accepts two placeholder forms in its query
string, and they behave differently:
* ${name} is replaced by SqlHelper.translateQuery with the literal string
value of the matching message header or exchange property. The result is
spliced into the query text before the job is built.
* @name is collected by GoogleBigQuerySQLProducer.extractParameters and bound
through QueryParameterValue as a named query parameter.
The two forms exist because BigQuery named parameters can bind values but
cannot bind identifiers. ${name} therefore covers dataset and table names,
which is how the documented example uses it:
delete * from ${datasetId}.${tableId} where id=@myId
and how SqlHelperTest exercises it (${report} / ${import} for dataset names,
@date / @id for values).
The documentation does not convey this split. It says only:
parameters in form ${name} are extracted from message headers and formed
the translated query
That sentence is accurate but incomplete. It does not state that the
substitution is literal text rather than parameter binding, does not mention
the identifier intent, and gives no guidance that values should use @name.
A reader can reasonably conclude that ${name} is a binding mechanism, and use
it for values where @name is the correct form.
Proposed changes:
1. Documentation (components/camel-google/camel-google-bigquery/src/main/docs/
google-bigquery-sql-component.adoc)
- State that ${name} performs literal text substitution into the query.
- State that it is intended for dataset and table identifiers, and explain
that BigQuery named parameters cannot bind identifiers.
- State that @name is the correct form for any value, and that values
derived from message content should always use @name.
2. Optional runtime guard (SqlHelper.translateQuery)
- Validate ${name} substitutions against a BigQuery identifier shape, or
log a warning when a substituted value does not match one.
- This is a behaviour change for anyone currently using ${name} to carry
values. It should be evaluated separately from the documentation change
and, if adopted, recorded in the upgrade guide.
Affected classes:
* components/camel-google/camel-google-bigquery/src/main/java/org/apache/camel/
component/google/bigquery/sql/SqlHelper.java (translateQuery)
* components/camel-google/camel-google-bigquery/src/main/java/org/apache/camel/
component/google/bigquery/sql/GoogleBigQuerySQLProducer.java (process,
extractParameters, setQueryParameters)
* components/camel-google/camel-google-bigquery/src/main/docs/
google-bigquery-sql-component.adoc
The behaviour is unchanged since CAMEL-12930 and is identical on main,
camel-4.22.x and camel-4.18.x.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
