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.
Aplica-se a:✅ Endpoint de análise de SQL e Armazém de Dados no Microsoft Fabric
Neste artigo, você aprenderá a consultar arquivos JSON usando Fabric SQL, incluindo o Fabric Data Warehouse e o endpoint de análise SQL.
JSON (JavaScript Object Notation) é um formato leve para dados semiestruturados, amplamente usado em Big Data para fluxos de sensor, configurações de IoT, logs e dados geoespaciais (por exemplo, GeoJSON).
Usar OPENROWSET para consultar arquivos JSON diretamente
No Fabric Data Warehouse e no ponto de extremidade de análise SQL para um Lakehouse, você pode consultar arquivos JSON diretamente no lago usando a função OPENROWSET.
OPENROWSET( BULK '{{filepath}}', [ , <options> ... ])
[ WITH ( <column schema and mappings> ) ];
Ao consultar arquivos JSON com OPENROWSET, você começa especificando o caminho do arquivo, que pode ser uma URL direta ou um padrão curinga direcionado a um ou mais arquivos. Por padrão, o Fabric projeta cada propriedade de nível superior no documento JSON como uma coluna separada no conjunto de resultados. Para arquivos JSON Lines, cada linha é tratada como uma linha individual, tornando-a ideal para cenários de streaming.
Se você precisar de mais controle:
- Use a cláusula opcional
WITHpara definir o esquema explicitamente e mapear colunas para propriedades JSON específicas, incluindo caminhos aninhados. - Use
DATA_SOURCEpara fazer referência a um local raiz para caminhos relativos. - Configure parâmetros de tratamento de erros, como
MAXERRORSpara gerenciar problemas de análise de forma elegante.
Casos comuns de uso de arquivo JSON
Tipos de arquivo JSON comuns e casos de uso que você pode manipular no Microsoft Fabric:
- Arquivos JSON delimitados por linha ("Linhas JSON") em que cada linha é um documento JSON autônomo e válido (por exemplo, um evento, uma leitura ou uma entrada de log).
- O arquivo inteiro não é necessariamente um único documento JSON válido, é uma sequência de objetos JSON separados por caracteres de nova linha.
- Os arquivos com esse formato normalmente têm extensões
.jsonl,.ldjsonou.ndjson. Ideal para cenários de streaming e somente acréscimo—os escritores podem adicionar um novo evento como uma nova linha sem reescrever o arquivo ou quebrar a estrutura.
- Arquivos JSON de documento único ("JSON clássico") com a extensão
.jsononde todo o arquivo é um documento JSON válido, um único objeto ou uma matriz de objetos (potencialmente aninhados).- Normalmente, ele é usado para configuração, instantâneos e conjuntos de dados exportados em um único arquivo.
- Por exemplo, os arquivos GeoJSON geralmente armazenam um único objeto JSON que descreve os recursos e suas geometrias.
Consultar arquivos JSONL com OPENROWSET
O Fabric Data Warehouse e o ponto de extremidade de análise do SQL para Lakehouse permitem que os desenvolvedores de SQL consultem arquivos JSON Lines (.jsonl, .ldjson, .ndjson) diretamente do data lake usando a função OPENROWSET.
Esses arquivos contêm um objeto JSON válido por linha, tornando-os ideais para cenários somente de streaming e acréscimo.
Para ler um arquivo JSON Lines, forneça sua URL no BULK argumento:
SELECT TOP 10 *
FROM OPENROWSET(
BULK 'https://pandemicdatalake.blob.core.windows.net/public/curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.jsonl'
);
Por padrão, OPENROWSET usa inferência de esquema, descobrindo automaticamente todas as propriedades de nível superior em cada objeto JSON e retornando-as como colunas.
No entanto, você pode definir explicitamente o esquema para controlar quais propriedades são retornadas e substituir tipos de dados inferidos:
SELECT TOP 10 *
FROM OPENROWSET(
BULK 'https://pandemicdatalake.blob.core.windows.net/public/curated/covid-19/bing_covid-19_data/latest/bing_covid-19_data.jsonl'
) WITH (
country_region VARCHAR(100),
confirmed INT,
date_reported DATE '$.updated'
);
A definição de esquema explícita é útil quando:
- Você deseja substituir os tipos inferidos padrão (por exemplo, para forçar o tipo de dados de data em vez de varchar).
- Você precisa de nomes de coluna estáveis e projeção seletiva.
- Você deseja mapear colunas para propriedades JSON específicas, incluindo caminhos aninhados.
Ler estruturas JSON complexas (aninhadas) com OPENROWSET
O Fabric Data Warehouse e o ponto de extremidade de análise do SQL para Lakehouse permitem que os desenvolvedores de SQL leiam JSON com objetos aninhados ou subarrays diretamente do lago usando OPENROWSET.
{
"type": "Feature",
"properties": {
"shapeName": "Serbia",
"shapeISO": "SRB",
"shapeID": "94879208B25563984444888",
"shapeGroup": "SRB",
"shapeType": "ADM0"
}
}
No exemplo a seguir, consulte um arquivo que contém dados de exemplo e use a WITH cláusula para projetar explicitamente suas propriedades de nível folha:
SELECT
*
FROM
OPENROWSET(
BULK '/Files/parquet/nested/geojson.jsonl'
)
WITH (
-- Top-level field
[type] VARCHAR(50),
-- Leaf properties from the nested "properties" object
shapeName VARCHAR(200) '$.properties.shapeName',
shapeISO VARCHAR(50) '$.properties.shapeISO',
shapeID VARCHAR(200) '$.properties.shapeID',
shapeGroup VARCHAR(50) '$.properties.shapeGroup',
shapeType VARCHAR(50) '$.properties.shapeType'
);
Observação
Este exemplo usa um caminho relativo sem uma fonte de dados, que funciona ao consultar arquivos em seu Lakehouse por meio de seu endpoint de análise SQL. No Fabric Data Warehouse, você deve escolher entre as seguintes opções:
- Usar um caminho absoluto para o arquivo ou
- Especifique uma URL raiz em uma fonte de dados externa e referencie-a na
OPENROWSETinstrução por meio da opçãoDATA_SOURCE.
Expandir matrizes aninhadas (JSON para linhas) com OPENROWSET
O Fabric Data Warehouse e o ponto de extremidade de análise do SQL para Lakehouse permitem ler arquivos JSON com matrizes aninhadas usando OPENROWSET. Em seguida, você pode expandir (desnudar) essas matrizes usando CROSS APPLY OPENJSON. Esse método é útil quando um documento de nível superior contém um subarray que você deseja transformar em uma linha por elemento.
Na seguinte entrada de exemplo simplificada, um documento semelhante a GeoJSON tem uma matriz de recursos:
{
"type": "FeatureCollection",
"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:OGC:1.3:CRS84" } },
"features": [
{
"type": "Feature",
"properties": {
"shapeName": "Serbia",
"shapeISO": "SRB",
"shapeID": "94879208B25563984444888",
"shapeGroup": "SRB",
"shapeType": "ADM0"
},
"geometry": {
"type": "Line",
"coordinates": [[[19.6679328, 46.1848744], [19.6649294, 46.1870428], [19.6638492, 46.1890231]]]
}
}
]
}
A seguinte consulta:
- Lê o documento JSON do lago usando
OPENROWSET, projetando a propriedade de tipo de nível superior junto com a matriz de recursos brutos. -
CROSS APPLY OPENJSONaplica-se para expandir a matriz de características para que cada elemento se torne uma linha individual no conjunto de resultados. Dentro dessa expansão, a consulta extrai valores aninhados usando expressões de caminho JSON. Valores comoshapeName,shapeISOe detalhes comogeometryegeometry.typecoordinates, agora são colunas simples para uma análise mais fácil.
SELECT
r.crs_name,
f.[type] AS feature_type,
f.shapeName,
f.shapeISO,
f.shapeID,
f.shapeGroup,
f.shapeType,
f.geometry_type,
f.coordinates
FROM
OPENROWSET(
BULK '/Files/parquet/nested/geojson.jsonl'
)
WITH (
crs_name VARCHAR(100) '$.crs.properties.name', -- top-level nested property
features VARCHAR(MAX) '$.features' -- raw JSON array
) AS r
CROSS APPLY OPENJSON(r.features)
WITH (
[type] VARCHAR(50),
shapeName VARCHAR(200) '$.properties.shapeName',
shapeISO VARCHAR(50) '$.properties.shapeISO',
shapeID VARCHAR(200) '$.properties.shapeID',
shapeGroup VARCHAR(50) '$.properties.shapeGroup',
shapeType VARCHAR(50) '$.properties.shapeType',
geometry_type VARCHAR(50) '$.geometry.type',
coordinates VARCHAR(MAX) '$.geometry.coordinates'
) AS f;