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:

  1. 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.yaml ou ambos os tipos de arquivos de configuração para combinar regras estruturais com a personalização do Gemini.
  2. 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.
  3. 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
  • O SQL de entrada precisa ser analisado no dialeto de origem.
  • As regras não podem atuar no texto do SQL de entrada que o analisador não reconhece, como marcadores de posição ${VAR} ou sintaxe de modelo.
  • Use uma regra SOURCE_SQL em arquivos *.ai_config.yaml ou seu próprio pré-processamento para remover esse texto primeiro.
  • Ative as sugestões da IA do Gemini para o job.
  • O job precisa ser executado em um local de processamento compatível.
  • O uso do Gemini é sem custo financeiro até um limite.
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:

  1. O Gemini aplica regras SOURCE_SQL em arquivos *.ai_config.yaml ao SQL de entrada original para produzir o SQL de origem reescrito.
  2. O mecanismo de tradução traduz o SQL de origem reescrito da etapa anterior ou o SQL de entrada original, se nenhuma regra SOURCE_SQL se aplicar, e aplica as regras nos arquivos *.config.yaml para produzir o SQL traduzido.
  3. O Gemini aplica as regras de TARGET_SQL nos arquivos *.ai_config.yaml ao SQL traduzido da etapa anterior para produzir o SQL de destino reescrito. Se os arquivos *.ai_config.yaml incluírem regras TRANSLATION_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:
  • 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-files para especificar arquivos *.config.yaml ou *.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-uris ou --source-local-dirs ou transmita arquivos individuais com a flag --source-gcs-files ou --source-local-files.
    • *.ai_config.yaml: inclua os arquivos no diretório de entrada que você passa para --source-gcs-uris ou --source-local-dirs ou transmita arquivos individuais com a flag --source-gcs-files ou --source-local-files e 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 em source_spec.base_uri, transmita uma entrada gcs_file_path em source_spec quando o arquivo não estiver em base_uri ou transmita uma entrada literal inline em source_spec.
  • *.ai_config.yaml: forneça os arquivos em source_spec em base_uri, como uma entrada gcs_file_path quando o arquivo não estiver em base_uri ou como uma entrada literal inline, e inclua "suggestion" em target_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 entradas translationConfigs inline.
    • *.ai_config.yaml: transmite entradas aiSuggestionConfigs inline.
  • Para traduzir arquivos SQL em lote (translate_batch_queries), faça o seguinte:
    • *.config.yaml: faça upload dos arquivos em sourceBaseUri ou liste-os em configurationFilePaths quando eles não estiverem em sourceBaseUri.
    • *.ai_config.yaml: faça upload dos arquivos em sourceBaseUri ou liste-os em configurationFilePaths quando eles não estiverem em sourceBaseUri e defina enableAiSuggestions como true.

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_SQL nos arquivos *.ai_config.yaml.
  • SQL de destino reescrito do Gemini depois de aplicar as regras TARGET_SQL nos arquivos *.ai_config.yaml.
  • Uma explicação de tradução do Gemini quando os arquivos *.ai_config.yaml incluem regras TRANSLATION_EXPLANATION ou 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> ou translation_explanation_suggestion/<var>PATH</var>) a target_return_literals para recebê-los em translatedLiterals.
  • 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_query e get_translation retornam translatedQuery, sourceSqlSuggestion e targetSqlSuggestion, e a ferramenta explain_translation retorna 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.yaml no 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.yaml não pode exceder 1 MB.
  • O tamanho total de todos os arquivos *.config.yaml usados em um único job de tradução de SQL não pode exceder 4 MB.
  • Se você estiver usando a sintaxe regex para 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.yaml nã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:

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 propriedades relation, como temporary, ephemeral, partitionLifetime, external, description, partition e clustering, e os tipos de dados attribute (type).
  • experimental_object_rewriter: reescreve nomes de objetos de saída com outputName em global, database, schema, relation, attribute, function, index, sequence, variable e projection, e converte tipos de dados globalmente com global.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 em session, como defaultDatabase, schemaSearchPath e dateFormat.
  • 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 de SELECT *, a formatação de GROUP BY e ORDER 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:

  • database ou db: corresponde ao nome do banco de dados de origem, que corresponde ao componente project_id no BigQuery.
  • schema: corresponde ao nome do esquema de origem, que corresponde ao componente dataset no 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 de attribute.
  • databaseRegex ou dbRegex: faz a correspondência de todo o nome de database com uma expressão regular que não diferencia maiúsculas de minúsculas.
  • schemaRegex: corresponde ao nome inteiro de schema com uma expressão regular que não diferencia maiúsculas de minúsculas.
  • relationRegex: corresponde ao nome inteiro de relation com uma expressão regular que não diferencia maiúsculas de minúsculas.
  • attributeRegex: corresponde ao nome inteiro de attribute com uma expressão regular que não diferencia maiúsculas de minúsculas. Essa propriedade é válida apenas para a seleção de attribute.

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:

  • BOOLEAN
  • TINYINT
  • SMALLINT
  • INTEGER
  • BIGINT
  • FLOAT
  • DOUBLE
  • NUMERIC (compatível com precisão e escala opcionais, como NUMERIC(18, 2))
  • TIME
  • TIMETZ
  • DATE
  • DATETIME
  • TIMESTAMP
  • TIMESTAMPTZ
  • CHAR (compatível com precisão opcional, como CHAR(42))
  • VARCHAR (compatível com precisão opcional, como VARCHAR(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:

  • DATETIME a TIMESTAMP
  • TIMESTAMP para DATETIME (aceita fuso horário opcional)
  • TIMESTAMP WITH TIME ZONE (timestamptz) para DATETIME (aceita fuso horário opcional)
  • CHAR para VARCHAR (aceita precisionAction e comparisonBehavior opcionais)
  • VARCHAR para VARCHAR (aceita precisionAction e comparisonBehavior opcionais)

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 como VARCHAR. Configurar target: VARCHAR em char remove o padding à direita (CONCAT) de CHAR, mesmo quando precisionAction é PRESERVE.
  • precisionAction: controla a precisão do comprimento de caracteres e os wrappers de truncamento SUBSTR:
    • PRESERVE (padrão): mantém a precisão do comprimento de caracteres em expressões e emite wrappers de truncamento SUBSTR ao transmitir ou inserir em colunas CHAR(N) ou VARCHAR(N). Para também emitir comprimentos de coluna STRING(N) na DDL CREATE 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 truncamento SUBSTR.
  • comparisonBehavior: controla os wrappers RTRIM e UPPER para comparações e chaves GROUP BY. Definir um valor diferente de STRICT em char ou varchar se 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 omite UPPER.
    • CASE_AWARE: emula apenas a compilação que não diferencia maiúsculas de minúsculas (UPPER) e omite RTRIM.
    • NONE: omite os wrappers RTRIM e UPPER, de modo que a saída use comparações diretas e expressões GROUP 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 de Y-M-D H:M:S que não é fixada em nenhum fuso horário específico. datetime representa um horário de relógio, não um instante específico.
  • Um timestamp representa 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 timestamptz representa um instante específico, como um timestamp, mas, ao contrário de um timestamp, ele carrega um deslocamento de fuso horário específico. Embora representem o mesmo instante, 2019-06-01 12:00:00+4 e 2019-06-01 06:00:00-2 são considerados valores timestamptz diferentes.

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: emite SELECT * quando a consulta de origem usa SELECT * ou lista todas as colunas da tabela em ordem.
  • PRESERVE (padrão): emite SELECT * somente quando a consulta de origem usa SELECT *.
  • EXPAND: expande SELECT * 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 itens GROUP BY ou ORDER BY como expressões completas.
  • ALIAS: formata itens GROUP BY ou ORDER BY usando aliases de coluna SELECT, quando disponíveis.
  • INDEX: formata itens GROUP BY ou ORDER BY usando posições de coluna com base em 1, como GROUP 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 regra schema expande ${database} e ${schema}, enquanto uma regra relation expande ${database}, ${schema} e ${relation}.
  • Quando várias regras do mesmo tipo de objeto com critérios match distintos correspondem a um objeto, a última regra correspondente na lista é aplicada.
  • As regras globais replace e case em global.outputName são executadas antes das regras outputName específicas do objeto. 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, além dos nomes database, schema e relation de 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ão true. Defina enabled como false para 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): especifique SOURCE_SQL para aplicar a regra ao SQL de entrada original antes que o mecanismo de tradução seja executado ou TARGET_SQL para 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 regras QUERY_CUSTOMIZATION ou a explicação a ser gerada para regras TRANSLATION_EXPLANATION.
  • examples (opcional): forneça uma lista de pares SQL input e output que 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)
    )
    ;