Referência do SQL do Spark para exibições materializadas do lago

Este artigo fornece a sintaxe do SQL do Spark para criar, listar, renomear e deletar vistas de lagos materializadas no Fabric.

Criar uma exibição materializada do lago

Você pode definir uma vista materializada do lago de qualquer tabela ou de outra vista materializada do lago dentro de uma casa de lago.

Sintaxe

CREATE [OR REPLACE] MATERIALIZED LAKE VIEW [IF NOT EXISTS] [workspace.lakehouse.schema].MLV_Identifier 
[( 
    CONSTRAINT constraint_name1 CHECK (condition expression1) [ON MISMATCH DROP | FAIL],  
    CONSTRAINT constraint_name2 CHECK (condition expression2) [ON MISMATCH DROP | FAIL] 
)]
[(
    REFRESH_HINT <hint_name> UNIQUE (<column1> [, <column2>, ...])
)]
[PARTITIONED BY (col1, col2, ... )] 
[COMMENT "description or comment"] 
[TBLPROPERTIES ("key1"="val1", "key2"="val2", ... )] 
AS select_statement 

Arguments

Exemplos

O exemplo a seguir cria uma vista materializada de lago com uma restrição de qualidade de dados, um comentário e particionamento. A cláusula OR REPLACE substitui qualquer visualização existente com o mesmo nome.

CREATE OR REPLACE MATERIALIZED LAKE VIEW silver.cleaned_order_data
(
    CONSTRAINT valid_quantity CHECK (quantity > 0) ON MISMATCH DROP
)
PARTITIONED BY (category)
COMMENT "Cleaned order data joined from products and orders"
AS SELECT 
    p.productID,
    p.productName,
    p.category,
    o.orderDate,
    o.quantity,
    o.totalAmount
FROM bronze.products p INNER JOIN bronze.orders o
ON p.productID = o.productID

O exemplo a seguir cria uma exibição de lago materializada mais simples. A cláusula IF NOT EXISTS impede um erro se a vista já existir, tornando-o seguro para scripts de implantação.

CREATE MATERIALIZED LAKE VIEW IF NOT EXISTS silver.products_with_sales AS
SELECT 
    p.productID,
    p.productName,
    p.category,
    CASE  
        WHEN COUNT(o.orderID) OVER (PARTITION BY p.productID) > 0 THEN TRUE  
        ELSE FALSE  
        END AS has_sales 
FROM bronze.products p LEFT JOIN bronze.orders o 
ON p.productID = o.productID

Ingerir arquivos com USING OneLake_Files

Além de definir uma visualização de lago materializado a partir de tabelas, você pode definir uma que ingere arquivos CSV ou Parquet diretamente do OneLake. Uma exibição de ingestão de arquivos usa USING OneLake_Files com uma pasta física do OneLake, um atalho para pasta do OneLake ou um caminho para um único arquivo. Você pode opcionalmente usar uma cláusula AS SELECT sem FROM para filtrar, estruturar e agregar os dados de origem à medida que são ingeridos.

A tabela a seguir mostra qual sintaxe se aplica a cada estilo de autoria:

Sintaxe

CREATE [OR REPLACE] MATERIALIZED LAKE VIEW [IF NOT EXISTS] [workspace.lakehouse.schema].MLV_Identifier
[(
    CONSTRAINT constraint_name CHECK (condition) ON MISMATCH DROP | FAIL
)]
USING OneLake_Files
OPTIONS (
    'format' = 'csv' | 'parquet',
    'path'   = 'abfss://<workspace>@<host>/<lakehouse>/Files/<folder-or-file>',
    ['header' = 'true' | 'false',]
    ['delimiter' = '<char>',]
    [...]
)
[PARTITIONED BY (column_name [, ...])]
[COMMENT "description"]
[TBLPROPERTIES (
    'schema_mode'  = 'DYNAMIC' | 'FIXED',
    'refresh_mode' = 'APPEND_ONLY' | 'FULL' | 'MIRROR'
)]
[AS SELECT select_expression [...] [WHERE condition]
    [GROUP BY expression [, ...]] [HAVING condition]]

Referência de OPTIONS

Referência de TBLPROPERTIES

Example

O exemplo a seguir carrega uma pasta de arquivos CSV com linha de cabeçalho em uma visão bronze. Cada linha também recebe uma __filepath__ coluna que registra o arquivo fonte de onde foi lida.

CREATE MATERIALIZED LAKE VIEW bronze.raw_orders
USING OneLake_Files
OPTIONS (
    'format' = 'csv',
    'path'   = 'abfss://SalesWorkspace@onelake.dfs.fabric.microsoft.com/SalesLake.Lakehouse/Files/orders/',
    'header' = 'true'
)
TBLPROPERTIES (
    'schema_mode'  = 'DYNAMIC',
    'refresh_mode' = 'APPEND_ONLY'
);

Você pode então construir vistas de lagos materializados a jusante e ouro que selecionam entre bronze.raw_orders; Fabric registra a dependência e as atualiza em ordem. Para rastrear arquivos pelo pipeline, veja Gerenciar a linhagem de vistas de lagos materializadas do Fabric.

Filtre, transforme e valide arquivos durante a ingestão

Use um AS SELECT sem cláusula FROM para selecionar colunas, filtrar linhas, converter valores, adicionar colunas calculadas, agregar dados ou aplicar funções de janela. Restrições de ingestão de arquivos são executadas contra a saída projetada, então uma restrição pode referenciar um alias calculado.

O exemplo a seguir captura linhas malformadas, aplica uma regra de qualidade de dados em nível de linha, filtra a entrada e particiona a saída materializada:

CREATE MATERIALIZED LAKE VIEW silver.valid_orders
(
    CONSTRAINT positive_amount
        CHECK (order_amount > 0) ON MISMATCH DROP
)
USING OneLake_Files
OPTIONS (
    'format' = 'csv',
    'path' = 'abfss://SalesWorkspace@onelake.dfs.fabric.microsoft.com/SalesLake.Lakehouse/Files/orders/',
    'header' = 'true',
    'multiLine' = 'true',
    'dateFormat' = 'MM/dd/yyyy',
    'timestampFormat' = 'MM/dd/yyyy HH:mm:ss',
    'encoding' = 'ISO-8859-1',
    'comment' = '#',
    'columnNameOfCorruptRecord' = '_corrupt_record'
)
PARTITIONED BY (region)
COMMENT "Valid orders ingested from CSV"
TBLPROPERTIES (
    'schema_mode' = 'DYNAMIC',
    'refresh_mode' = 'FULL'
)
AS SELECT
    order_id,
    region,
    CAST(amount AS DECIMAL(18,2)) AS order_amount,
    CASE WHEN amount >= 1000 THEN 'high' ELSE 'standard' END AS order_band,
    _corrupt_record,
    __filepath__,
    current_timestamp() AS ingested_at;

Consultar as linhas capturadas para inspeção ou remediação:

SELECT
    _corrupt_record,
    __filepath__,
    ingested_at
FROM silver.valid_orders
WHERE _corrupt_record IS NOT NULL;

Você também pode criar resultados agregados ou materializados em janelas diretamente a partir de arquivos:

CREATE MATERIALIZED LAKE VIEW gold.sales_by_region
USING OneLake_Files
OPTIONS (
    'format' = 'parquet',
    'path' = 'abfss://SalesWorkspace@onelake.dfs.fabric.microsoft.com/SalesLake.Lakehouse/Files/sales/'
)
TBLPROPERTIES ('schema_mode' = 'DYNAMIC', 'refresh_mode' = 'FULL')
AS SELECT
    region,
    COUNT(*) AS order_count,
    SUM(amount) AS total_amount,
    AVG(amount) AS average_amount
GROUP BY region
HAVING SUM(amount) > 0;

As expressões compatíveis incluem operações aritméticas padrão do Spark SQL, funções de agregação, funções estatísticas, funções de janela e funções de classificação.

Ingerir um único arquivo

Defina path para um arquivo CSV ou Parquet em vez de uma pasta. Uma origem de arquivo único usa a semântica de atualização FULL, de modo que, ao substituir o arquivo, o resultado materializado também é substituído.

CREATE MATERIALIZED LAKE VIEW bronze.monthly_snapshot
USING OneLake_Files
OPTIONS (
    'format' = 'parquet',
    'path' = 'abfss://SalesWorkspace@onelake.dfs.fabric.microsoft.com/SalesLake.Lakehouse/Files/snapshots/2026-08.parquet'
)
TBLPROPERTIES (
    'schema_mode' = 'FIXED',
    'refresh_mode' = 'FULL'
);

Obter uma lista de vistas materializadas do lago

Para obter a lista de todas as exibições materializadas do lago em um esquema, use a seguinte sintaxe:

SHOW MATERIALIZED LAKE VIEWS <IN/FROM> Schema_Name;

Por exemplo, para listar todas as visões de lago materializadas no esquema silver.

SHOW MATERIALIZED LAKE VIEWS IN silver;

Recuperar a instrução que criou uma exibição materializada do lago

Para obter a CREATE instrução de uma exibição de lago materializada, use a seguinte sintaxe:

SHOW CREATE MATERIALIZED LAKE VIEW MLV_Identifier;

Por exemplo, para recuperar a definição de products_with_sales:

SHOW CREATE MATERIALIZED LAKE VIEW products_with_sales;

Atualizar uma exibição materializada do lago

Para modificar a definição de uma exibição de lago materializada (como a SELECT consulta, restrições ou particionamento), use o comando CREATE OR REPLACE . Como alternativa, você pode excluir a exibição existente e recriá-la.

Renomear uma exibição materializada do lago

Para renomear uma exibição de lago materializada existente, use o ALTER MATERIALIZED LAKE VIEW comando. A sintaxe é:

ALTER MATERIALIZED LAKE VIEW MLV_Identifier RENAME TO MLV_Identifier_New;

Por exemplo, para renomear products_with_sales:

ALTER MATERIALIZED LAKE VIEW products_with_sales RENAME TO products_with_sales_v2;

Excluir uma exibição materializada do lago

Você pode excluir uma exibição materializada do lago usando a opção Excluir no gerenciador de objetos lakehouse ou executando um DROP comando. A sintaxe é:

DROP MATERIALIZED LAKE VIEW MLV_Identifier;

Por exemplo, para excluir products_with_sales:

DROP MATERIALIZED LAKE VIEW products_with_sales;

Limitações atuais

As seguintes limitações se aplicam às instruções SQL do Spark para exibições de lago materializadas:

• Não há suporte para nomes de esquema — nomes de esquema em letras maiúsculas (por exemplo, MYSCHEMA) . Use maiúsculas ou minúsculas mistas.
• Nenhuma instrução DML (linguagem de manipulação de dados) – você não pode executar instruções de INSERT, UPDATE ou DELETE contra uma vista materializada do lago de dados. Os dados são preenchidos somente pela SELECT consulta na definição.
• Nenhuma consulta de viagem no tempo — a SELECT consulta em uma definição de visualização materializada do lago não pode usar a sintaxe de viagem no tempo do Delta Lake (por exemplo, VERSION AS OF ou TIMESTAMP AS OF).
• As funções definidas pelo usuário (UDFs) não são suportadas na consulta que define um modo de exibição de lago materializado.
• Sem vistas temporárias como fontes – a SELECT consulta pode referenciar tabelas e outras vistas de lago materializadas, mas não vistas temporárias.
• As propriedades do Spark no nível da sessão — as propriedades de configuração do Spark definidas no nível da sessão (por exemplo, spark.conf.set(...)) não são aplicadas durante uma atualização agendada. Em vez disso, defina propriedades no nível do lakehouse ou do workspace.
• Ingestão de arquivos — Visualizações de ingestimento de arquivos suportam apenas CSV e Parquet. Uma exibição de FIXED-schema falha se a pasta de origem contiver arquivos com esquemas diferentes na criação. Caminhos de origem não podem conter espaços. Atalhos de pasta do OneLake podem ser usados como fontes, mas a atualização gerenciada não detecta recursivamente arquivos adicionados em pastas de atalho aninhadas.

Conteúdo relacionado

• O que são visualizações de lago materializadas no Microsoft Fabric?
• Qualidade dos dados em exibições de lago materializadas
• Atualização ideal para vistas materializadas do lago