Transformar conversões de SQL com YAML
Os arquivos YAML de configuração permitem personalizar como o BigQuery traduz o código SQL
do banco de dados de origem durante uma migração. O serviço de migração do BigQuery
aceita dois tipos de arquivos YAML de configuração: arquivos de configuração de tradução
*.config.yaml, que fornecem regras determinísticas ao mecanismo de tradução, e
arquivos de configuração baseados no Gemini *.ai_config.yaml, que fornecem
regras de linguagem natural ao Gemini.
Para personalizar uma tradução de SQL com arquivos YAML de configuração, faça o seguinte:
- Criar arquivos de configuração: crie arquivos de configuração de tradução determinísticos do
*.config.yaml, arquivos de configuração baseados no Gemini do*.ai_config.yamlou ambos os tipos de arquivos de configuração para combinar regras estruturais com a personalização do Gemini. - Forneça os arquivos para um job de tradução: envie os arquivos de configuração ao traduzir uma única consulta ou arquivos SQL em lote.
- Revise os resultados da tradução: encontre o SQL traduzido e as sugestões do Gemini na resposta ao traduzir uma única consulta ou no Cloud Storage ao traduzir arquivos SQL em lote.
Tipos de arquivos YAML de configuração
A tabela a seguir compara os dois tipos de arquivos YAML de configuração:
| Recurso | Configuração de tradução
(*.config.yaml) |
Configuração baseada no Gemini
(*.ai_config.yaml) |
|---|---|---|
| Como as regras são aplicadas | As regras são aplicadas pelo mecanismo de tradução como regras determinísticas no SQL analisado. Assim, a mesma entrada e configuração sempre produzem o mesmo resultado. | As regras são aplicadas pelo Gemini como instruções em linguagem natural e exemplos aplicados ao texto SQL. As saídas podem variar entre as execuções. Por isso, sempre revise e verifique as sugestões antes de usá-las. |
| O que pode ser transformado | O mecanismo de tradução pode transformar todos os objetos ou configurações que
reconhece. Isso inclui nomes e tipos de banco de dados, esquema, tabela, coluna e função, propriedades de tabela, como particionamento, clustering e expiração, padrões de sessão, assinaturas de UDF, otimizações e saída de instrução, como estilo GROUP BY e SELECT *. |
O Gemini pode mudar qualquer transformação de SQL que você possa descrever em linguagem natural. Isso inclui formatação e comentários, substituição de padrões, reescrita de construções que o mecanismo não traduz da maneira que você quer e geração de uma explicação da tradução. |
| Requisitos |
|
|
| Onde o resultado aparece | O resultado aparece no próprio SQL traduzido, como na resposta da tradução ou no diretório de saída sql/ no Cloud Storage. |
O resultado aparece como sugestões separadas do Gemini no
console do Google Cloud , em campos de sugestão ou arquivos de saída separados na
Google Cloud CLI e no servidor MCP ou em diretórios de saída
*_suggestion/ separados no Cloud Storage.
Para mais informações, consulte
Onde encontrar resultados de tradução. |
| Filename | Os nomes de arquivo precisam terminar com .config.yaml, por exemplo,
rename-tables.config.yaml. |
Os nomes de arquivo precisam terminar com .ai_config.yaml, por
exemplo, style-rules.ai_config.yaml. |
O serviço de tradução ignora qualquer arquivo YAML na
entrada que não termine com .config.yaml ou
.ai_config.yaml e informa o arquivo ignorado no
registro de tradução. |
||
| Referência | Para mais informações, consulte Diretrizes para criar um arquivo YAML de configuração e Exemplos de YAML de configuração nesta página. | Para mais informações, consulte Criar um arquivo YAML de configuração baseado no Gemini nesta página. |
Como os dois tipos de regras são aplicados
Um job de tradução aplica regras de configuração na seguinte ordem:
- O Gemini aplica regras
SOURCE_SQLem arquivos*.ai_config.yamlao SQL de entrada original para produzir o SQL de origem reescrito. - O mecanismo de tradução traduz o SQL de origem reescrito da etapa anterior ou o SQL de entrada original, se nenhuma regra
SOURCE_SQLse aplicar, e aplica as regras nos arquivos*.config.yamlpara produzir o SQL traduzido. - O Gemini aplica as regras de
TARGET_SQLnos arquivos*.ai_config.yamlao SQL traduzido da etapa anterior para produzir o SQL de destino reescrito. Se os arquivos*.ai_config.yamlincluírem regrasTRANSLATION_EXPLANATION, o Gemini também vai gerar uma explicação em texto do SQL traduzido.
Recomendamos o uso de regras *.config.yaml para mudanças estruturais repetíveis, como renomear objetos, mapear tipos e definir particionamento. Recomendamos
que você use regras *.ai_config.yaml para mudanças que o mecanismo
não pode expressar ou para limpar entradas que não são analisadas. É possível usar os dois tipos de arquivos de configuração no mesmo job.
Fornecer arquivos de configuração para uma tradução
O console do Google Cloud , a CLI gcloud, a API BigQuery Migration e o servidor MCP do serviço de migração do BigQuery aceitam o uso de vários arquivos de configuração em um único job de tradução. Para mais informações, consulte Como aplicar várias configurações YAML.
Para fornecer arquivos de configuração a um job de tradução, selecione uma das seguintes opções:
Console
- Para usar arquivos de configuração ao traduzir uma única consulta, especifique-os
nas configurações de tradução do tradutor interativo:
*.config.yaml: no campo Local de origem da configuração de tradução nas configurações de tradução, especifique um caminho do Cloud Storage para o arquivo de configuração.*.ai_config.yaml: crie regras de personalização, que são salvas em__default.ai_config.yaml, ou especifique um caminho do Cloud Storage.
- Para usar arquivos de configuração ao traduzir arquivos SQL em lote, faça o
seguinte:
*.config.yaml: faça upload dos arquivos de configuração no diretório de entrada do Cloud Storage e, nas configurações de tradução, especifique um caminho para o diretório no campo Detalhes do local do arquivo.*.ai_config.yaml: faça upload dos arquivos de configuração no diretório de entrada do Cloud Storage. Em seguida, nas configurações de tradução, selecione Configurações opcionais > Sugestões da IA do Gemini.
gcloud
- Ao usar o
comando
gcloud alpha bq migration translate, use a flag--translation-config-filespara especificar arquivos*.config.yamlou*.ai_config.yaml. - Ao usar o
comando
gcloud alpha bq migration translate-batch, siga um destes procedimentos:*.config.yaml: inclua os arquivos no diretório de entrada que você passa para--source-gcs-urisou--source-local-dirsou transmita arquivos individuais com a flag--source-gcs-filesou--source-local-files.*.ai_config.yaml: inclua os arquivos no diretório de entrada que você passa para--source-gcs-urisou--source-local-dirsou transmita arquivos individuais com a flag--source-gcs-filesou--source-local-filese adicione a flag--enable-ai-suggestion.
API
Na API BigQuery Migration, seja para traduzir uma única consulta ou arquivos SQL em lote, faça o seguinte:
*.config.yaml: faça upload dos arquivos no caminho de entrada emsource_spec.base_uri, transmita uma entradagcs_file_pathemsource_specquando o arquivo não estiver embase_uriou transmita uma entradaliteralinline emsource_spec.*.ai_config.yaml: forneça os arquivos emsource_specembase_uri, como uma entradagcs_file_pathquando o arquivo não estiver embase_uriou como uma entradaliteralinline, e inclua"suggestion"emtarget_types, por exemplo,"target_types": ["sql", "suggestion"].
MCP
No servidor MCP do serviço de migração do BigQuery:
- Para traduzir uma única consulta (
translate_query), faça o seguinte:*.config.yaml: transmite entradastranslationConfigsinline.*.ai_config.yaml: transmite entradasaiSuggestionConfigsinline.
- Para traduzir arquivos SQL em lote (
translate_batch_queries), faça o seguinte:*.config.yaml: faça upload dos arquivos emsourceBaseUriou liste-os emconfigurationFilePathsquando eles não estiverem emsourceBaseUri.*.ai_config.yaml: faça upload dos arquivos emsourceBaseUriou liste-os emconfigurationFilePathsquando eles não estiverem emsourceBaseUrie definaenableAiSuggestionscomotrue.
Onde encontrar as saídas de tradução
Dependendo dos arquivos de configuração fornecidos, um job de tradução pode produzir as seguintes saídas:
- SQL traduzido do mecanismo de tradução depois de aplicar as regras nos arquivos
*.config.yaml. - SQL de origem reescrito do Gemini depois de aplicar as regras
SOURCE_SQLnos arquivos*.ai_config.yaml. - SQL de destino reescrito do Gemini depois de aplicar as regras
TARGET_SQLnos arquivos*.ai_config.yaml. - Uma explicação de tradução do Gemini quando os
arquivos
*.ai_config.yamlincluem regrasTRANSLATION_EXPLANATIONou quando você solicita uma explicação sob demanda.
O local onde você encontra essas saídas depende de como a tradução é executada:
- Para encontrar saídas ao traduzir uma única consulta no console doGoogle Cloud ou na CLI gcloud, consulte Analisar a saída da tradução no guia do tradutor SQL interativo.
- Para encontrar saídas ao traduzir arquivos SQL em lote no Cloud Storage ou analisá-los no console do Google Cloud , consulte Analisar a saída da tradução no guia do tradutor de SQL em lote.
- Para encontrar saídas ao usar a API BigQuery Migration, consulte
Recuperar resultados no
guia da API BigQuery Migration. Para traduções de consulta única, adicione os
caminhos de saída que você quer (
sql/<var>PATH</var>,source_sql_query_customization_suggestion/<var>PATH</var>,target_sql_query_customization_suggestion/<var>PATH</var>outranslation_explanation_suggestion/<var>PATH</var>) atarget_return_literalspara recebê-los emtranslatedLiterals. - Para encontrar saídas ao usar o servidor MCP do serviço de migração do BigQuery, consulte
Usar o servidor MCP do serviço de migração do BigQuery. As ferramentas
translate_queryeget_translationretornamtranslatedQuery,sourceSqlSuggestionetargetSqlSuggestion, e a ferramentaexplain_translationretorna uma explicação da tradução.
Requisitos do arquivo de tradução *.config.yaml
Um arquivo de tradução *.config.yaml precisa atender aos seguintes requisitos para ser
compatível com o serviço de migração do BigQuery:
- Quando você faz upload de arquivos
*.config.yamlno caminho de entrada do Cloud Storage para um job de tradução em lote, os arquivos de configuração colocados em qualquer lugar no caminho de entrada se aplicam a todo o job. Eles não precisam estar no nível raiz ou ser copiados para cada subdiretório. Para informações sobre como criar buckets e fazer upload de arquivos no Cloud Storage, consulte Criar buckets e Fazer upload de objetos de um sistema de arquivos. - O tamanho de um único arquivo
*.config.yamlnão pode exceder 1 MB. - O tamanho total de todos os arquivos
*.config.yamlusados em um único job de tradução de SQL não pode exceder 4 MB. - Se você estiver usando a sintaxe
regexpara a correspondência de nomes, use RE2/J. - Todos os nomes arquivo de configuração de tradução precisam terminar com
.config.yaml, por exemplo,change-case.config.yaml.config.yamlnão é um nome válido para o arquivo de configuração.
Diretrizes para criar um arquivo YAML de configuração
Nesta seção, apresentamos algumas diretrizes gerais para criar um arquivo YAML de configuração:
Cabeçalho
Cada arquivo *.config.yaml precisa incluir um cabeçalho type de nível superior que
especifique a categoria de regras de configuração no arquivo:
object_rewriter: reescreve as propriedadesrelation, comotemporary,ephemeral,partitionLifetime,external,description,partitioneclustering, e os tipos de dadosattribute(type).experimental_object_rewriter: reescreve nomes de objetos de saída comoutputNameemglobal,database,schema,relation,attribute,function,index,sequence,variableeprojection, e converte tipos de dados globalmente comglobal.typeConvert. Para mais informações, consulte Mapeamento de nomes de saída e Conversão de tipo global.environment: define os padrões no nível da sessão emsession, comodefaultDatabase,schemaSearchPathedateFormat.metadata: declara assinaturas de função definida pelo usuário (UDF) (udfs) e remove prefixos, sufixos ou padrões de expressão regular do nome de entrada durante a pesquisa de metadados (nameAlias).statement_rewriter: personaliza a saída da instrução, como a expansão deSELECT *, a formatação deGROUP BYeORDER BY(select) e o rigor de precisão decimal ou de string (common).input_formats: especifica a codificação de caracteres dos arquivos SQL de entrada (formats).optimizer: ativa, desativa ou configura otimizações de consulta opcionais (transformations).
O exemplo a seguir usa o tipo experimental_object_rewriter para converter todos os nomes de objetos de saída em letras maiúsculas:
type: experimental_object_rewriter
global:
outputName:
all:
case: UPPERCASE
Seleção de entidade
Para realizar transformações específicas de entidade, especifique a entidade SQL de origem no arquivo de configuração. Todas as propriedades match são opcionais. Use apenas as propriedades match necessárias para uma transformação. O campo match é comparado
com os nomes dos objetos de origem depois de resolver qualquer defaultDatabase
e schemaSearchPath configurados, exceto em regras outputName quando global.outputName
também está configurado. Para mais informações, consulte
Mapeamento de nomes de saída. O YAML de configuração a seguir expõe properties a serem correspondidas para a seleção de entidades específicas:
match:
database: <literal_name>
schema: <literal_name>
relation: <literal_name>
attribute: <literal_name>
databaseRegex: <regex>
schemaRegex: <regex>
relationRegex: <regex>
attributeRegex: <regex>
Descrição de cada property match:
databaseoudb: corresponde ao nome do banco de dados de origem, que corresponde ao componenteproject_idno BigQuery.schema: corresponde ao nome do esquema de origem, que corresponde ao componentedatasetno BigQuery.relation: corresponde ao nome da tabela ou visualização de origem.attribute: corresponde ao nome da coluna de origem. Essa propriedade é válida apenas para a seleção deattribute.databaseRegexoudbRegex: faz a correspondência de todo o nome dedatabasecom uma expressão regular que não diferencia maiúsculas de minúsculas.schemaRegex: corresponde ao nome inteiro deschemacom uma expressão regular que não diferencia maiúsculas de minúsculas.relationRegex: corresponde ao nome inteiro derelationcom uma expressão regular que não diferencia maiúsculas de minúsculas.attributeRegex: corresponde ao nome inteiro deattributecom uma expressão regular que não diferencia maiúsculas de minúsculas. Essa propriedade é válida apenas para a seleção deattribute.
Por exemplo, o YAML de configuração a seguir especifica as properties match para selecionar a tabela testdb.acme.employee para uma transformação de tabela temporária.
type: object_rewriter
relation:
-
match:
database: testdb
schema: acme
relation: employee
temporary: true
É possível usar as propriedades databaseRegex, schemaRegex, relationRegex e attributeRegex para especificar expressões regulares a fim de selecionar um subconjunto de entidades. O exemplo a seguir altera todas as relações do esquema tmp_schema em testdb para temporário, desde que o nome comece com tmp_:
type: object_rewriter
relation:
-
match:
schema: tmp_schema
relationRegex: "tmp_.*"
temporary: true
As properties regex e o literal são correspondidos de uma maneira que não diferencia maiúsculas de minúsculas.
É possível aplicar a correspondência que diferencia maiúsculas de minúsculas usando um regex com uma flag i desativada, como mostrado no exemplo a seguir:
match:
relationRegex: "(?-i:<actual_regex>)"
Também é possível especificar entidades totalmente qualificadas usando uma sintaxe de string curta equivalente. Uma sintaxe de string curta espera exatamente três segmentos de nome (para seleção de relação) ou quatro (para seleção de atributo) delimitados por pontos, como no exemplo testdb.acme.employee. Os segmentos são interpretados internamente como se fossem transmitidos como database, schema, relation e attribute, respectivamente.
Isso significa que os nomes são correspondidos literalmente. Portanto, expressões regulares não são permitidas em sintaxe curta. O exemplo a seguir mostra o uso de sintaxe de string curta para especificar uma entidade totalmente qualificada em um arquivo YAML de configuração:
type: object_rewriter
relation:
-
match: "testdb.acme.employee"
temporary: true
Se uma tabela tiver um ponto no nome, não será possível especificar o nome usando uma sintaxe curta. Nesse caso, é preciso usar uma correspondência de objeto. O exemplo a seguir altera a tabela testdb.acme.stg.employee para temporária:
type: object_rewriter
relation:
-
match:
database: testdb
schema: acme
relation: stg.employee
temporary: true
Um arquivo YAML de configuração também aceita key como alias para match. Tanto
key quanto match são compatíveis com subcampos explícitos de componentes de nome, bem como com a sintaxe de string curta
"database.schema.relation" ou
"database.schema.relation.attribute" delimitada por pontos. Por convenção, key
costuma ser usado com a sintaxe de string curta, e match é usado com subcampos
explícitos.
Banco de dados padrão
Alguns dialetos SQL de entrada, principalmente o Teradata, não são compatíveis com um nome de banco de dados em identificadores qualificados (schema.table). Nesse caso, use um objeto match e omita a propriedade database. Como alternativa, configure
defaultDatabase, por exemplo, em type: environment, para que
seja possível fazer a correspondência com esse banco de dados padrão em regras de objeto ou de string curta
match.
Tipos de atributo de destino compatíveis
É possível usar o arquivo YAML de configuração para realizar transformações de tipo de atributo, em que você transforma o tipo de dados de uma coluna do tipo de origem para um tipo de destino. O arquivo YAML de configuração é compatível com os seguintes tipos de destino:
BOOLEANTINYINTSMALLINTINTEGERBIGINTFLOATDOUBLENUMERIC(compatível com precisão e escala opcionais, comoNUMERIC(18, 2))TIMETIMETZDATEDATETIMETIMESTAMPTIMESTAMPTZCHAR(compatível com precisão opcional, comoCHAR(42))VARCHAR(compatível com precisão opcional, comoVARCHAR(42))
Exemplos de YAML de configuração
Nesta seção, apresentamos exemplos para criar vários arquivos YAML de configuração para usar com as traduções de SQL. Cada exemplo descreve a sintaxe YAML para transformar a tradução de SQL de maneiras específicas, com uma breve descrição.
Cada exemplo também apresenta o conteúdo de um arquivo teradata-input.sql ou hive-input.sql e um arquivo bq-output.sql para você comparar os efeitos de um YAML de configuração em uma tradução de consulta SQL do BigQuery.
Os exemplos a seguir usam o Teradata ou o Apache Hive como o dialeto SQL de entrada e o SQL do BigQuery como o dialeto de saída.
Alterar caixa do nome do objeto
O YAML de configuração a seguir altera as letras maiúsculas ou minúsculas dos nomes de objetos SQL para UPPERCASE ou LOWERCASE. É possível definir case em objetos all ou substituí-lo
por tipos de objeto específicos (database, schema, relation, attribute,
function, sequence, index, variable ou projection):
type: experimental_object_rewriter
global:
outputName:
all:
case: UPPERCASE
database:
case: LOWERCASE
attribute:
case: LOWERCASE
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table TESTDB.testschema.x(A int); select * from TESTDB.testschema.x; |
bq-output.sql |
CREATE TABLE testdb.TESTSCHEMA.X ( a INT64 ) ; SELECT X.* FROM testdb.TESTSCHEMA.X ; |
Tornar tabela temporária
A configuração YAML a seguir altera uma tabela regular para uma tabela temporária:
type: object_rewriter
relation:
-
match: "testdb.testschema.x"
temporary: true
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table testdb.testschema.x(a int); |
bq-output.sql |
CREATE TEMPORARY TABLE x ( a INT64 ) ; |
Tornar tabela efêmera
A configuração YAML a seguir altera uma tabela regular para uma tabela efêmera com validade de 60 segundos.
type: object_rewriter
relation:
-
match: "testdb.testschema.x"
ephemeral:
expireAfterSeconds: 60
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table testdb.testschema.x(a int); |
bq-output.sql |
CREATE TABLE testdb.testschema.x ( a INT64 ) OPTIONS( expiration_timestamp=timestamp_add(current_timestamp(), interval 60 SECOND) ); |
Definir validade da partição
O YAML de configuração a seguir altera a validade de uma tabela particionada para 1 dia:
type: object_rewriter
relation:
-
match: "testdb.testschema.x"
partitionLifetime:
expireAfterSeconds: 86400
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table testdb.testschema.x(a date, b int) partition by (a); |
bq-output.sql |
CREATE TABLE testdb.testschema.x ( a DATE, b INT64 ) PARTITION BY a OPTIONS( partition_expiration_days=1 ); |
Alterar local ou formato externo de uma tabela
O YAML de configuração a seguir altera o local externo e formato de uma tabela:
type: object_rewriter
relation:
-
match: "testdb.testschema.x"
external:
locations: "gs://path/to/department/files"
format: ORC
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table testdb.testschema.x(a int); |
bq-output.sql |
CREATE EXTERNAL TABLE testdb.testschema.x ( a INT64 ) OPTIONS( format='ORC', uris=[ 'gs://path/to/department/files' ] ); |
Definir ou alterar descrição da tabela
O YAML de configuração a seguir define a descrição de uma tabela:
type: object_rewriter
relation:
-
match: "testdb.testschema.x"
description:
text: "Example description."
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table testdb.testschema.x(a int); |
bq-output.sql |
CREATE TABLE testdb.testschema.x ( a INT64 ) OPTIONS( description='Example description.' ); |
Definir ou alterar particionamento de tabela
O YAML de configuração a seguir altera o
esquema de particionamento de uma tabela usando
add, remove ou set, em que set substitui as colunas de partição atuais:
type: object_rewriter
relation:
-
match: "testdb.testschema.x"
partition:
simple:
add: [a]
-
match: "testdb.testschema.y"
partition:
simple:
remove: [a]
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table testdb.testschema.x(a date, b int); create table testdb.testschema.y(a date, b int) partition by (a); |
bq-output.sql |
CREATE TABLE testdb.testschema.x ( a DATE, b INT64 ) PARTITION BY a; CREATE TABLE testdb.testschema.y ( a DATE, b INT64 ) ; |
O YAML de configuração a seguir altera o esquema de particionamento de uma tabela para que ela seja particionada por bucket de intervalo:
type: object_rewriter
relation:
-
match: "testdb.testschema.mytable"
partition:
range_bucket:
column: "id"
start: 0
end: 100
step: 10
options:
require_partition_filter: "TRUE"
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
snowflake-input.sql |
create table testdb.testschema.mytable ( date timestamp_ntz, id number, content variant ); |
bq-output.sql |
CREATE TABLE TESTDB.TESTSCHEMA.MYTABLE ( DATE DATETIME, ID INT64, CONTENT JSON ) PARTITION BY RANGE_BUCKET(ID, generate_array(0, 100, 10)) OPTIONS( require_partition_filter=TRUE ); |
Definir ou alterar clustering de tabela
O YAML de configuração a seguir altera o
esquema de clustering de uma tabela usando add,
remove ou set, em que set substitui todas as colunas de clustering atuais:
type: object_rewriter
relation:
-
match: "testdb.testschema.x"
clustering:
add: [a]
-
match: "testdb.testschema.y"
clustering:
remove: [b]
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
hive-input.sql |
create table testdb.testschema.x(a int, b int); create table testdb.testschema.y(a int, b int) clustered by (b) into 16 buckets; |
bq-output.sql |
CREATE TABLE testdb.testschema.x ( a INT64, b INT64 ) CLUSTER BY a; CREATE TABLE testdb.testschema.y ( a INT64, b INT64 ) ; |
Alterar tipo de um atributo de coluna
O YAML de configuração a seguir altera o tipo de dados para um atributo de uma coluna:
type: object_rewriter
attribute:
-
match:
database: testdb
schema: testschema
attributeRegex: "a+"
type:
target: NUMERIC(10,2)
É possível transformar o tipo de dados de origem em qualquer um dos tipos de atributo de destino compatíveis.
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table testdb.testschema.x(a int, b int, aa int); |
bq-output.sql |
CREATE TABLE testdb.testschema.x ( a NUMERIC(31, 2), b INT64, aa NUMERIC(31, 2) ) ; |
Quando não há uma conversão direta entre os tipos de origem e de destino, por exemplo, ao converter uma coluna INT que armazena datas YYYYMMDD em uma coluna DATE, forneça expressões de conversão sourceToTarget e targetToSource do GoogleSQL. Use ? como o marcador de posição para o
valor da coluna ou da expressão. Exemplo:
type: object_rewriter
attribute:
-
match: "testdb.acme.employee.jd"
type:
target: DATE
sourceToTarget: "parse_date('%Y%m%d', cast(? as string))"
targetToSource: "cast(format_date('%Y%m%d', cast(? as date)) as int64)"
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table testdb.acme.employee(eid int, jd int); insert into testdb.acme.employee select 42, 20011213; select eid, jd from testdb.acme.employee e where jd > 20010101; |
bq-output.sql |
CREATE TABLE testdb.acme.employee ( eid INT64, jd DATE ) ; INSERT INTO testdb.acme.employee SELECT 42, parse_date('%Y%m%d', CAST(20011213 as STRING)) ; SELECT eid, CAST(format_date('%Y%m%d', jd) as INT64) AS jd FROM testdb.acme.employee AS e WHERE CAST(format_date('%Y%m%d', jd) as INT64) > 20010101 ; |
Adicionar conexão a um data lake externo
O YAML de configuração a seguir marca a tabela de origem como uma tabela externa que aponta para dados armazenados em um data lake externo, especificado por uma conexão de data lake.
type: object_rewriter
relation:
-
match: "testdb.testschema.x"
external:
connection_id: "connection_test"
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
hive-input.sql |
CREATE TABLE testdb.testschema.x ( a VARCHAR(150), b INT ); |
bq-output.sql |
CREATE EXTERNAL TABLE testdb.testschema.x ( a STRING, b INT64 ) WITH CONNECTION `connection_test` OPTIONS( ); |
Alterar a codificação de caracteres de um arquivo de entrada
Por padrão, o serviço de migração do BigQuery tenta detectar automaticamente a codificação de caracteres dos arquivos de entrada. Nos casos em que o BigQuery Migration Service pode identificar incorretamente a codificação de um arquivo, é possível usar um YAML de configuração para especificar explicitamente a codificação de caracteres.
O YAML de configuração a seguir especifica a codificação explícita
de caracteres do arquivo de entrada como ISO-8859-1. É possível corresponder arquivos de entrada usando um caminho exato (path), um padrão glob (pathGlob) ou uma expressão regular (pathRegex):
type: input_formats
formats:
- source:
pathGlob: "*.sql"
contents:
raw:
charset: iso-8859-1
Conversão de tipo global
O YAML de configuração a seguir altera um tipo de dados para outro em todos os scripts e especifica um tipo de dados de origem a ser evitado no script transcompilado. Isso é diferente da configuração Alterar o tipo de atributo de uma coluna, em que apenas o tipo de dados de um único atributo é alterado.
O serviço de tradução é compatível com as seguintes conversões de tipo de dados:
DATETIMEaTIMESTAMPTIMESTAMPparaDATETIME(aceita fuso horário opcional)TIMESTAMP WITH TIME ZONE(timestamptz) paraDATETIME(aceita fuso horário opcional)CHARparaVARCHAR(aceitaprecisionActionecomparisonBehavioropcionais)VARCHARparaVARCHAR(aceitaprecisionActionecomparisonBehavioropcionais)
No exemplo a seguir, o YAML de configuração converte um tipo de dados TIMESTAMP em DATETIME.
type: experimental_object_rewriter
global:
typeConvert:
timestamp: DATETIME
Converter tipos CHAR e VARCHAR
Em dialetos como o Teradata, os valores CHAR(N) são preenchidos à direita
com espaços, e as gravações de string são truncadas para o comprimento de coluna declarado.
As comparações de strings não diferenciam maiúsculas de minúsculas (NOT CASESPECIFIC) por padrão e
ignoram espaços à direita. Por padrão, o mecanismo de tradução emula essa semântica no BigQuery. Ele adiciona wrappers de preenchimento à direita (CONCAT) e
truncamento (SUBSTR) em transmissões e gravações, wrappers UPPER e RTRIM
em comparações e wrappers UPPER em chaves GROUP BY.
É possível configurar os campos char e varchar em global.typeConvert
com as seguintes propriedades:
target: precisa ser definido comoVARCHAR. Configurartarget: VARCHARemcharremove o padding à direita (CONCAT) deCHAR, mesmo quandoprecisionActionéPRESERVE.precisionAction: controla a precisão do comprimento de caracteres e os wrappers de truncamentoSUBSTR:PRESERVE(padrão): mantém a precisão do comprimento de caracteres em expressões e emite wrappers de truncamentoSUBSTRao transmitir ou inserir em colunasCHAR(N)ouVARCHAR(N). Para também emitir comprimentos de colunaSTRING(N)na DDLCREATE TABLE, consulte Como definir o rigor de precisão de string.DROP: descarta a precisão do comprimento de caracteres em expressões e omite wrappers de truncamentoSUBSTR.
comparisonBehavior: controla os wrappersRTRIMeUPPERpara comparações e chavesGROUP BY. Definir um valor diferente deSTRICTemcharouvarcharse aplica aos dois tipos. Portanto, defina o mesmo valor nas duas chaves ao configurar ambas:STRICT(padrão): emula o preenchimento de espaço final (RTRIM) e a compilação que não diferencia maiúsculas de minúsculas (UPPER).PADDING_AWARE: emula apenas o preenchimento de espaço à direita (RTRIM) e omiteUPPER.CASE_AWARE: emula apenas a compilação que não diferencia maiúsculas de minúsculas (UPPER) e omiteRTRIM.NONE: omite os wrappersRTRIMeUPPER, de modo que a saída use comparações diretas e expressõesGROUP BY.
O YAML de configuração a seguir converte CHAR em VARCHAR e remove wrappers de truncamento (SUBSTR), espaço final (RTRIM) e não diferenciação de maiúsculas de minúsculas (UPPER) para as colunas CHAR e VARCHAR:
type: experimental_object_rewriter
global:
typeConvert:
char:
target: VARCHAR
precisionAction: DROP
comparisonBehavior: NONE
varchar:
target: VARCHAR
precisionAction: DROP
comparisonBehavior: NONE
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table r(a char(10), b varchar(20)); select cast(b as char(5)) from r where a = b group by 1; |
bq-output.sql |
CREATE TABLE r ( a STRING, b STRING ) ; SELECT b FROM r WHERE a = b GROUP BY 1 ; |
Como definir o fuso horário padrão
Os dialetos de banco de dados têm semânticas e nomes variados para diferentes tipos de dados relacionados a data e hora. O serviço de tradução padroniza a seguinte terminologia na configuração YAML, independentemente do nome do tipo de dados do dialeto de entrada:
- Um
datetimeé uma combinação deY-M-D H:M:Sque não é fixada em nenhum fuso horário específico.datetimerepresenta um horário de relógio, não um instante específico. - Um
timestamprepresenta um instante de tempo específico ou absoluto e, como tal, é implicitamente fixado a um fuso horário específico, que pode ser uma configuração de sessão ou de banco de dados. - Um
timestamptzrepresenta um instante específico, como umtimestamp, mas, ao contrário de umtimestamp, ele carrega um deslocamento de fuso horário específico. Embora representem o mesmo instante,2019-06-01 12:00:00+4e2019-06-01 06:00:00-2são considerados valorestimestamptzdiferentes.
Em dialetos como o Teradata, funções relacionadas a data e hora, como
current_date, current_time ou current_timestamp, retornam carimbos de data/hora com base
em um parâmetro de fuso horário de sessão configurado implicitamente. O BigQuery, por outro lado, sempre retorna carimbos de data/hora no fuso horário UTC. Para garantir um comportamento consistente entre os dois dialetos, pode ser necessário configurar um fuso horário de acordo.
Recomendamos que você especifique o fuso horário padrão para tradução se o banco de dados de origem tiver um padrão que não seja UTC. Isso garante o comportamento correto da consulta traduzida, preservando o fuso horário.
No exemplo a seguir, o YAML de configuração converte um tipo de dados TIMESTAMP e um
TIMESTAMPTZ em DATETIME, com o fuso horário de destino definido como
Europe/Paris.
Para valores de fuso horário de string válidos, consulte Fusos horários.
type: experimental_object_rewriter
global:
typeConvert:
timestamp:
target: DATETIME
timezone: Europe/Paris
timestamptz:
target: DATETIME
timezone: Europe/Paris
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
snowflake-input.sql |
create table x(c_timestamp timestamp_ltz, c_timestamptz timestamp_tz, c_datetime timestamp_ntz); select c_timestamp from x where c_timestamp > current_timestamp(0); select c_timestamptz from x where c_timestamptz > cast(current_timestamp(0) as timestamp_tz); select c_datetime from x where c_datetime > cast(current_timestamp(0) as timestamp_ntz); |
bq-output.sql |
CREATE TABLE X ( C_TIMESTAMP DATETIME, C_TIMESTAMPTZ DATETIME, C_DATETIME DATETIME ) ; SELECT C_TIMESTAMP FROM X WHERE C_TIMESTAMP > datetime(current_timestamp(), 'Europe/Paris') ; SELECT X.C_TIMESTAMPTZ FROM X WHERE X.C_TIMESTAMPTZ > datetime(current_timestamp(), 'Europe/Paris') ; SELECT C_DATETIME FROM X WHERE C_DATETIME > datetime(current_timestamp(), 'Europe/Paris') ; |
No exemplo a seguir, o YAML de configuração converte um tipo de dados DATETIME em TIMESTAMP.
Por padrão, TIMESTAMPTZ é convertido em TIMESTAMP sem
configuração necessária.
type: experimental_object_rewriter
global:
typeConvert:
datetime:
target: TIMESTAMP
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
snowflake-input.sql |
create table x(c_timestamp timestamp_ltz, c_timestamptz timestamp_tz, c_datetime timestamp_ntz); select c_timestamp from x where c_timestamp > current_timestamp(0); select c_timestamptz from x where c_timestamptz > cast(current_timestamp(0) as timestamp_tz); select c_datetime from x where c_datetime > cast(current_timestamp(0) as timestamp_ntz); |
bq-output.sql |
CREATE TABLE X ( C_TIMESTAMP TIMESTAMP, C_TIMESTAMPTZ TIMESTAMP, C_DATETIME TIMESTAMP ) ; SELECT C_TIMESTAMP FROM X WHERE C_TIMESTAMP > current_timestamp() ; SELECT C_TIMESTAMPTZ FROM X WHERE C_TIMESTAMPTZ > current_timestamp() ; SELECT X.C_DATETIME FROM X WHERE X.C_DATETIME > current_timestamp() ; |
Selecionar modificação de instrução
O YAML de configuração a seguir altera a projeção em estrela, as cláusulas GROUP BY e
ORDER BY nas instruções SELECT.
O campo select.starProjection aceita os seguintes valores:
ALLOW: emiteSELECT *quando a consulta de origem usaSELECT *ou lista todas as colunas da tabela em ordem.PRESERVE(padrão): emiteSELECT *somente quando a consulta de origem usaSELECT *.EXPAND: expandeSELECT *em referências de colunas individuais quando os metadados da tabela estão disponíveis.
Os campos select.groupBy e select.orderBy aceitam os seguintes valores:
EXPRESSION: formata itensGROUP BYouORDER BYcomo expressões completas.ALIAS: formata itensGROUP BYouORDER BYusando aliases de colunaSELECT, quando disponíveis.INDEX: formata itensGROUP BYouORDER BYusando posições de coluna com base em 1, comoGROUP BY 1.
No exemplo a seguir, o YAML de configuração define a projeção
em estrela como EXPAND.
type: statement_rewriter
select:
starProjection: EXPAND
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table x(a int, b TIMESTAMP); select * from x; |
bq-output.sql |
CREATE TABLE x ( a INT64, b TIMESTAMP ) ; SELECT x.a, x.b FROM x ; |
Especificação de UDF
Na maioria dos casos, o tradutor de SQL do BigQuery pode analisar automaticamente a linguagem de definição de dados (DDL) de funções definidas pelo usuário (UDFs) externas para determinar os tipos de dados de entrada e saída, mesmo que o corpo da UDF seja escrito em uma linguagem externa. No entanto, para determinados dialetos de origem, o tradutor pode não conseguir compilar automaticamente a assinatura da UDF. Para garantir que as instruções SQL que fazem referência a essas UDFs sejam traduzidas com precisão sem precisar fornecer a DDL original, use um arquivo de configuração YAML para registrar explicitamente as assinaturas de UDF.
O YAML de configuração a seguir especifica a assinatura de funções definidas pelo usuário (UDFs, na sigla em inglês) que são usadas nos scripts de origem. Especifique cada assinatura no
dialeto de origem como RETURN_TYPE
FUNCTION_NAME(ARG_NAME ARG_TYPE, ...),
incluindo um nome para cada parâmetro. Assim como os arquivos ZIP de metadados, as definições de UDF podem ajudar a produzir uma tradução mais precisa dos scripts de entrada.
type: metadata
udfs:
- "date parse_short_date(dt int)"
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table x(dt int); select parse_short_date(dt) + 1 from x; |
bq-output.sql |
CREATE TABLE x ( dt INT64 ) ; SELECT date_add(parse_short_date(dt), interval 1 DAY) FROM x ; |
Alguns dialetos de origem são compatíveis com UDFs que compartilham um nome em diferentes assinaturas de argumento, às vezes chamadas de UDFs sobrecarregadas. Para UDFs sobrecarregadas, especifique
udf e um destino name diferente para que cada assinatura seja mapeada para um nome de função
exclusivo no BigQuery:
type: metadata
udfs:
- "int custom_substr(pos int)"
- udf: "int custom_substr(pos int, len int)"
name: "custom_substr_with_len"
Remover padrões de identificador durante a pesquisa de metadados
Os scripts SQL de entrada podem fazer referência a objetos ou colunas com um prefixo, sufixo ou
padrão de nomenclatura que não está nas definições de metadados. Por exemplo,
fazer referência a a_dt quando a DDL de metadados define a coluna dt. Nesse caso, use
nameAlias em type: metadata para que o mecanismo de tradução remova o
padrão ao fazer a pesquisa rápida de nomes de objetos nos metadados. O identificador original é
preservado no SQL de saída.
O campo nameAlias aceita as propriedades a seguir. Cada propriedade aceita
uma única string ou uma lista de strings, e a primeira entrada correspondente em cada lista
é aplicada:
stripPrefix: remove um prefixo literal antes de procurar metadados.stripSuffix: remove um sufixo literal antes de procurar metadados.stripRegex: corresponde a uma expressão regular que diferencia maiúsculas de minúsculas e substitui cada substring correspondente pelo primeiro grupo de captura(...)ao fazer uma pesquisa rápida de metadados. Ancore o padrão, por exemplo,^a_(.*)$, para corresponder apenas a um prefixo ou ao identificador completo.
O YAML de configuração a seguir remove o prefixo a_ dos identificadores ao procurar nomes de objetos em metadados:
type: metadata
nameAlias:
stripRegex: "^a_(.*)$"
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table t(dt date); select a_dt + 1 from t; |
bq-output.sql |
CREATE TABLE t ( dt DATE ) ; SELECT date_add(a_dt, interval 1 DAY) FROM t ; |
Como definir a rigidez da precisão decimal
Por padrão, o serviço de migração do BigQuery aumenta a precisão numérica para a maior precisão disponível em uma determinada escala. O YAML de configuração a seguir substitui esse comportamento configurando o rigor de precisão para manter a precisão decimal da instrução de origem.
type: statement_rewriter
common:
decimalPrecision: STRICT
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table x(a decimal(3,0)); |
bq-output.sql |
CREATE TABLE x ( a NUMERIC(3) ) ; |
Como definir a rigidez da precisão de strings
Por padrão, o serviço de migração do BigQuery omite a precisão de string ao traduzir colunas CHAR
e VARCHAR. Isso pode ajudar a evitar erros de truncamento quando os valores
são gravados. Alguns dialetos SQL, como o Teradata, truncam valores
que excedem a precisão máxima na gravação, enquanto o BigQuery
retorna um erro nesse cenário.
Se o aplicativo não depender do comportamento de truncamento do dialeto de origem, considere preservar a precisão da coluna na definição do tipo traduzido.
O YAML de configuração a seguir substitui esse comportamento configurando o rigor de precisão para manter a precisão da string da instrução de origem.
type: statement_rewriter
common:
stringPrecision: STRICT
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table x(a varchar(3)); |
bq-output.sql |
CREATE TABLE x ( a STRING(3) ) ; |
Mapeamento de nome de saída
É possível usar type: experimental_object_rewriter em um arquivo YAML de configuração para mapear nomes de objetos SQL (database, schema, relation, attribute, function, sequence, index, variable ou projection) de forma estática ou dinâmica:
- Cada tipo de objeto expande apenas o próprio nome e os marcadores de posição da hierarquia pai
de
${database},${schema},${relation},${attribute},${function},${sequence},${index},${variable}e${projection}. Por exemplo, uma regraschemaexpande${database}e${schema}, enquanto uma regrarelationexpande${database},${schema}e${relation}. - Quando várias regras do mesmo tipo de objeto com critérios
matchdistintos correspondem a um objeto, a última regra correspondente na lista é aplicada. - As regras globais
replaceecaseemglobal.outputNamesão executadas antes das regrasoutputNameespecíficas do objeto. Uma regra específica do objeto corresponde e pode substituir o nome transformado globalmente do objeto. Para regrasattribute,matchcompara com o nomeattributetransformado globalmente, além dos nomesdatabase,schemaerelationde origem. Para mais informações, consulte Reescrever o nome da saída global.
Para mais informações sobre como as regras de mapeamento de nomes funcionam nos níveis de banco de dados, esquema, relação, função e atributo, consulte Mapear nomes de objetos SQL para tradução.
Mapeamento de nome estático
Use o mapeamento de nomes estáticos para mapear o nome de uma entidade. Se você quiser mudar apenas partes específicas do nome, mantendo as outras partes iguais, inclua apenas as partes que precisam ser alteradas.
O YAML de configuração a seguir altera o nome da tabela de my_db.my_schema.my_table para my_new_db.my_schema.my_new_table.
type: experimental_object_rewriter
relation:
-
match: "my_db.my_schema.my_table"
outputName:
database: "my_new_db"
relation: "my_new_table"
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table my_db.my_schema.my_table(a int); |
bq-output.sql |
CREATE TABLE my_new_db.my_schema.my_new_table ( a INT64 ) ; |
É possível usar o mapeamento de nomes estáticos para atualizar a região usada pelos nomes nas funções definidas pelo usuário.
O exemplo a seguir altera os nomes na UDF bqutil.fn
para que usem a região europe_west2 em vez da multirregião padrão us:
type: experimental_object_rewriter
function:
-
match:
database: bqutil
schema: fn
outputName:
database: bqutil
schema: fn_europe_west2
Mapeamento de nomes dinâmico
Use o mapeamento de nomes dinâmico para alterar vários objetos ao mesmo tempo e crie novos nomes com base nos objetos mapeados.
O YAML de configuração a seguir altera o nome de todas as tabelas adicionando o prefixo stg_ àquelas que pertencem ao esquema staging e, em seguida, move essas tabelas para o esquema production.
type: experimental_object_rewriter
relation:
-
match:
schema: staging
outputName:
schema: production
relation: "stg_${relation}"
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table staging.my_table(a int); |
bq-output.sql |
CREATE TABLE production.stg_my_table ( a INT64 ) ; |
Mapeamento de nomes de colunas
Use a seção attribute em type: experimental_object_rewriter para
renomear colunas nas definições de tabela e nas referências de consulta:
type: experimental_object_rewriter
attribute:
-
match:
relation: employee
attributeRegex: "\\d.*"
outputName:
attribute: "col_${attribute}"
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table employee(eid int, "2name" varchar(10)); select eid, "2name" from employee e; |
bq-output.sql |
CREATE TABLE employee ( eid INT64, col_2name STRING ) ; SELECT eid, col_2name FROM employee AS e ; |
Como especificar o banco de dados padrão e o caminho de pesquisa do esquema
O YAML de configuração a seguir especifica um banco de dados padrão e um caminho de pesquisa de esquema.
type: environment
session:
defaultDatabase: myproject
schemaSearchPath: [myschema1, myschema2]
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
SELECT * FROM mydb.mytable; SELECT * FROM table1; |
bq-output.sql |
SELECT * FROM myproject.mydb.mytable; SELECT * FROM myproject.myschema1.table1; |
Como definir NLS_DATE_FORMAT
O YAML de configuração a seguir define o parâmetro NLS_DATE_FORMAT como o formato DD/MM/YYYY. Recomendamos que você especifique NLS_DATE_FORMAT para
usos implícitos de formato de data e transmissões. Se não for definido, o formato padrão para
tradução, DD-MON-RR, será usado.
type: environment
session:
dateFormat: DD/MM/YYYY
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
oracle-input.sql |
create table x(dt date default '31/12/1999'); insert into x values ('01/01/2000'); |
bq-output.sql |
CREATE TABLE X ( DT DATETIME DEFAULT DATETIME '1999-12-31 00:00:00' ) ; INSERT INTO X VALUES (DATETIME '2000-01-01 00:00:00') ; |
Reescrever o nome da saída global
O YAML de configuração a seguir usa regras replace em
global.outputName para reescrever os nomes de saída de todos os objetos (all) ou
tipos de objeto específicos (database, schema, relation, attribute,
function, sequence, index, variable ou projection). Cada regra
corresponde a uma expressão regular que diferencia maiúsculas de minúsculas e substitui as correspondências por um novo texto,
incluindo $0, $1 e outros grupos de captura.
As transformações globais de outputName (replace seguido por case) são executadas antes das regras de outputName específicas do objeto, como schema, relation ou attribute. Uma regra específica do objeto corresponde e pode substituir o nome transformado globalmente do objeto. Para regras attribute, match compara com
o nome attribute transformado globalmente ao lado dos nomes de origem database,
schema e relation:
type: experimental_object_rewriter
global:
outputName:
all:
replace:
- regex: '\s'
replaceWith: '_'
- regex: '>='
replaceWith: 'gte'
- regex: '^[^a-zA-Z_].*'
replaceWith: '_$0'
Uma tradução de SQL com esse arquivo YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table "test special chars >= 12"("42eid" int, "custom column" varchar(10)); |
bq-output.sql |
CREATE TABLE test_special_chars_gte_12 ( _42eid INT64, custom_column STRING ) ; |
Otimizar e melhorar o desempenho do SQL traduzido
Transformações opcionais podem ser aplicadas ao SQL traduzido para introduzir mudanças que podem melhorar o desempenho ou o custo. Essas otimizações são estritamente dependentes do caso e precisam ser avaliadas em relação à saída SQL não modificada para avaliar o efeito real delas no desempenho.
O YAML de configuração a seguir ativa transformações opcionais. Cada
entrada na lista transformations aceita os seguintes campos:
name: o nome da otimização.enabled(opcional): um booleano que tem como padrãotrue. Definaenabledcomofalsepara desativar uma otimização que está ativada por padrão para o dialeto de origem.parameters(opcional): um mapa de parâmetros específicos da otimização.
type: optimizer
transformations:
- name: PRECOMPUTE_INDEPENDENT_SUBSELECTS
- name: REWRITE_CTE_TO_TEMP_TABLE
parameters:
threshold: 1
| Otimização | Parâmetro opcional | Descrição |
|---|---|---|
PRECOMPUTE_INDEPENDENT_SUBSELECTS |
scope: [PREDICATE, PROJECTION]
|
Reescreve a consulta adicionando uma instrução DECLARE para
substituir uma expressão nas cláusulas PREDICATE,
PROJECTION ou ambas por uma variável pré-computada. Essa
reescrita transforma a expressão em um predicado estático que pode reduzir a
quantidade de dados lidos. O parâmetro scope aceita uma lista
que contém PREDICATE, PROJECTION ou ambos. Se
parameters for omitido, scope será definido como
[PREDICATE] por padrão, o que abrange as cláusulas WHERE e
JOIN ON.
Extrair uma subconsulta escalar para uma instrução DECLARE
vai tornar o predicado original estático e, portanto, atender aos requisitos para um planejamento de execução
melhor. Essa otimização vai introduzir novas instruções SQL.
|
REWRITE_CTE_TO_TEMP_TABLE |
threshold: N
|
Reescreve expressões de tabela comuns (CTEs) em tabelas temporárias quando há pelo menos N referências à mesma CTE. Essa reescrita
reduz a complexidade da consulta e força a execução única da CTE. Se
N for omitido, o valor padrão será 4.
Recomendamos usar essa otimização quando CTEs não triviais forem mencionados várias vezes. A introdução de tabelas temporárias tem um overhead que pode ser maior do que as execuções múltiplas de uma CTE de baixa complexidade ou de baixa cardinalidade. Essa otimização vai introduzir novas instruções SQL. |
REWRITE_ZERO_SCALE_NUMERIC_AS_INTEGER |
bigint: N
|
Reescreva os atributos NUMERIC/BIGNUMERIC de escala zero para o
tipo INT64 se a precisão estiver dentro de N. Se
N for omitido, o valor padrão será 18.
Recomendamos usar essa otimização ao traduzir de dialetos de origem que não têm tipos de números inteiros. A mudança de tipos de coluna exige a análise de todos os usos dependentes para verificar a compatibilidade de tipos e mudanças semânticas. Por exemplo, divisões fracionárias se tornando divisões inteiras ou código que espera valores numéricos. As traduções do Snowflake têm essa otimização para números de escala zero até a precisão 38 ativada por padrão. Essa otimização garante que um INTEGER do Snowflake, que é
representado implicitamente como NUMBER(38,0) no Snowflake,
seja traduzido para um INT64 do BigQuery em vez de um
BIGNUMERIC(38). Se o aplicativo usar números com precisões maiores que 18, recomendamos desativar essa funcionalidade para garantir que o BigQuery possa processar toda a gama de valores necessários para o aplicativo. |
DROP_TEMP_TABLE |
Adiciona instruções DROP TABLE para todas as tabelas temporárias criadas
em um script e não descartadas ao final dele. Isso reduz o período de cobrança de armazenamento da tabela temporária de 24 horas para o tempo de execução do script.
Recomendamos usar essa otimização quando as tabelas temporárias não forem acessadas para nenhum processamento adicional após o término da execução do script. Essa otimização vai introduzir novas instruções SQL. |
|
REGEXP_CONTAINS_TO_LIKE |
Reescreve algumas categorias de padrões de correspondência REGEXP_CONTAINS
para expressões LIKE.
Recomendamos usar essa otimização quando nenhum outro processo, como a substituição de macros, depender de que os literais de padrão de expressão regular sejam preservados sem alterações no SQL de saída. |
|
ADD_DISTINCT_TO_SUBQUERY_IN_SET_COMPARISON |
Adiciona a cláusula DISTINCT às subconsultas usadas como conjunto de valores para o operador [NOT] IN.
Recomendamos usar essa otimização quando a cardinalidade (número distinto de valores) do resultado da subconsulta for significativamente menor que o número de valores. Quando essa condição prévia não é atendida, essa transformação pode ter efeitos negativos no desempenho. |
|
APPROXIMATE_RANGE_PARTITIONS |
Aproxima esquemas de particionamento de números inteiros não contíguos ou não regulares, convertendo-os em intervalos de partição contíguos e de tamanho igual compatíveis
com o BigQuery. Por padrão, esses esquemas de particionamento não
influenciam o esquema de particionamento de tabelas em instruções DDL traduzidas.
Recomendamos usar essa otimização quando a tabela de origem usa uma função de particionamento não contígua, como a função RANGE_N do Teradata,
e se beneficiaria de um esquema de partição de tamanho igual
no BigQuery.
|
Exemplos de otimização
A otimização a seguir converte tipos numéricos de escala zero com precisão menor ou igual a 38 para INT64 no BigQuery.
# An INTEGER is internally represented as NUMBER(38,0) in Snowflake.
# To convert Snowflake INTEGER to INT64 in BigQuery, enable the rewrite for precision <= 38.
# Note that this can produce incorrect results if your application logic uses more than 18 digits of precision.
#
# This configuration is enabled by default for the Snowflake Dialect.
type: optimizer
transformations:
- name: REWRITE_ZERO_SCALE_NUMERIC_AS_INTEGER
parameters:
bigint: 38
Uma tradução de SQL com essa otimização pode ter o seguinte formato:
snowflake-input.sql |
CREATE TABLE numbers(i INTEGER, n NUMERIC(10,0)); |
bq-output.sql |
CREATE TABLE NUMBERS ( I INT64, N INT64 ) ; |
A configuração a seguir desativa a otimização em dialetos, como
o Snowflake, em que ela é ativada por padrão. Essa configuração
converte tipos numéricos em NUMERIC ou BIGNUMERIC, dependendo da
precisão de entrada, em vez do padrão de INT64.
type: optimizer
transformations:
- name: REWRITE_ZERO_SCALE_NUMERIC_AS_INTEGER
enabled: false
Uma tradução de SQL com essa otimização pode ter o seguinte formato:
snowflake-input.sql |
CREATE TABLE numbers(i INTEGER, n NUMERIC(10,0)); |
bq-output.sql |
CREATE TABLE NUMBERS ( I BIGNUMERIC(38), N NUMERIC(29) ) ; |
Criar um arquivo YAML de configuração baseado no Gemini
Para gerar uma resposta de IA, forneça pelo menos um arquivo *.ai_config.yaml e ative
as sugestões da IA do Gemini quando a interface exigir. Para mais
informações, consulte
Fornecer arquivos de configuração para uma tradução.
Requisitos
O arquivo YAML de configuração para saídas de IA precisa ter o sufixo .ai_config.yaml.
Por exemplo, rules_1.ai_config.yaml.
Campos aceitos
Ao contrário de um arquivo *.config.yaml, um arquivo *.ai_config.yaml não inclui um cabeçalho type. Em vez disso, o arquivo contém uma lista translation_rules de nível superior,
em que cada regra é compatível com os seguintes campos:
suggestion_type(opcional): especifique o tipo de sugestão de IA a ser gerada. Os seguintes tipos de sugestão são aceitos:QUERY_CUSTOMIZATION(padrão): gera sugestões de IA para código SQL com base nas regras de tradução especificadas no arquivo*.ai_config.yaml.TRANSLATION_EXPLANATION: gera um texto gerado que inclui um resumo da consulta do GoogleSQL traduzida e as diferenças e inconsistências entre a consulta SQL de origem e a consulta do GoogleSQL traduzida.
rewrite_target(opcional): especifiqueSOURCE_SQLpara aplicar a regra ao SQL de entrada original antes que o mecanismo de tradução seja executado ouTARGET_SQLpara aplicar a regra ao SQL traduzido que o mecanismo de tradução produz. O valor padrão éTARGET_SQL. Para mais informações, consulte Como os dois tipos de regras são aplicados.instruction(opcional): descreva em linguagem natural a mudança a ser aplicada ao SQL de entrada ou ao SQL traduzido para regrasQUERY_CUSTOMIZATIONou a explicação a ser gerada para regrasTRANSLATION_EXPLANATION.examples(opcional): forneça uma lista de pares SQLinputeoutputque mostram como você quer que um padrão SQL seja modificado.
É possível adicionar mais translation_rules e examples, conforme
necessário.
Exemplos
Os exemplos a seguir criam arquivos YAML de configuração baseados no Gemini que podem ser usados com as traduções de SQL.
Remover a função UPPER na consulta de saída da tradução padrão
translation_rules:
- instruction: "Remove upper() function"
examples:
- input: "upper(X)"
output: "X"
Criar várias regras de tradução para personalizar o resultado da tradução
translation_rules:
- instruction: "Remove upper() function"
suggestion_type: QUERY_CUSTOMIZATION
rewrite_target: TARGET_SQL
examples:
- input: "upper(X)"
output: "X"
- instruction: "Insert a comment at the head that explains each statement in detail."
suggestion_type: QUERY_CUSTOMIZATION
rewrite_target: TARGET_SQL
Remover comentários SQL da consulta de entrada de tradução
translation_rules:
- instruction: "Remove all the sql comments in the input sql query."
suggestion_type: QUERY_CUSTOMIZATION
rewrite_target: SOURCE_SQL
Gerar explicações de tradução usando o comando padrão do LLM
Este exemplo usa os comandos de LLM padrão fornecidos pelo serviço de tradução para gerar explicações de texto:
translation_rules:
- suggestion_type: "TRANSLATION_EXPLANATION"
Gera explicações de tradução usando seus próprios comandos em linguagem natural
translation_rules:
- suggestion_type: "TRANSLATION_EXPLANATION"
instruction: "Explain the syntax differences between the source Teradata query and the translated GoogleSQL query."
Vários tipos de sugestão em um único arquivo YAML de configuração
translation_rules:
- suggestion_type: "TRANSLATION_EXPLANATION"
instruction: "Explain the syntax differences between the source Teradata query and the translated GoogleSQL query."
- instruction: "Remove upper() function"
suggestion_type: QUERY_CUSTOMIZATION
rewrite_target: TARGET_SQL
examples:
- input: "upper(X)"
output: "X"
- instruction: "Remove all the sql comments in the input sql query."
suggestion_type: QUERY_CUSTOMIZATION
rewrite_target: SOURCE_SQL
Como aplicar várias configurações YAML
Ao traduzir uma única consulta ou arquivos SQL em lote, é possível fornecer vários arquivos YAML de configuração em um único job de tradução para refletir várias transformações. Se várias configurações entrarem em conflito, uma transformação poderá substituir outra. Recomendamos usar diferentes tipos de configurações em cada arquivo para evitar transformações conflitantes no mesmo job de tradução.
O exemplo a seguir lista dois arquivos YAML de configuração separados que foram fornecidos para um único job de tradução do SQL, um para alterar o atributo de uma coluna e o outro para definir a tabela como temporária:
change-type-example.config.yaml:
type: object_rewriter
attribute:
-
match: "testdb.testschema.x.a"
type:
target: NUMERIC(10,2)
make-temp-example.config.yaml:
type: object_rewriter
relation:
-
match: "testdb.testschema.x"
temporary: true
Uma tradução de SQL com esses dois arquivos YAML de configuração pode ter o seguinte formato:
teradata-input.sql |
create table testdb.testschema.x(a int); |
bq-output.sql |
CREATE TEMPORARY TABLE x ( a NUMERIC(31, 2) ) ; |