com.google.cloud.bigquery

Class QueryJobConfiguration.Builder

java.lang.Object

com.google.cloud.bigquery.JobConfiguration.Builder<QueryJobConfiguration,QueryJobConfiguration.Builder>

com.google.cloud.bigquery.QueryJobConfiguration.Builder

Enclosing class:

QueryJobConfiguration

public static final class QueryJobConfiguration.Builder
extends JobConfiguration.Builder<QueryJobConfiguration,QueryJobConfiguration.Builder>

Method Summary

Modifier and Type	Method and Description
QueryJobConfiguration.Builder	addNamedParameter(String name, QueryParameterValue value) Adds a named query parameter to the set of query parameters.
QueryJobConfiguration.Builder	addPositionalParameter(QueryParameterValue value) Adds a positional query parameter to the list of query parameters.
QueryJobConfiguration.Builder	addTableDefinition(String tableName, ExternalTableDefinition tableDefinition) Adds a new external table definition.
QueryJobConfiguration	build() Creates an object.
QueryJobConfiguration.Builder	setAllowLargeResults(Boolean allowLargeResults) Sets whether the job is enabled to create arbitrarily large results.
QueryJobConfiguration.Builder	setClustering(Clustering clustering) Sets the clustering specification for the destination table.
QueryJobConfiguration.Builder	setConnectionProperties(List<ConnectionProperty> connectionProperties) A connection-level property to customize query behavior.
QueryJobConfiguration.Builder	setCreateDisposition(JobInfo.CreateDisposition createDisposition) Sets whether the job is allowed to create tables.
QueryJobConfiguration.Builder	setCreateSession(Boolean createSession) Sets whether to create a new session.
QueryJobConfiguration.Builder	setDefaultDataset(DatasetId defaultDataset) Sets the default dataset.
QueryJobConfiguration.Builder	setDefaultDataset(String defaultDataset) Sets the default dataset.
QueryJobConfiguration.Builder	setDestinationEncryptionConfiguration(EncryptionConfiguration encryptionConfiguration)
QueryJobConfiguration.Builder	setDestinationTable(TableId destinationTable) Sets the table where to put query results.
QueryJobConfiguration.Builder	setDryRun(Boolean dryRun) Sets whether the job has to be dry run or not.
QueryJobConfiguration.Builder	setFlattenResults(Boolean flattenResults) Sets whether nested and repeated fields should be flattened.
QueryJobConfiguration.Builder	setJobTimeoutMs(Long jobTimeoutMs) [Optional] Job timeout in milliseconds.
QueryJobConfiguration.Builder	setLabels(Map<String,String> labels) The labels associated with this job.
QueryJobConfiguration.Builder	setMaximumBillingTier(Integer maximumBillingTier) Limits the billing tier for this job.
QueryJobConfiguration.Builder	setMaximumBytesBilled(Long maximumBytesBilled) Limits the bytes billed for this job.
QueryJobConfiguration.Builder	setMaxResults(Long maxResults) This is only supported in the fast query path [Optional] The maximum number of rows of data to return per page of results.
QueryJobConfiguration.Builder	setNamedParameters(Map<String,QueryParameterValue> values) Sets the query parameters to a set of named query parameters to use in the query.
QueryJobConfiguration.Builder	setParameterMode(String parameterMode) Standard SQL only.
QueryJobConfiguration.Builder	setPositionalParameters(Iterable<QueryParameterValue> values) Sets the query parameters to a list of positional query parameters to use in the query.
QueryJobConfiguration.Builder	setPriority(QueryJobConfiguration.Priority priority) Sets a priority for the query.
QueryJobConfiguration.Builder	setQuery(String query) Sets the BigQuery SQL query to execute.
QueryJobConfiguration.Builder	setRangePartitioning(RangePartitioning rangePartitioning) Range partitioning specification for this table.
QueryJobConfiguration.Builder	setSchemaUpdateOptions(List<JobInfo.SchemaUpdateOption> schemaUpdateOptions) [Experimental] Sets options allowing the schema of the destination table to be updated as a side effect of the query job.
QueryJobConfiguration.Builder	setTableDefinitions(Map<String,ExternalTableDefinition> tableDefinitions) Sets the external tables definitions.
QueryJobConfiguration.Builder	setTimePartitioning(TimePartitioning timePartitioning) Sets the time partitioning specification for the destination table.
QueryJobConfiguration.Builder	setUseLegacySql(Boolean useLegacySql) Sets whether to use BigQuery's legacy SQL dialect for this query.
QueryJobConfiguration.Builder	setUseQueryCache(Boolean useQueryCache) Sets whether to look for the result in the query cache.
QueryJobConfiguration.Builder	setUserDefinedFunctions(List<UserDefinedFunction> userDefinedFunctions) Sets user defined function resources that can be used by this query.
QueryJobConfiguration.Builder	setWriteDisposition(JobInfo.WriteDisposition writeDisposition) Sets the action that should occur if the destination table already exists.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setQuery

public QueryJobConfiguration.Builder setQuery(String query)

Sets the BigQuery SQL query to execute.

addPositionalParameter

public QueryJobConfiguration.Builder addPositionalParameter(QueryParameterValue value)

Adds a positional query parameter to the list of query parameters. See setPositionalParameters(Iterable) for more details on the input requirements.

A positional parameter cannot be added after named parameters have been added.

setParameterMode

public QueryJobConfiguration.Builder setParameterMode(String parameterMode)

Standard SQL only. Set to POSITIONAL to use positional (?) query parameters or to NAMED to use named (@myparam) query parameters in this query.

setPositionalParameters

public QueryJobConfiguration.Builder setPositionalParameters(Iterable<QueryParameterValue> values)

Sets the query parameters to a list of positional query parameters to use in the query.

The set of query parameters must either be all positional or all named parameters. Positional parameters are denoted in the query with a question mark (?).

Additionally, useLegacySql must be set to false; query parameters cannot be used with legacy SQL.

The values parameter can be set to null to clear out the positional parameters so that named parameters can be used instead.

addNamedParameter

public QueryJobConfiguration.Builder addNamedParameter(String name,
                                                       QueryParameterValue value)

Adds a named query parameter to the set of query parameters. See setNamedParameters(Map) for more details on the input requirements.

A named parameter cannot be added after positional parameters have been added.

setNamedParameters

public QueryJobConfiguration.Builder setNamedParameters(Map<String,QueryParameterValue> values)

Sets the query parameters to a set of named query parameters to use in the query.

The set of query parameters must either be all positional or all named parameters. Named parameters are denoted using an @ prefix, e.g. @myParam for a parameter named "myParam".

Additionally, useLegacySql must be set to false; query parameters cannot be used with legacy SQL.

The values parameter can be set to null to clear out the named parameters so that positional parameters can be used instead.

setDestinationTable

public QueryJobConfiguration.Builder setDestinationTable(TableId destinationTable)

Sets the table where to put query results. If not provided a new table is created. This value is required if setAllowLargeResults(Boolean) is set to true.

setDestinationEncryptionConfiguration

public QueryJobConfiguration.Builder setDestinationEncryptionConfiguration(EncryptionConfiguration encryptionConfiguration)

setTableDefinitions

public QueryJobConfiguration.Builder setTableDefinitions(Map<String,ExternalTableDefinition> tableDefinitions)

Sets the external tables definitions. If querying external data sources outside of BigQuery, this value describes the data format, location and other properties of the data sources. By defining these properties, the data sources can be queried as if they were standard BigQuery tables.

addTableDefinition

public QueryJobConfiguration.Builder addTableDefinition(String tableName,
                                                        ExternalTableDefinition tableDefinition)

Adds a new external table definition. If a definition already exists for tableName it is updated.

Parameters:

tableName - name of the table

tableDefinition - external data configuration for the table used by this query

setUserDefinedFunctions

public QueryJobConfiguration.Builder setUserDefinedFunctions(List<UserDefinedFunction> userDefinedFunctions)

Sets user defined function resources that can be used by this query. Function resources can either be defined inline (UserDefinedFunction.inline(String)) or loaded from a Google Cloud Storage URI (UserDefinedFunction.fromUri(String).

setCreateDisposition

public QueryJobConfiguration.Builder setCreateDisposition(JobInfo.CreateDisposition createDisposition)

Sets whether the job is allowed to create tables.

See Also:

Create Disposition

setWriteDisposition

public QueryJobConfiguration.Builder setWriteDisposition(JobInfo.WriteDisposition writeDisposition)

Sets the action that should occur if the destination table already exists.

See Also:

Write Disposition

setDefaultDataset

public QueryJobConfiguration.Builder setDefaultDataset(DatasetId defaultDataset)

Sets the default dataset. This dataset is used for all unqualified table names used in the query.

setDefaultDataset

public QueryJobConfiguration.Builder setDefaultDataset(String defaultDataset)

Sets the default dataset. This dataset is used for all unqualified table names used in the query.

setPriority

public QueryJobConfiguration.Builder setPriority(QueryJobConfiguration.Priority priority)

Sets a priority for the query. If not specified the priority is assumed to be QueryJobConfiguration.Priority.INTERACTIVE.

setCreateSession

public QueryJobConfiguration.Builder setCreateSession(Boolean createSession)

Sets whether to create a new session. If true a random session id will be generated by BigQuery. If false, runs query with an existing session_id passed in ConnectionProperty, otherwise runs query in non-session mode."

setAllowLargeResults

public QueryJobConfiguration.Builder setAllowLargeResults(Boolean allowLargeResults)

Sets whether the job is enabled to create arbitrarily large results. If true the query is allowed to create large results at a slight cost in performance. If true setDestinationTable(TableId) must be provided.

See Also:

Returning Large Query Results

setUseQueryCache

public QueryJobConfiguration.Builder setUseQueryCache(Boolean useQueryCache)

Sets whether to look for the result in the query cache. The query cache is a best-effort cache that will be flushed whenever tables in the query are modified. Moreover, the query cache is only available when setDestinationTable(TableId) is not set.

See Also:

Query Caching

setFlattenResults

public QueryJobConfiguration.Builder setFlattenResults(Boolean flattenResults)

Sets whether nested and repeated fields should be flattened. If set to false setAllowLargeResults(Boolean) must be true. By default results are flattened.

See Also:

Flatten

setDryRun

public QueryJobConfiguration.Builder setDryRun(Boolean dryRun)

Sets whether the job has to be dry run or not. If set, the job is not executed. A valid query will return a mostly empty response with some processing statistics, while an invalid query will return the same error it would if it wasn't a dry run.

setUseLegacySql

public QueryJobConfiguration.Builder setUseLegacySql(Boolean useLegacySql)

Sets whether to use BigQuery's legacy SQL dialect for this query. By default this property is set to false. If set to false, the query will use BigQuery's Standard SQL. When set to false, the values of setAllowLargeResults(Boolean) and setFlattenResults(Boolean) are ignored; query will be run as if setAllowLargeResults(Boolean) is true and setFlattenResults(Boolean) is false.

If set to null or true, legacy SQL dialect is used. This property is experimental and might be subject to change.

setMaximumBillingTier

public QueryJobConfiguration.Builder setMaximumBillingTier(Integer maximumBillingTier)

Limits the billing tier for this job. Queries that have resource usage beyond this tier will fail (without incurring a charge). If unspecified, this will be set to your project default.

Parameters:

maximumBillingTier - maximum billing tier for this job

setMaximumBytesBilled

public QueryJobConfiguration.Builder setMaximumBytesBilled(Long maximumBytesBilled)

Limits the bytes billed for this job. Queries that will have bytes billed beyond this limit will fail (without incurring a charge). If unspecified, this will be set to your project default.

Parameters:

maximumBytesBilled - maximum bytes billed for this job

setSchemaUpdateOptions

public QueryJobConfiguration.Builder setSchemaUpdateOptions(List<JobInfo.SchemaUpdateOption> schemaUpdateOptions)

[Experimental] Sets options allowing the schema of the destination table to be updated as a side effect of the query job. Schema update options are supported in two cases: when writeDisposition is WRITE_APPEND; when writeDisposition is WRITE_TRUNCATE and the destination table is a partition of a table, specified by partition decorators. For normal tables, WRITE_TRUNCATE will always overwrite the schema.

setTimePartitioning

public QueryJobConfiguration.Builder setTimePartitioning(TimePartitioning timePartitioning)

Sets the time partitioning specification for the destination table.

setClustering

public QueryJobConfiguration.Builder setClustering(Clustering clustering)

Sets the clustering specification for the destination table.

setJobTimeoutMs

public QueryJobConfiguration.Builder setJobTimeoutMs(Long jobTimeoutMs)

[Optional] Job timeout in milliseconds. If this time limit is exceeded, BigQuery may attempt to terminate the job.

Parameters:

jobTimeoutMs - jobTimeoutMs or null for none

setLabels

public QueryJobConfiguration.Builder setLabels(Map<String,String> labels)

The labels associated with this job. You can use these to organize and group your jobs. Label keys and values can be no longer than 63 characters, can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter and each label in the list must have a different key.

Parameters:

labels - labels or null for none

setRangePartitioning

public QueryJobConfiguration.Builder setRangePartitioning(RangePartitioning rangePartitioning)

Range partitioning specification for this table. Only one of timePartitioning and rangePartitioning should be specified.

Parameters:

rangePartitioning - rangePartitioning or null for none

setConnectionProperties

public QueryJobConfiguration.Builder setConnectionProperties(List<ConnectionProperty> connectionProperties)

A connection-level property to customize query behavior. Under JDBC, these correspond directly to connection properties passed to the DriverManager. Under ODBC, these correspond to properties in the connection string. Currently, the only supported connection property is "time_zone", whose value represents the default timezone used to run the query. Additional properties are allowed, but ignored. Specifying multiple connection properties with the same key is an error.

Parameters:

connectionProperties - connectionProperties or null for none

setMaxResults

public QueryJobConfiguration.Builder setMaxResults(Long maxResults)

This is only supported in the fast query path [Optional] The maximum number of rows of data to return per page of results. Setting this flag to a small value such as 1000 and then paging through results might improve reliability when the query result set is large. In addition to this limit, responses are also limited to 10 MB. By default, there is no maximum row count, and only the byte limit applies.

Parameters:

maxResults - maxResults or null for none

build

public QueryJobConfiguration build()

Description copied from class: JobConfiguration.Builder

Creates an object.

Specified by:

build in class JobConfiguration.Builder<QueryJobConfiguration,QueryJobConfiguration.Builder>