Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Consultas federadas no Fabric HorizonDB são usadas pg_fabric_fdw para ler warehouses suportados e endpoints de análise SQL com PostgreSQL SQL. Este artigo descreve os metadados de tabelas estrangeiras, o comportamento das consultas e os controles de sessão para esta funcionalidade de Federated Analytics .
Importante
Fabric HorizonDB está em prévia pública. Use a extensão gerenciada por serviço e a configuração de conexão fornecida para seu banco de dados. Instruções que instalam a extensão, requerem acesso de superusuário PostgreSQL ou substituem um servidor externo gerenciado não se aplicam ao serviço gerenciado.
Para um procedimento, consulte Consultar dados Fabric de um banco de dados HorizonDB. Para erros e etapas de recuperação, consulte Solucionar problemas de consultas federadas.
Opções de conexão e metadados
O servidor externo gerenciado possui duas opções de conexão:
| Option | Meaning |
|---|---|
endpoint |
O nome de host Fabric simples, sem porta ou tcp: prefixo. |
database |
O banco de dados padrão do warehouse ou endpoint de análise SQL. |
O wrapper usa uma conexão nativa do Tabular Data Stream (TDS), não um nome de fonte de dados (DSN) ou cadeia de conexão do Open Database Connectivity (ODBC). Conecte-se como criador do banco de dados e confirme o acesso do Microsoft Entra à fonte. Você não passa um token em SQL. Não altere servidores gerenciados por serviços nem mapeamentos de usuários.
O servidor padrão fabric_dw tem como alvo o endpoint de análise SQL espelhado do próprio banco de dados. Para um armazém separado, crie um servidor de propriedade do cliente com CREATE SERVER ... FOREIGN DATA WRAPPER pg_fabric_fdw OPTIONS (endpoint '...', database '...'). Copie o nome do host e do banco de dados SQL dasstringsde Conexão de Configurações> do depósito. O nome do banco de dados SQL pode diferir do nome de exibição do item Fabric. Consulte Registrar uma fonte separada de armazém.
Opções de importação
IMPORT FOREIGN SCHEMA Lê o catálogo de origem e cria metadados locais. O esquema local deve já existir. Use LIMIT TO para selecionar tabelas ou EXCEPT para excluí-las.
| Option | Meaning |
|---|---|
database_name |
Seleciona outro banco de dados SQL consultável acessível pela conexão Fabric selecionada em vez do banco de dados padrão. Não descobre espaços de trabalho arbitrários. |
mirror_schema |
Associa cada tabela importada a uma fonte de estatísticas locais com o mesmo nome, definindo sua mirror_of opção. A fonte deve atender aos requisitos das estatísticas locais do planejador. |
Por exemplo, importe uma tabela de outro banco de dados no espaço de trabalho:
CREATE SCHEMA IF NOT EXISTS fabric_sales;
IMPORT FOREIGN SCHEMA analytics
LIMIT TO (customer_signals)
FROM SERVER fabric_dw
INTO fabric_sales
OPTIONS (database_name 'sales_analytics');
Substitua os nomes pelo seu servidor de origem e pelo servidor gerenciado. A opção não concede acesso ao outro banco de dados nem descobre espaços de trabalho arbitrários. Um endpoint diferente pode exigir um servidor separado de propriedade do cliente.
Filtros de importação correspondem a nomes exatos. Cite um nome de maiúsculas e minúsculas, como "CustomerSignals". Um esquema ausente, visibilidade insuficiente do catálogo, uma seleção vazia ou um tipo remoto não suportado podem falhar na importação.
Opções de tabela estrangeira e coluna
Use uma definição manual quando precisar de um subconjunto de colunas ou de um nome local diferente:
CREATE FOREIGN TABLE fabric_sales.customer_signal_scores (
customer_id bigint,
score numeric(5, 2) OPTIONS (column_name 'risk_score')
)
SERVER fabric_dw
OPTIONS (
database_name 'sales_analytics',
schema_name 'analytics',
table_name 'customer_signals'
);
Este exemplo assume que a fonte possui essas colunas e tipos correspondentes. Verifique a definição de origem em vez de inferir um tipo a partir de valores de amostra.
| Option | Scope | Meaning |
|---|---|---|
schema_name |
Tabela estrangeira; obrigatório | O esquema remoto. |
table_name |
Tabela estrangeira; obrigatório | A mesa remota. |
database_name |
Tabela estrangeira; opcional | Outro banco de dados consultável acessível pela conexão Fabric selecionada. |
mirror_of |
Tabela estrangeira; opcional | Uma tabela local qualificada pelo esquema ou uma visualização materializada usada apenas para estatísticas. |
column_name |
Coluna; opcional | O nome exato da coluna remota. Sem ele, o nome local é usado. |
Colunas importadas mantêm seus nomes remotos através de column_name. Defina esta opção antes de renomear uma coluna definida manualmente que ainda não a tenha. Caso contrário, uma renomeação local altera qual coluna remota o wrapper solicita. Uma diferença entre nomes de colunas locais e remotos impede o pushdown completo de consultas, embora as partes elegíveis ainda possam ser executadas remotamente.
Alterar ou eliminar metadados de tabelas estrangeiras pertencentes ao cliente não altera a tabela remota nem suas linhas.
Mapeamentos de tipo de dados
Prefira IMPORT FOREIGN SCHEMA obter o mapeamento de tipos da fonte.
| Tipo de coluna Fabric | Tipo de coluna PostgreSQL |
|---|---|
bit |
boolean |
tinyint, smallint |
smallint |
int |
integer |
bigint |
bigint |
real |
real |
float |
double precision |
decimal(p,s), numeric(p,s) |
numeric(p,s) |
date |
date |
time(p) |
time |
datetime2(p) |
timestamp |
datetimeoffset(p) |
timestamptz |
char(n), nchar(n) |
char(n) |
varchar(n), nvarchar(n) |
varchar(n) |
varchar(max) |
text |
varbinary(n), varbinary(max) |
bytea |
O wrapper também suporta colunas UUID. Use o mapeamento importado ou verifique a representação de origem antes de declarar uma uuid coluna. Uma coluna binária não é necessariamente um UUID.
Esses limites afetam importações e expressões:
- Os remotos
time,datetime2, edatetimeoffsetas colunas suportam no máximo seis dígitos fracionários de segundo. Importação rejeita uma precisão remota de sete. - Cálculos numéricos exatos Fabric suportam até 38 dígitos. Definições numéricas mais amplas do PostgreSQL não podem participar de expressões reprimidas.
- Tipos de colunas remotas não mapeadas falham na importação. Busque JSON armazenado como dados de string como
text, e aplique funções JSON PostgreSQL localmente. - Casts UUID rodam no PostgreSQL porque os motores aceitam representações de string diferentes. A igualdade no UUID ainda pode pressionar para baixo.
- Expressões dependentes do fuso horário, como
date::timestamptz, são executadas localmente para preservar as regras do fuso horário do PostgreSQL. - Literal de encontros fora de intervalo, datas BC, infinito e
TIME '24:00:00'permanecer local. Datas construídas remotamente ainda podem falhar se seu valor calculado ficar fora do intervalo suportado pelo Fabric.
Query pushdown
O wrapper traduz operações elegíveis do PostgreSQL para T-SQL. Fabric avalia essas operações e retorna as linhas de resultados. Outras operações podem ser executadas no PostgreSQL sobre as linhas retornadas, ou a consulta pode falhar se não puder ser traduzida com segurança.
| Forma de consulta | Behavior |
|---|---|
Projeção, filtros, ordenação, LIMIT, e OFFSET |
Pode ser executado no Fabric quando as expressões são suportadas. |
| Junções entre tabelas estrangeiras elegíveis em um único servidor | Pode ser executado como uma única junção remota, incluindo entre bancos de dados acessíveis quando suportados pela conexão. |
| Uma junção entre uma tabela local e uma tabela estrangeira | Utiliza planejamento local e verificações remotas elegíveis. Uma chave local seletiva pode parametrizar uma varredura remota; entradas mais amplas podem exigir uma junção local. |
count, sum, avg, min, e max |
Pode rodar em Fabric.
count Usa COUNT_BIG; entradas inteiras para sum são ampliadas quando necessário. |
Funções de janela suportadas, como row_number, rank, lag, e lead |
Pressione para baixo quando toda a consulta for executada no Fabric. Em uma consulta mista, eles rodam localmente. |
array_agg, json_agge jsonb_agg |
Execute localmente sobre uma varredura remota porque o Fabric não possui um tipo de resultado correspondente. |
| Funções somente PostgreSQL ou expressões de data não suportadas | Pode ser executado localmente ou produzir um erro de construção não suportada. O recurso local não é garantido para todas as expressões. |
| Predicados de expressões regulares e expressões recursivas de tabelas comuns | Não são suportados. |
Escreve, COPY em uma tabela estrangeira, FOR UPDATE, e FOR SHARE |
Não são suportados. Tabelas estrangeiras são somente de leitura. |
Execute EXPLAIN (VERBOSE) na consulta propriamente dita. A Fabric SQL linha mostra o SQL planejado para o Fabric. Nós locais de agregado, joine ou ordenação mostram onde o PostgreSQL conclui o trabalho. O nó de Materialize um cursor sozinho não implica computação local de consulta.
Por padrão, EXPLAIN sem ANALYZE não entra em contato com Fabric.
EXPLAIN ANALYZE executa a consulta.
Planos estimados remotos
Ative o plano remoto para sua sessão:
SET fabric_fdw.remote_explain = ON;
EXPLAINagora entra em contato com o Fabric para obter um plano estimado de execução sem executar o SQL remoto. A identidade remota precisa de permissão para executar a instrução e SHOWPLAN permissão em cada banco de dados referenciado. Sem essas permissões, EXPLAIN falha.
A saída inclui uma Fabric Plan árvore. Os custos do Fabric usam unidades diferentes dos custos do PostgreSQL. Mesmo com EXPLAIN ANALYZE, o plano aninhado do Fabric permanece estimado em vez de fornecer contadores reais por operador. Uma varredura parametrizada pode informar que seu plano remoto foi ignorado porque os valores dos parâmetros de runtime ainda não estão disponíveis.
Restaure o padrão quando terminar:
RESET fabric_fdw.remote_explain;
Diferenças de comportamento entre motores
Pushdown não garante resultados equivalentes ao PostgreSQL para toda expressão. O motor que realiza uma comparação ou cálculo aplica suas próprias regras.
| Operation | Diferença e orientação |
|---|---|
| Comparação de textos, ordenação, agrupamento e junções | Operações remotas utilizam a ordenação de armazém. Uma declaração local COLLATE não altera os resultados já calculados pelo Fabric. Valide maiúsculas e minúsculas, acentos e ordem de triagem. |
| Ordenação de UUID e predicados de intervalo | Fabric e PostgreSQL classificam UUIDs de forma diferente. Igualdade, IN, e agrupamento concordam. Veja regras de comparação de UUIDs. |
| Média dos inteiros | Uma média inteira impulsionada pode descartar a fração. Use avg(column_name::numeric) quando o resultado fracionário for necessário. |
| Comprimento do texto com espaços finais | A função de comprimento remoto omite espaços finais. Use length(column_name \|\| '\|') - 1 para contá-los. |
| Preenchimento de caracteres de comprimento fixo | O Fabric pode manter o preenchimento onde o PostgreSQL o corta durante a conversão. Use rtrim quando o acolchoamento for preciso ser removido. |
Casts numérico-para-inteiro em .5 |
As regras de arredondamento diferem. Use round(value)::integer para comportamento de meio afastamento do zero e verifique o intervalo inteiro alvo antes de lançar. |
LIKE Padrões |
O T-SQL trata os parênteses como sintaxe de padrão e não usa o escape implícito de barra inversa do PostgreSQL. Use um caractere de escape explícito, como LIKE 'a#%b' ESCAPE '#' para um sinal literal de porcentagem. |
| Cálculos semanais e dias da semana | As configurações do calendário Fabric podem diferir das regras de semana ISO do PostgreSQL. Valide week, dow, e truncamento semanal em relação ao calendário comercial requerido. |
| Cálculos de alta precisão | Resultados exatos grandes podem ultrapassar 38 dígitos. Alguns resultados de potência, expoentes e divisão usam precisão de ponto flutuante. Não presuma resultados numéricos exatos do PostgreSQL. |
| Um conjunto de agrupamento vazio sobre entrada vazia | Fabric não pode retornar linhas onde PostgreSQL retorna uma linha de som. Teste entradas vazias explicitamente. |
O Import pode alertar que uma ordenação de texto Fabric não foi verificada como compatível com a ordenação do banco de dados PostgreSQL. O aviso aparece no máximo uma vez por importação e reporta contagens em vez dos nomes das colunas afetadas. Não é prova de que a importação terminou ou de que uma comparação específica será diferente. Inspecione a ordenação de origem e os valores representativos de teste.
Regras de comparação de UUID
fabric_fdw.uuid_fabric_semantics usa como padrão ON. Ele permite comparações de UUID do Fabric onde a consulta pode empurra-las para baixo. Um plano misto ainda pode ordenar UUIDs localmente, então a ordem resultante pode depender do plano.
Use a ordenação PostgreSQL quando sua aplicação exigir intervalo consistente de UUID PostgreSQL e comportamento de ordenação:
SET fabric_fdw.uuid_fabric_semantics = OFF;
O filtro ou ordenação relevante agora roda localmente. Isso pode aumentar o número de linhas transferidas. A configuração afeta apenas UUIDs, não a ordenação de texto.
Controles de sessão
Use os controles expostos pela versão da extensão lançada e pelas permissões.
| Setting | Default | Effect |
|---|---|---|
fabric_fdw.max_retrieved_rows |
0 |
Sem limite por padrão. Um valor positivo rejeita uma varredura estrangeira se as linhas recuperadas estimadas excederem o limite. Esse não é um limite exato de linhas em tempo de execução. |
fabric_fdw.max_batch_memory |
256 kB |
Um valor positivo permite o agrupamento de resultados.
0 Traz uma fileira de cada vez. O intervalo permitido é 0 através de 1024 kB; o limite efetivo de memória também é limitado por work_mem. Alterar essa configuração requer o privilégio de parâmetro SET aplicável. |
fabric_fdw.remote_explain |
OFF |
Adiciona o plano estimado de execução do Fabric e EXPLAIN requer permissões remotas do plano. |
fabric_fdw.enable_query_labels |
OFF |
Adiciona um rótulo exclusivo a cada consulta remota e a reporta em um PostgreSQL NOTICE. |
fabric_fdw.uuid_fabric_semantics |
ON |
Permite semântica de comparação com UUID do Fabric onde essas operações podem ser empurradas para baixo. |
Configure statement_timeout antes de iniciar uma verificação. O wrapper o captura para leituras remotas quando a varredura começa; alterá-lo durante a varredura não altera esse valor capturado. A limpeza de consultas pode continuar após o cancelamento. Para mais detalhes, veja Cancelamento e intervalos.
Correlacione uma consulta com o histórico do Fabric
Habilite etiquetas antes de executar uma consulta:
SET fabric_fdw.enable_query_labels = ON;
SELECT count(*)
FROM fabric_mirror.orders;
Grave a gravadora a partir do NOTICE. Uma consulta PostgreSQL pode emitir múltiplas consultas remotas, cada uma com um rótulo separado.
Execute a seguinte consulta contra o depósito de origem, não contra o endpoint PostgreSQL do banco de dados HorizonDB:
SELECT
distributed_statement_id,
label,
start_time
FROM queryinsights.exec_requests_history
WHERE label = '<query-label>';
O rótulo e distributed_statement_id são identificadores diferentes. O histórico pode levar até 15 minutos para aparecer. O acesso depende das permissões do seu armazém. Para mais informações, consulte Insights de consulta.
Restaurar o padrão após coletar os rótulos:
RESET fabric_fdw.enable_query_labels;
Estatísticas de planejadores locais
A opção opcional mirror_of de tabela estrangeira identifica uma tabela local permanente ou uma visualização materializada que o PostgreSQL amostra durante ANALYZE. O wrapper não cria nem atualiza essa fonte de estatísticas, e as consultas ainda lêem linhas do Fabric.
Esta opção não é espelhamento de banco de dados Fabric e não sincroniza dados. Mantenha linhas locais representativas por meio do seu próprio processo de carregamento aprovado.
A fonte estatística deve:
- Seja uma tabela permanente ou uma vista materializada, não uma tabela temporária ou uma vista comum.
- Use um nome qualificado pelo esquema em
mirror_of. - Corresponda às colunas não descartadas da tabela estrangeira por contagem, ordem e tipo PostgreSQL.
- Corresponda a modificadores de tipo declarados, como comprimento de caracteres ou precisão numérica e escala.
Os nomes das colunas podem diferir porque a correspondência é posicional.
IMPORT FOREIGN SCHEMA ... OPTIONS (mirror_schema 'analytics_stats') define mirror_of para cada tabela importada usando o mesmo nome de tabela em analytics_stats.
Depois de preencher ou atualizar uma fonte de estatísticas correspondente, execute ANALYZE na tabela estrangeira pertencente ao cliente. Alterar a fonte local não atualiza metadados de tabelas estrangeiras nem dados remotos.