Projetando mapeamentos para eventos OpenLineage

Ao criar mapeamentos para os eventos do OpenLineage, decida sobre as condições e ações de cada regra.

OpenLineage estrutura do evento

Um evento OpenLineage pode ter a seguinte estrutura:

{
  "eventTime": "2025-08-21T10:03:33.616Z",
  "schemaURL": "https://openlineage.io/spec/2-0-2/OpenLineage.json#/$defs/RunEvent",
  "eventType": "COMPLETE",
  "job": {
    "namespace": "custom_etl_tool",
    "name": "workspace_name/folder_1/folder_2/job_name_1"
  },
  "inputs": [
    {
      "namespace": "s3://mybigbucket.com",
      "name": "sales/public/orders",
      "facets": {
        "schema": {
          "fields": [
            {
              "name": "my_one_field",
              "type": "integer"
            }
          ]
        }
      }
    }
  ],
  "outputs": [
    {
      "namespace": "mongodb://analytics-db.company.com:27017",
      "name": "customerdb.mycollection.sales_summary",
      "facets": {
        "schema": {
          "fields": [
            {
              "name": "my_one_field",
              "type": "integer"
            }
          ]
        }
      }
    }
  ]
}

O evento consiste nas seguintes seções:

inputs que se referem a conjuntos de dados que são lidos.
job que se referem a processos que transformam dados.
outputs que se referem a conjuntos de dados que são gravados.

Cada seção contém um namespace que identifica a tecnologia e o local, um nome que identifica o caminho do objeto e facetas opcionais que fornecem metadados adicionais, como a linhagem da coluna.

O namespace é usado para definir uma condição no mapeamento. Ele pode ser estático ou dinâmico.

Um namespace estático, por exemplo, o namespace de trabalho custom_etl_tool , representa o agrupamento lógico de trabalhos executados por uma ferramenta ETL personalizada. É usado para definir o espaço de trabalho ou aplicativo para rastrear a linhagem.
Um namespace dinâmico contém um prefixo que representa um tipo de tecnologia e não muda. Ele também contém valores dinâmicos de host e porta que representam endpoints específicos. Por exemplo, no namespace mongodb://analytics-db.company.com:27017, o prefixo mongodb:// não muda, e o host analytics-db.company.com e a porta 27017 representam um dos muitos pontos de extremidade.

Antes de criar mapeamentos

Antes de começar a criar mapeamentos, revise a estrutura do seu evento e identifique as tecnologias que são referenciadas. Os eventos podem conter referências a tecnologias que já são compatíveis. Os mapeamentos padrão são criados para essas tecnologias. Eles estão listados na guia Mapeamentos ativos e são identificados pelo valor do prefixo de um namespace. Por exemplo, o mapeamento s3:// refere-se à tecnologia Amazon S3.

Para essas tecnologias que não são suportadas por padrão, crie seus próprios mapeamentos personalizados.

Dica: se o evento contiver referências a tecnologias compatíveis com conectores padrão, execute primeiro os metadados de linhagem para essas fontes de dados. Ele garante que os ativos de origem e destino corretos sejam descobertos. Se essa etapa for ignorada, os ativos de espaço reservado deduzidos e os servidores desconhecidos poderão ser incluídos na linhagem.

Quando um mapeamento para um evento específico ainda não foi criado, um espaço reservado é criado e todos os ativos referenciados por um namespace específico são localizados nesse sistema de espaço reservado. Você pode criar um mapeamento correspondente posteriormente e, depois de reimportar o evento, a linhagem é atualizada com as informações do novo mapeamento.

Condições de mapeamento

Na seção de condições de mapeamento, você define o tipo do namespace e o método de correspondência de namespace.

Escopo de regra

A regra de mapeamento pode ser baseada no namespace do conjunto de dados ou no namespace do trabalho. Se você quiser criar um mapeamento com base nos namespaces do conjunto de dados e do trabalho, crie dois mapeamentos individuais.

Para obter mais informações sobre as convenções de nomenclatura do site OpenLineage, consulte Convenções de nomenclatura.

Método de correspondência de namespace e valor de namespace

O mapeamento pode ser baseado em um prefixo de namespace ou em todo o valor do namespace. O método de correspondência afeta a forma como as definições da fonte de dados são posteriormente atribuídas aos ativos importados.

Prefixo de namespace: O namespace contém um prefixo que é comum a muitos eventos. O prefixo especifica um tipo de tecnologia, por exemplo, s3://, ou mongodb://, e esse valor não muda. Os valores de host e porta são dinâmicos e distinguem endpoints específicos do mesmo tipo de tecnologia. Quando você seleciona esse método, as definições de fonte de dados podem ser atribuídas automaticamente.
No campo Valor do prefixo do namespace, especifique o valor do prefixo, incluindo o delimitador :// ou ., por exemplo s3://, ou mongodb://.
Valor exato do namespace: O namespace é estático e contém os detalhes do host e da porta. Ele identifica de forma exclusiva um endpoint específico. Quando você seleciona esse método, posteriormente seleciona manualmente uma definição de fonte de dados específica. No campo Namespace exact value (Valor exato do espaço de nome), especifique o valor completo do espaço de nome, por exemplo, custom_etl_tool, ou s3://mybigbucket.com.

Ações de Mapeamento

As ações definem o que acontece quando as condições da regra são atendidas. Configure as seguintes ações:

Atribua o tipo de tecnologia correto.
Defina como o elemento de nome de um evento é interpretado na hierarquia de ativos.
Associar definições corretas de fontes de dados para que os ativos sejam localizados no sistema correto.

Tipo de tecnologia

Você pode atribuir a tecnologia padrão de uma lista ou criar uma tecnologia personalizada. Cada tecnologia contém informações sobre os tipos de ativos e a hierarquia, bem como as ramificações.

Branch: A ramificação é necessária porque uma tecnologia pode conter muitos tipos de ativos no mesmo nível de ativos. Por exemplo, um banco de dados pode conter tabelas ou exibições. Os nomes das filiais devem ser exclusivos. Você pode criar dois mapeamentos para o mesmo evento, mas com base em um tipo de namespace diferente e com uma ramificação exclusiva. Consulte o exemplo a seguir:

Regra de mapeamento 1:

Escopo da regra: Espaço de nome do conjunto de dados
Método de correspondência de namespace: Namespace exact match com o valor Custom_tool
Tipo de tecnologia:
- Nome da tecnologia: Custom_tool
- Filial: Tabela
- Hierarquia de ativos: Banco de dados > Esquema > Tabela

Regra de mapeamento 2:

Escopo da regra: Espaço de nome do trabalho
Método de correspondência de namespace: Namespace exact match com o valor Custom_tool
Tipo de tecnologia:
- Nome da tecnologia: Custom_tool
- Filial: Procedimento
- Hierarquia de ativos: Banco de dados > Esquema > Procedimento

Hierarquia de Ativo: Ao definir a hierarquia de ativos, especifique quantos níveis de ativos existem em sua fonte de dados e forneça os nomes de cada nível. O primeiro nível representa o tipo pai mais alto na hierarquia, por exemplo, um banco de dados ou uma pasta. Opcionalmente, selecione o tipo de ativo que pode ocorrer de forma recursiva. Por exemplo, na hierarquia Collection > Folder > Folder > File, o tipo de ativo Folder é recursivo.

Definições de origem de dados

As definições da fonte de dados especificam o local dos dados. Na visualização de linhagem, eles definem em qual sistema os dados são exibidos. Cada evento refere-se a três sistemas, um em cada seção do evento. Portanto, são necessárias três definições de fonte de dados. Para otimizar o processo, crie todas as definições de fonte de dados antes de começar a criar mapeamentos.

Para obter mais informações, consulte Proteção de dados com definições de fonte de dados.

Ao criar um mapeamento, você precisa decidir como as definições de fonte de dados são aplicadas aos eventos. Você pode escolher entre atribuição automática e manual.

Atribuir automaticamente
As definições de fonte de dados são atribuídas automaticamente, com base no prefixo e nos valores dinâmicos de host e porta do namespace. Essa opção está disponível quando o método de correspondência de namespace é baseado no prefixo. Quando uma definição de fonte de dados correspondente é encontrada, ela é atribuída. Quando mais de uma definição de fonte de dados correspondente é encontrada, ou nenhuma correspondência é encontrada, um sistema deduzido é criado e todos os ativos são associados a esse sistema deduzido.

Quando os sistemas deduzidos são criados, talvez seja necessário criar atribuições de alias. Para obter mais informações, consulte Configuração de atribuições de alias.

Selecionar manualmente
Selecione uma definição de fonte de dados específica na lista para que todos os ativos sejam localizados nesse sistema. Essa é a única opção quando o mapeamento se baseia no valor exato do namespace, mas você também pode usá-la quando o mapeamento se baseia no prefixo do namespace.

Configurações comuns de mapeamento

Consulte a tabela a seguir para analisar os cenários mais comuns e ver como os mapeamentos são configurados em cada caso.

Situação	Método de correspondência	Atribuição de definição de fonte de dados
Tecnologia conhecida com muitos pontos de extremidade, por exemplo `s3://…`	Prefixo de namespace	Atribuir automaticamente (preferencial)
Um grupo de trabalho lógico específico, por exemplo `custom_etl_tool`	Valor exato do namespace	Selecionar manualmente
Tecnologia de banco de dados para a qual um conector padrão está disponível	Prefixo de namespace	Atribuir automaticamente Execute a importação de metadados com o conector padrão antes de importar o evento

Em alguns casos, a linhagem pode não ser tão precisa quanto o esperado. Consulte os exemplos a seguir:

Quando o tipo de tecnologia no mapeamento e na definição da fonte de dados não corresponde, o sistema deduzido é criado e a linhagem pode ser desconectada.
Quando a definição da fonte de dados não é criada para um namespace que é importado com o evento, é criado um sistema deduzido. Como resultado, a configuração de aliases pode ser necessária.
Quando a hierarquia de ativos definida no mapeamento não corresponde ao padrão de nome do evento, os ativos são exibidos incorretamente na linhagem ou são adicionados a ativos de espaço reservado.