Federação de catálogo do Palantir Foundry

info

Visualização

Esse recurso está em Prévia Pública.

A federação de catálogo do Palantir Foundry permite que o Unity Catalog leia tabelas Iceberg do Palantir Foundry diretamente do armazenamento em nuvem.

Com a federação de catálogos, o Unity Catalog acessa as tabelas Iceberg do Palantir Foundry no armazenamento cloud e a query é executada inteiramente no compute do Databricks. As equipes de dados podem descobrir, governar e consultar dados do Palantir Foundry a partir do Databricks sem criar pipelines ETL. O acesso aos dados é somente leitura.

Antes de começar

Revise os seguintes requisitos antes de configurar a federação de catálogo do Palantir Foundry.

Requisitos do workspace:

• O workspace deve estar habilitado para o Unity Catalog. Consulte Comece a usar o Unity Catalog.
• Como este recurso está em Prévia pública, um administrador do workspace deve ativá-lo na página Pré-visualizações do workspace . Consulte Gerenciar prévias em nível de workspace.

Requisitos de computação:

• O compute do Databricks deve usar o Databricks Runtime 18 ou superior.
• SQL warehouses devem ser Pro ou Serverless.
• Clusters dedicados (anteriormente clusters de usuário único) não são suportados.

Requisitos de rede:

• Os intervalos de IP de saída do Databricks para o plano de controle e para o plano de dados devem estar na lista de permissões no Palantir Foundry. Consulte Configurando a entrada no Foundry e Recomendações de rede para a Lakehouse Federation.

Permissões necessárias:

• Para criar uma conexão, é preciso ser administrador de metastore ou usuário com o privilégio CREATE CONNECTION no metastore do Unity Catalog anexado ao espaço de trabalho.
• Para criar um catálogo externo, você deve ter a permissão CREATE CATALOG no metastore. Você também deve ser proprietário da conexão ou ter o privilégio CREATE FOREIGN CATALOG nela.

Requisitos do Palantir Foundry:

• As tabelas do Palantir Foundry devem ser tabelas Iceberg.
• Um aplicativo de terceiros do Palantir Foundry para autenticação. Configure o aplicativo de acordo com o método de autenticação:

  • OAuth de usuário para máquina (U2M) :

    • O aplicativo deve oferecer suporte aos escopos api:iceberg-read e offline_access.
    • O aplicativo deve ter a URL de redirecionamento OAuth https://<databricks-workspace-url>/login/oauth/lakehousefederation.html configurada, onde <databricks-workspace-url> é o hostname do seu workspace.
    • O usuário que autentica a conexão deve ter acesso à pasta raiz federada.

  • OAuth Machine to Machine (M2M) :

    • O aplicativo deve oferecer suporte à concessão de credenciais de cliente e ao escopo api:iceberg-read.
    • O usuário de serviço por trás da aplicação deve ter acesso à pasta raiz federada.

Passo 1: Criar uma conexão

Permissões necessárias: Administrador do Metastore ou usuário com o privilégio CREATE CONNECTION.

Uma conexão especifica um caminho e as credenciais para acessar um sistema externo. Ele identifica o host do Palantir Foundry e as credenciais para autenticação, não a pasta a ser federada. Você seleciona a pasta raiz ao criar o catálogo externo em O passo 2: Criar um catálogo externo.

A federação do Palantir Foundry é compatível com dois métodos de autenticação, descritos nas subseções a seguir. Ambos exigem um aplicativo de terceiros do Palantir Foundry.

nota

Você também pode usar a API REST do Databricks ou a CLI do Databricks para criar uma conexão. Consulte POST /api/2.1/unity-catalog/connections e comandos do Unity Catalog.

Autenticação OAuth User to Machine (U2M)

Com o OAuth User to Machine (U2M), o Unity Catalog acessa o Foundry como o usuário que autentica a conexão. Crie esta conexão usando o Explorador de Catálogos. Este método não pode ser configurado usando SQL, porque o fluxo de login OAuth requer a interface de usuário.

1. No seu workspace do Databricks, clique em Catálogo .
2. Na parte superior do painel Catálogo , clique no ícone Adicionar e selecione Criar uma conexão no menu.
3. Na página Noções básicas de conexão do assistente Configurar conexão , insira um nome de conexão fácil de lembrar.
4. Selecione um Connection type de Palantir Foundry e um Auth type de OAuth User to Machine , depois clique em Next .
5. Na página Authentication , insira o Host da sua instância do Palantir Foundry, por exemplo your-company.palantirfoundry.com, e conclua o fluxo de login OAuth para autorizar a conexão.
6. (Opcional) Adicione um comentário.
7. Clique em Criar conexão .

Autenticação OAuth Machine to Machine (M2M)

Com o OAuth Machine to Machine (M2M), o Unity Catalog acessa o Foundry como o usuário de serviço por trás do aplicativo de terceiros, usando a concessão de credenciais do cliente. Crie esta conexão usando o Catalog Explorer ou o comando CREATE CONNECTION do SQL em um Notebook do Databricks ou no editor de consultas SQL do Databricks.

Catalog Explorer

1. No seu workspace do Databricks, clique em Catálogo .

2. Na parte superior do painel Catálogo , clique no ícone Adicionar e selecione Criar uma conexão no menu.

3. Na página Noções básicas de conexão do assistente Configurar conexão , insira um nome de conexão fácil de lembrar.

4. Selecione um Tipo de conexão como Palantir Foundry e um Tipo de autenticação como OAuth máquina para máquina e, em seguida, clique em Próximo .

5. Na página Autenticação , digite o seguinte:

   • Host : O hostname da sua instância do Palantir Foundry, por exemplo your-company.palantirfoundry.com.
   • Client ID : O ID do cliente da sua aplicação de terceiros do Palantir Foundry.
   • Segredo do cliente : o segredo do cliente da sua aplicação de terceiros Palantir Foundry.

6. (Opcional) Adicione um comentário.

7. Clique em Criar conexão .

SQL

Execute o seguinte comando em um notebook ou no editor de consultas SQL do Databricks. Substitua os valores temporários:

• <connection-name>: Nome para a conexão no Databricks.
• <palantir-host>: O hostname da sua instância do Palantir Foundry, por exemplo your-company.palantirfoundry.com.
• <client-id>: O ID do cliente da sua aplicação de terceiros do Palantir Foundry.
• <secret-scope> e <secret-key>: O Secret Scope e a chave que armazenam o segredo do cliente do seu aplicativo de terceiros Palantir Foundry.

SQL

CREATE CONNECTION <connection-name> TYPE PALANTIR
OPTIONS (
  host '<palantir-host>',
  client_id '<client-id>',
  client_secret secret('<secret-scope>','<secret-key>')
);

A Databricks recomenda que você utilize segredos em vez de strings para valores confidenciais, como o segredo do cliente. Para obter informações sobre como configurar segredos, consulte Gerenciamento de segredos.

Passo 2: Criar um catálogo externo

Permissões necessárias: permissão CREATE CATALOG na metastore e propriedade da conexão ou o privilégio CREATE FOREIGN CATALOG na conexão.

Um foreign catalog espelha sua pasta raiz do Palantir Foundry para que você possa query e gerenciar o acesso às suas tabelas usando Databricks e Unity Catalog. Para criar um foreign catalog, use a conexão que você criou no o passo 1: Criar uma conexão.

Crie um catálogo externo usando o Catalog Explorer ou o comando SQL CREATE FOREIGN CATALOG em um notebook do Databricks ou no editor de consultas SQL do Databricks.

Catalog Explorer

1. No seu workspace do Databricks, clique em Catálogo para abrir o Catalog Explorer.
2. Na parte superior do painel Catálogo , clique no ícone Adicionar e selecione Adicionar um catálogo no menu.
3. Insira um Nome do catálogo e selecione um Tipo de catálogo externo .
4. Selecione a Conexão que você criou na Etapa 1: Criar uma conexão no menu suspenso.
5. Para Pasta raiz , insira a pasta do Palantir Foundry onde o Unity Catalog procura esquemas e tabelas para federar, por exemplo /space-name/project-name/folder-name. Consulte Mapeamento de pasta raiz e namespace.
6. No campo Local de armazenamento , especifique um local de armazenamento em cloud gravável que armazene metadados para as tabelas Iceberg neste catálogo. A account de serviço gerenciada pelo Databricks deve ter acesso de leitura e gravação a ele. Este local pode ser qualquer bucket de armazenamento e não precisa estar relacionado aos buckets de tabela.
7. Clique em Criar catálogo .
8. Atribua acesso ao workspace, um proprietário e privilégios conforme solicitado.

SQL

Execute o seguinte comando em um notebook ou no editor de consultas SQL do Databricks. Os itens entre colchetes são opcionais. Substitua os valores temporários:

• <catalog-name>: Nome para o catálogo no Databricks.
• <connection-name>: O nome da conexão que você criou em o passo 1: Criar uma conexão.
• <root-folder>: A pasta do Palantir Foundry onde o Unity Catalog procura esquemas e tabelas para federar, por exemplo /space-name/project-name/folder-name. Consulte Pasta raiz e mapeamento de namespace.
• <storage-location>: um local de armazenamento em cloud gravável que armazena metadados para as tabelas Iceberg neste catálogo. A account de serviço gerenciada pelo Databricks deve ter acesso de leitura e gravação a ela. Este local pode ser qualquer bucket de armazenamento e não precisa estar relacionado aos buckets de tabela.

SQL

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name>
USING CONNECTION <connection-name>
OPTIONS (
  root_folder '<root-folder>',
  storage_root '<storage-location>'
);

O Unity Catalog descobre as pastas e tabelas na pasta raiz:

• As subpastas do Palantir Foundry tornam-se esquemas do Unity Catalog.
• As tabelas Iceberg do Palantir Foundry tornam-se tabelas externas do Unity Catalog.

Etapa 3: conceder permissões e consultar o catálogo

Após configurar a federação de catálogos, os usuários devem ter as permissões apropriadas do Unity Catalog para acessar tabelas federadas:

• Todos os usuários precisam das permissões USE CATALOG e USE SCHEMA no catálogo e no esquema, respectivamente.
• Para ler de uma tabela federada, os usuários precisam da permissão SELECT.

Para obter mais informações sobre os privilégios do Unity Catalog e como concedê-los, consulte Gerenciar privilégios no Unity Catalog.

Após conceder permissões, os usuários podem consultar as tabelas externas do Databricks:

SQL

SELECT * FROM <catalog-name>.<schema>.<table>;

Pasta raiz e mapeamento de namespace

Ao criar um catálogo estrangeiro, você especifica uma pasta do Palantir Foundry (por exemplo, /space-name/project-name/folder-name) como a raiz da federação. O Unity Catalog mapeia suas subpastas para esquemas estrangeiros e as tabelas Iceberg nessas subpastas tornam-se tabelas estrangeiras no Unity Catalog. Isso mapeia a hierarquia mais profunda do Foundry em uma estrutura consistente de três níveis.

Por exemplo, se você federar a pasta raiz /sales/orders:

Text

Palantir Foundry object                       Unity Catalog object
────────────────────────────────────────────  ──────────────────────────────────────────────────
sales                    (Foundry Space)
└── orders               (Foundry Project)    <foreign-catalog>                        (Catalog)
    └── shipments        (Foundry Folder)     <foreign-catalog>.shipments              (Schema)
        └── line_items   (Iceberg Table)      <foreign-catalog>.shipments.line_items   (Table)

A pasta que você federar se torna o catálogo, cada subpasta se torna um esquema e cada tabela Iceberg se torna uma tabela externa.

Limitações

A federação de catálogo do Palantir Foundry tem as seguintes limitações:

• A federação do Palantir Foundry pode acessar apenas tabelas Iceberg. Views não são suportadas.
• A conectividade privada com o catálogo Palantir Foundry não é suportada.
• Os nomes de esquemas e tabelas seguem as limitações de nomenclatura padrão do Unity Catalog. O Databricks não oferece suporte a nomes que contenham ponto (.), espaço () ou barra (/). Consulte Requisitos de nomenclatura de objetos protegíveis.
• Uma pasta raiz que é uma pasta de nível único no Foundry (uma pasta que contém apenas tabelas e nenhuma subpasta para mapear para esquemas) não exibe esquemas ou tabelas. A federação requer pelo menos um nível de subpastas para mapear para esquemas do Unity Catalog.

Consulte Limitações para limitações relacionadas ao Iceberg.

Solução de problemas

A seção a seguir descreve erros comuns e suas resoluções.

Failed to create request URI ou pasta raiz inválida

• A opção root_folder não corresponde a um caminho de pasta na sua instância do Palantir Foundry. Verifique o caminho.

Falha na autenticação ao criar a conexão

As credenciais do aplicativo de terceiros Palantir Foundry não são válidas, ou a identidade de autenticação não tem acesso à pasta raiz federada. Confirme o ID do cliente e o segredo (para OAuth M2M) ou reautentique (para OAuth U2M) e verifique se a identidade tem permissão na pasta raiz. Consulte Antes de começar.