Consultar dados Fabric de um banco de dados HorizonDB

Consultas federadas são uma funcionalidade de Análise Federada no Microsoft Fabric HorizonDB. Use a extensão pg_fabric_fdw gerenciada pelo serviço para consultar data warehouses compatíveis e pontos de extremidade de análise SQL com SQL do PostgreSQL. Objetos importados aparecem como tabelas estrangeiras PostgreSQL, de modo que uma aplicação conectada a um banco de dados HorizonDB possa unir linhas operacionais com dados Fabric sem armazenar uma cópia local.

O wrapper traduz operações de consulta elegíveis para T-SQL e as envia para o Fabric por meio de uma conexão nativa de Fluxo de Dados Tabulares (TDS). O Fabric executa essas operações e retorna os resultados. Você não precisa reescrever suas consultas de aplicação no T-SQL nem configurar um driver de Conectividade de Banco de Dados Aberto (ODBC) ou nome de fonte de dados (DSN).

Importante

Fabric HorizonDB está em prévia pública. Capacidades, limites e comportamento podem mudar antes da disponibilidade geral. Para mais informações, consulte os recursos de pré-visualização do Microsoft Fabric.

Tabelas estrangeiras são somente de leitura. Não é possível inserir INSERT, UPDATE, DELETE, MERGE, COPY em uma tabela estrangeira, e consultas com bloqueio de linha não são suportadas. Use a entrega de dados com um trabalho de Cópia quando um aplicativo precisar de dados armazenados em tabelas locais do banco de dados HorizonDB.

Prerequisites

  • Um banco de dados HorizonDB com a integração de federação habilitada.
  • Faça login como criador do banco de dados, com permissão do Microsoft Entra para ler a origem do Fabric. Outros usuários e entidades de segurança não podem se conectar ao PostgreSQL na pré-visualização atual.
  • Um data warehouse ou endpoint de análise SQL suportado e íntegro, como o endpoint de análise SQL para dados espelhados.
  • Os nomes do banco de dados remoto, do esquema remoto e da tabela remota.
  • Permissão para criar o esquema local e os metadados de tabela estrangeira, além dos privilégios necessários de esquema USAGE e objeto.

Os exemplos usam as tabelas espelhadas horizon_sample.customers e horizon_sample.orders de Criar tabelas e Carregar dados de exemplo. O exemplo do warehouse usa um dbo.customer_signals warehouse separado com uma customer_id tabela contendo risk_score, recommended_action, calculated_at, load_batch_id e sales_analytics. Crie a fonte do armazém tutorial para um conjunto de dados sintético completo que você também possa usar com um trabalho de Cópia.

A configuração pública de pré-visualização utiliza PostgreSQL DDL. Ele não oferece um navegador gráfico de origem completo nem suporta todos os tipos de itens Fabric.

Verifique a extensão gerenciada pelo serviço

Conecte-se ao endpoint PostgreSQL e execute:

SELECT
    extension.extname AS extension_name,
    extension.extversion AS installed_version
FROM pg_catalog.pg_extension AS extension
WHERE extension.extname = 'pg_fabric_fdw';

Uma linha deve ser retornada. Se não for, não execute CREATE EXTENSION. A extensão é gerenciada pelo serviço.

Inspecione servidores externos disponíveis:

SELECT
    server.srvname AS server_name,
    wrapper.fdwname AS wrapper_name,
    server.srvoptions AS server_options
FROM pg_catalog.pg_foreign_server AS server
JOIN pg_catalog.pg_foreign_data_wrapper AS wrapper
  ON wrapper.oid = server.srvfdw
ORDER BY server.srvname;

Um banco de dados habilitado para o Federated Analytics inclui o servidor padrão fabric_dw para seu endpoint de análise SQL espelhado. A endpoint opção identifica o host Fabric e database identifica seu banco de dados remoto padrão. Não elimine, substitua ou altere este servidor gerenciado. Se fabric_dw ou pg_fabric_fdw estiver ausente, trate-o como um problema de provisionamento ou habilitação de pré-visualização.

Use sua conexão de criador do Microsoft Entra e confirme o acesso à fonte do Fabric. Não forneça um token nas opções de servidor estrangeiro ou SQL. Uma conexão PostgreSQL autorizada não prova, por si só, que a consulta Fabric pode autenticar ou ler a fonte remota. Para etapas de recuperação, consulte Solucionar problemas de consultas federadas.

Importar metadados de tabelas estrangeiras

Crie um esquema de propriedade do cliente para os metadados importados:

CREATE SCHEMA IF NOT EXISTS fabric_mirror;

Importe apenas as tabelas que o aplicativo precisa:

IMPORT FOREIGN SCHEMA horizon_sample
    LIMIT TO (customers, orders)
    FROM SERVER fabric_dw
    INTO fabric_mirror;

Substitua horizon_sample, a lista de tabela, e fabric_dw com o esquema remoto, objetos e servidor gerenciado para seu banco de dados. O nome do esquema local pode diferir do nome do esquema remoto.

IMPORT FOREIGN SCHEMA Lê o catálogo remoto e cria nomes locais de colunas e mapeamentos de tipos. Ele não copia linhas para o seu banco de dados HorizonDB. O endpoint remoto pode expor nomes de esquemas ou tabelas de forma diferente do PostgreSQL, como _public para um esquema de origem. Use os nomes informados por esse endpoint.

Use uma destas formas para selecionar tabelas:

  • Omita LIMIT TO para importar todas as tabelas visíveis do esquema remoto.
  • Use LIMIT TO (customers, orders) para importar apenas essas tabelas.
  • Use EXCEPT (staging_log) em vez de LIMIT TO para excluir tabelas selecionadas.

Coloque nomes com maiúsculas e minúsculas entre aspas, como LIMIT TO ("Orders"). Filtros de importação usam nomes exatos mesmo quando a ordenação remota não diferencia maiúsculas e minúsculas.

Um tipo de coluna não suportado faz a importação falhar em vez de criar um mapeamento inseguro. Exclua a tabela ou defina uma tabela estrangeira com apenas as colunas suportadas necessárias. Um aviso de ordenamento é diferente: ele informa regras de comparação de texto potencialmente diferentes, não um tipo não suportado. Verifique se o comando terminou e inspecione as tabelas criadas.

Para mapeamentos, definições manuais e opções de importação, consulte Referência de consulta federada.

Registre uma fonte separada do warehouse

O endpoint de análise SQL espelhado é somente leitura. Crie tabelas de origem analíticas em um Fabric Data Warehouse separado, não em um endpoint de análise SQL.

  1. Abra o depósito de código-fonte.

  2. Abra Configurações e encontre Strings de conexão.

  3. Copie a cadeia de conexão SQL e o nome do banco de dados SQL. O nome do banco de dados SQL pode diferir do nome de exibição do item Fabric.

  4. Retorne ao editor HorizonDB PostgreSQL e crie um servidor externo de propriedade do cliente:

    CREATE SERVER customer_signals_dw
        FOREIGN DATA WRAPPER pg_fabric_fdw
        OPTIONS (
            endpoint '<warehouse-sql-endpoint>',
            database '<warehouse-sql-database-name>'
        );
    
    CREATE SCHEMA IF NOT EXISTS fabric_sales;
    
    IMPORT FOREIGN SCHEMA dbo
        LIMIT TO (customer_signals)
        FROM SERVER customer_signals_dw
        INTO fabric_sales;
    

Substitua ambos os marcadores de posição pelos valores de conexão do seu armazém. Use um novo nome de servidor pertencente ao cliente; nunca recrie ou altere fabric_dw.

Importar de outro banco de dados acessível

A database_name opção de importação seleciona outro banco de dados consultável acessível pela conexão Fabric selecionada. Por exemplo, em vez da importação anterior, use este formulário quando sua conexão puder alcançar a origem:

CREATE SCHEMA IF NOT EXISTS fabric_sales;

IMPORT FOREIGN SCHEMA dbo
    LIMIT TO (customer_signals)
    FROM SERVER customer_signals_dw
    INTO fabric_sales
    OPTIONS (database_name 'sales_analytics');

Cada tabela importada mantém seu nome remoto de banco de dados. Esta opção não descobre espaços de trabalho arbitrários nem concede permissões de origem. Use o nome do banco de dados SQL a partir dos detalhes da conexão, não um nome de exibição assumido.

database_name é uma opção de importação ou de tabela externa. A opção de servidor é chamada database; os nomes não são intercambiáveis.

Inspecionar tabelas estrangeiras importadas

SELECT
    foreign_table.foreign_table_schema,
    foreign_table.foreign_table_name,
    foreign_table.foreign_server_name
FROM information_schema.foreign_tables AS foreign_table
ORDER BY
    foreign_table.foreign_table_schema,
    foreign_table.foreign_table_name;

Se você concluiu a importação opcional sales_analytics , teste uma consulta limitada:

SELECT
    signal.customer_id,
    signal.risk_score,
    signal.recommended_action,
    signal.calculated_at
FROM fabric_sales.customer_signals AS signal
WHERE signal.risk_score >= 70
ORDER BY signal.risk_score DESC
LIMIT 20;

Junte dados locais e Fabric

Esta consulta une clientes locais a resultados analíticos remotos:

SELECT
    customer.customer_id,
    customer.customer_name,
    customer.segment,
    signal.risk_score,
    signal.recommended_action,
    signal.calculated_at
FROM horizon_sample.customers AS customer
JOIN fabric_sales.customer_signals AS signal
  ON signal.customer_id = customer.customer_id
WHERE signal.risk_score >= 70
ORDER BY signal.risk_score DESC
LIMIT 20;

A aplicação permanece conectada ao Fabric HorizonDB, mas a consulta depende da fonte remota do Fabric. Uma consulta local pode ser bem-sucedida enquanto essa consulta federada falha.

Para uma tabela local seletiva, o PostgreSQL pode escolher uma varredura externa parametrizada que solicite linhas remotas correspondentes para cada chave local. Para um resultado local mais amplo, ele pode escolher uma varredura remota seguida de uma junção local. Não presuma que adicionar uma junção sempre reduz a transferência. Inspecione o plano para filtros representativos e volumes de dados.

Verifique quais operações são executadas no Fabric

Pushdown significa que o Fabric executa uma operação em vez de retornar todas as suas linhas de entrada para o PostgreSQL. Filtros, junções entre tabelas estrangeiras elegíveis, agregados, ordenação e limites podem ser enviados.

Por exemplo, planeje um agregado sobre a tabela de ordens espelhadas:

EXPLAIN (VERBOSE, COSTS OFF)
SELECT
    order_row.status,
    count(*) AS order_count,
    sum(order_row.total) AS order_total
FROM fabric_mirror.orders AS order_row
GROUP BY order_row.status
ORDER BY order_row.status;

Leia a Fabric SQL linha. Ele mostra exatamente o T-SQL planejado para o Fabric. Para um agregado totalmente empurrado, esse SQL inclui o agrupamento e agregados; PostgreSQL count(*) traduz como COUNT_BIG(*).

Localização do plano Meaning
Um Foreign Scan com a consulta completa em sua Fabric SQL linha Fabric executa as operações de consulta e retorna as linhas de resultado.
Uma varredura local Aggregate, Hash Join, ou Sort acima de uma varredura estrangeira O PostgreSQL executa essa operação nas linhas retornadas pelo Fabric. Mais linhas podem passar pela conexão.
Um Materialize nó para um cursor rolável PostgreSQL armazena em buffer as linhas para movimento do cursor. Esse nó sozinho não significa que a consulta falhou em ser enviada.
Um erro de planejamento O wrapper não pode executar o construto solicitado ou um limite configurado rejeita o plano.

Com o padrão fabric_fdw.remote_explain = OFF, EXPLAIN sem ANALYZE planeja localmente sem entrar em contato com o Fabric. Ele não valida disponibilidade remota. EXPLAIN ANALYZE executa a consulta, então use-a somente quando estiver pronto para executar a carga de trabalho.

Para o plano estimado de Fabric, as operações suportadas e as diferenças de resultados entre mecanismos, consulte a referência de consulta federada.

Controle o tamanho da transferência e o tempo da consulta

Defina um limite de planejamento e um tempo limite da instrução para a sessão:

SET fabric_fdw.max_retrieved_rows = 100000;
SET statement_timeout = '30s';

O guardrail de linha é definido por padrão para 0, o que significa sem limitação. Um valor positivo rejeita uma varredura estrangeira no momento do planejamento quando o número estimado de linhas recuperadas excede o limite. A estimativa leva em conta filtros push, junções e agregação.

Esta é uma verificação de planejamento baseada em estimativa, não um limite exato de linhas em tempo de execução. Mantenha predicados seletivos e limites explícitos de resultados, e escolha um timeout que se adapte à sua carga de trabalho. Para recuperação de cancelamentos e de tempo limite, consulte Solucionar problemas de consultas federadas.

Após terminar o exemplo, restaure os valores padrão da sessão:

RESET fabric_fdw.max_retrieved_rows;
RESET statement_timeout;

Projete consultas federadas eficientes

  • Importe apenas as tabelas necessárias e selecione apenas as colunas necessárias.
  • Filtre dados remotos o mais cedo e seletivamente possível.
  • Agregue no Fabric antes de unir um grande resultado remoto a uma pequena tabela local quando essa forma atenda aos requisitos da sua consulta.
  • Evite varreduras ilimitadas nos caminhos de solicitação de aplicação.
  • Confirme o comportamento de tipo, nulo, timestamp, agrupamento e comparação entre os motores.
  • Verifique médias inteiras, espaços finais, LIKE padrões e ordenação de UUID antes de confiar em resultados equivalentes a PostgreSQL.
  • Compare resultados federados limitados com a fonte para filtros e agregados representativos.
  • Defina tempos de espera do aplicativo e use apenas tentativas limitadas para leituras seguras.
  • Use uma tarefa de cópia quando consultas repetidas precisarem de um resultado local estável e indexado.
  • Atualize os metadados importados deliberadamente após uma alteração remota aprovada no esquema.

Metadados importados não são um mecanismo automático de sincronização de esquemas. Reconcilie colunas alteradas e consultas dependentes antes de substituir definições de tabelas estrangeiras pertencentes ao cliente. Não descarte componentes gerenciados por serviços para atualizar um esquema.

Permissions

A federação requer autorização em ambas as extremidades:

  • O chamador deve ser o criador do banco de dados na pré-visualização atual.
  • O criador precisa de permissão para ler a fonte Fabric selecionada.
  • O criador precisa criar o esquema de propriedade do cliente e os metadados de tabela estrangeira.
  • Uma substituição forçada database_name ainda exige uma fonte acessível e acesso à fonte.

Uma falha não deve recorrer à identidade de outro usuário. Não coloque tokens ou segredos nas opções do servidor ou em scripts SQL.

Solucionar problemas de federação

Sintoma Verificação
pg_fabric_fdw não está instalado Confirme o provisionamento do banco de dados e a elegibilidade de recursos. Não crie a extensão gerenciada por serviço.
O servidor gerenciado está ausente Aguarde a inicialização de provisionamento ou espelhamento e, em seguida, reúna o status da operação para suporte.
A autenticação foi negada Verifique o acesso do Microsoft Entra tanto ao Fabric HorizonDB quanto ao item Fabric remoto.
Nenhum esquema ou tabela foi encontrado Verifique os nomes remotos do banco de dados, esquema e tabela que diferenciam maiúsculas de minúsculas, mostrados na origem.
Falha na importação de um tipo Importe um subconjunto suportado e revise o mapeamento de tipos liberado.
Já existe uma relação local Importe para um novo esquema de propriedade do cliente ou remova apenas os metadados obsoletos de tabelas estrangeiras.
Uma consulta retorna muitas linhas ou demora demais Inspecione EXPLAIN (VERBOSE), adicione filtros seletivos, projete menos colunas e revise o guardrail de linha.
Uma gravação é rejeitada Isso é esperado. Tabelas externas de versão prévia pública são somente de leitura.
Consultas locais funcionam, mas a federação falha Investigue capacidade remota, autorização, esquema e status de federação independentemente do estado do banco de dados.

Para códigos SQLSTATE, recuperação de autenticação, falhas de importação e erros de tradução de consultas, consulte Solucionar problemas de consultas federadas.

Remova metadados importados

Remova apenas as tabelas estrangeiras de propriedade do cliente criadas por estes exemplos:

DROP FOREIGN TABLE IF EXISTS fabric_sales.customer_signals;
DROP FOREIGN TABLE IF EXISTS fabric_mirror.customers;
DROP FOREIGN TABLE IF EXISTS fabric_mirror.orders;

Se você criou customer_signals_dw apenas para este exercício, remova-o depois de remover suas tabelas externas:

DROP SERVER customer_signals_dw;

Essas instruções não excluem dados remotos. Se um objeto local depender de uma tabela estrangeira, revise essa dependência em vez de adicionar CASCADE sem verificá-la. Remova os esquemas de exemplo somente depois de confirmar que estão vazios e não são mais necessários.

Não remova pg_fabric_fdw nem um servidor estrangeiro ou mapeamento de usuário gerenciado pelo serviço.