Resolver problemas do conjunto de SQL sem servidor no Azure Synapse Analytics

  • Artigo

Este artigo contém informações sobre como solucionar os problemas mais frequentes com o pool SQL sem servidor no Azure Synapse Analytics.

Para saber mais sobre o Azure Synapse Analytics, consulte Visão geral e O que há de novo no Azure Synapse Analytics?.

Synapse Studio

Synapse Studio é uma ferramenta fácil de usar que você pode usar para acessar seus dados usando um navegador sem a necessidade de instalar ferramentas de acesso ao banco de dados. O Synapse Studio não foi projetado para ler um grande conjunto de dados ou gerenciamento completo de objetos SQL.

O pool SQL sem servidor está acinzentado no Synapse Studio

Se o Synapse Studio não conseguir estabelecer uma conexão com o pool SQL sem servidor, você notará que o pool SQL sem servidor está acinzentado ou mostra o status Offline.

Normalmente, esse problema ocorre por um dos dois motivos:

  • Sua rede impede a comunicação com o back-end do Azure Synapse Analytics. O caso mais frequente é que a porta TCP 1443 está bloqueada. Para que o pool SQL sem servidor funcione, desbloqueie essa porta. Outros problemas podem impedir que o pool SQL sem servidor também funcione. Para obter mais informações, consulte o Guia de solução de problemas.
  • Você não tem permissão para entrar no pool SQL sem servidor. Para obter acesso, um administrador de espaço de trabalho do Azure Synapse deve adicioná-lo à função de administrador de espaço de trabalho ou à função de administrador SQL. Para obter mais informações, consulte Controle de acesso do Azure Synapse.

Conexão Websocket fechada inesperadamente

Sua consulta pode falhar com a mensagem Websocket connection was closed unexpectedly. de erro Esta mensagem significa que a conexão do navegador com o Synapse Studio foi interrompida, por exemplo, devido a um problema de rede.

  • Para resolver esse problema, execute novamente a consulta.
  • Experimente o Azure Data Studio ou o SQL Server Management Studio para as mesmas consultas em vez do Synapse Studio para investigação adicional.
  • Se esta mensagem ocorrer frequentemente no seu ambiente, obtenha ajuda do administrador da rede. Você também pode verificar as configurações do firewall e verificar o Guia de solução de problemas.
  • Se o problema persistir, crie um tíquete de suporte por meio do portal do Azure.

Bancos de dados sem servidor não são mostrados no Synapse Studio

Se você não vir os bancos de dados criados no pool SQL sem servidor, verifique se o pool SQL sem servidor foi iniciado. Se o pool SQL sem servidor for desativado, os bancos de dados não serão exibidos. Execute qualquer consulta, por exemplo, SELECT 1no pool SQL sem servidor para ativá-lo e fazer com que os bancos de dados apareçam.

Synapse Serverless SQL pool mostra como indisponível

A configuração de rede incorreta geralmente é a causa desse comportamento. Verifique se as portas estão configuradas corretamente. Se você usa um firewall ou pontos de extremidade privados, verifique essas configurações também.

Por fim, certifique-se de que as funções apropriadas foram concedidas e não foram revogadas.

Não é possível criar novo banco de dados, pois a solicitação usará a chave antiga/expirada

Este erro é causado pela alteração da chave gerenciada pelo cliente do espaço de trabalho usada para criptografia. Você pode optar por criptografar novamente todos os dados no espaço de trabalho com a versão mais recente da chave ativa. Para criptografar novamente, altere a chave no portal do Azure para uma chave temporária e, em seguida, alterne de volta para a chave que você deseja usar para criptografia. Saiba aqui como gerir as chaves da área de trabalho.

O pool SQL sem servidor Synapse não está disponível após a transferência de uma assinatura para um locatário diferente do Microsoft Entra

Se você moveu uma assinatura para outro locatário do Microsoft Entra, poderá ter alguns problemas com o pool SQL sem servidor. Crie um tíquete de suporte e o suporte do Azure entrará em contato com você para resolver o problema.

Acesso ao armazenamento

Se você receber erros enquanto tenta acessar arquivos no armazenamento do Azure, verifique se você tem permissão para acessar dados. Deve ser capaz de aceder a ficheiros disponíveis publicamente. Se você tentar acessar dados sem credenciais, certifique-se de que sua identidade do Microsoft Entra possa acessar diretamente os arquivos.

Se você tiver uma chave de assinatura de acesso compartilhado que deve usar para acessar arquivos, certifique-se de ter criado uma credencial de nível de servidor ou de escopo de banco de dados que contenha essa credencial. As credenciais são necessárias se você precisar acessar dados usando a identidade gerenciada do espaço de trabalho e o SPN (nome da entidade de serviço) personalizado.

Não é possível ler, listar ou acessar arquivos no Armazenamento do Azure Data Lake

Se você usar um login do Microsoft Entra sem credenciais explícitas, certifique-se de que sua identidade do Microsoft Entra possa acessar os arquivos no armazenamento. Para acessar os arquivos, sua identidade do Microsoft Entra deve ter a permissão Leitor de Dados de Blob ou permissões para Lista e Listas de Controle de Acesso de Leitura(ACL) no ADLS. Para obter mais informações, consulte Falha na consulta porque o arquivo não pode ser aberto.

Se você acessar o armazenamento usando credenciais, verifique se sua identidade gerenciada ou SPN tem a função de Leitor de Dados ou Colaborador ou permissões de ACL específicas. Se você usou um token de assinatura de acesso compartilhado, verifique se ele tem rl permissão e se não expirou.

Se você usar um logon SQL e a OPENROWSET função sem uma fonte de dados, verifique se você tem uma credencial no nível do servidor que corresponde ao URI de armazenamento e tem permissão para acessar o armazenamento.

A consulta falha porque o arquivo não pode ser aberto

Se sua consulta falhar com o erro File cannot be opened because it does not exist or it is used by another process e você tiver certeza de que ambos os arquivos existem e não são usados por outro processo, o pool SQL sem servidor não poderá acessar o arquivo. Esse problema geralmente acontece porque sua identidade do Microsoft Entra não tem direitos para acessar o arquivo ou porque um firewall está bloqueando o acesso ao arquivo.

Por padrão, o pool SQL sem servidor tenta acessar o arquivo usando sua identidade do Microsoft Entra. Para resolver esse problema, você deve ter direitos adequados para acessar o arquivo. A maneira mais fácil é conceder a si mesmo uma função de Colaborador de Dados de Blob de Armazenamento na conta de armazenamento que você está tentando consultar.

Para obter mais informações, consulte:

Alternativa à função de Colaborador de Dados de Blob de Armazenamento

Em vez de conceder a si mesmo uma função de Colaborador de Dados de Blob de Armazenamento, você também pode conceder permissões mais granulares em um subconjunto de arquivos.

Todos os usuários que precisam acessar alguns dados neste contêiner também devem ter permissão EXECUTE em todas as pastas pai até a raiz (o contêiner).

Saiba mais sobre como definir ACLs no Azure Data Lake Storage Gen2.

Nota

A permissão de execução no nível do contêiner deve ser definida no Azure Data Lake Storage Gen2. As permissões na pasta podem ser definidas no Azure Synapse.

Se você quiser consultar data2.csv neste exemplo, as seguintes permissões são necessárias:

  • Executar permissão no contêiner
  • Executar permissão na pasta1
  • permissão de Ler sobre data2.csv

Diagrama que mostra a estrutura de permissão no data lake.

  1. Entre no Azure Synapse com um usuário administrador que tenha permissões totais nos dados que você deseja acessar.

  2. No painel de dados, clique com o botão direito do mouse no arquivo e selecione Gerenciar acesso.

    Captura de tela que mostra a opção gerenciar acesso.

  3. Selecione pelo menos a permissão de leitura . Insira o UPN ou o ID do objeto do usuário, por exemplo, user@contoso.com. Selecione Adicionar.

  4. Conceda permissão de leitura para este usuário.

    Captura de tela que mostra a concessão de permissões de leitura.

Nota

Para usuários convidados, essa etapa precisa ser feita diretamente com o Azure Data Lake porque não pode ser feita diretamente por meio do Azure Synapse.

O conteúdo do diretório no caminho não pode ser listado

Esse erro indica que o usuário que está consultando o Azure Data Lake não pode listar os arquivos no armazenamento. Há vários cenários em que esse erro pode acontecer:

  • O usuário do Microsoft Entra que está usando a autenticação de passagem do Microsoft Entra não tem permissão para listar os arquivos no Armazenamento Data Lake.
  • O usuário do Microsoft Entra ID ou SQL que está lendo dados usando uma chave de assinatura de acesso compartilhado ou identidade gerenciada pelo espaço de trabalho e essa chave ou identidade não tem permissão para listar os arquivos no armazenamento.
  • O usuário que está acessando dados do Dataverse que não tem permissão para consultar dados no Dataverse. Esse cenário pode acontecer se você usar usuários SQL.
  • O usuário que está acessando o Delta Lake pode não ter permissão para ler o log de transações do Delta Lake.

A maneira mais fácil de resolver esse problema é conceder a si mesmo a função de Colaborador de Dados de Blob de Armazenamento na conta de armazenamento que você está tentando consultar.

Para obter mais informações, consulte:

O conteúdo da tabela Dataverse não pode ser listado

Se você estiver usando o Azure Synapse Link for Dataverse para ler as tabelas DataVerse vinculadas, precisará usar a conta do Microsoft Entra para acessar os dados vinculados usando o pool SQL sem servidor. Para obter mais informações, consulte Azure Synapse Link for Dataverse with Azure Data Lake.

Se você tentar usar um logon SQL para ler uma tabela externa que está fazendo referência à tabela DataVerse, você receberá o seguinte erro: External table '???' is not accessible because content of directory cannot be listed.

As tabelas externas do Dataverse sempre usam a autenticação de passagem do Microsoft Entra. Não é possível configurá-los para usar uma chave de assinatura de acesso compartilhado ou uma identidade gerenciada pelo espaço de trabalho.

O conteúdo do log de transações do Delta Lake não pode ser listado

O seguinte erro é retornado quando o pool SQL sem servidor não consegue ler a pasta de log de transações Delta Lake:

Content of directory on path 'https://.....core.windows.net/.../_delta_log/*.json' cannot be listed.

Verifique se a _delta_log pasta existe. Talvez você esteja consultando arquivos Parquet simples que não são convertidos para o formato Delta Lake. Se a _delta_log pasta existir, certifique-se de que tem a permissão Ler e Listar nas pastas Delta Lake subjacentes. Tente ler arquivos json diretamente usando FORMAT='csv'. Coloque seu URI no parâmetro BULL:

select top 10 *
from openrowset(BULK 'https://.....core.windows.net/.../_delta_log/*.json',FORMAT='csv', FIELDQUOTE = '0x0b', FIELDTERMINATOR ='0x0b',ROWTERMINATOR = '0x0b')  
with (line varchar(max)) as logs

Se essa consulta falhar, o chamador não terá permissão para ler os arquivos de armazenamento subjacentes.

Execução da consulta

Você pode obter erros durante a execução da consulta nos seguintes casos:

A consulta falha porque não pode ser executada devido a restrições de recursos atuais

Sua consulta pode falhar com a mensagem This query cannot be executed due to current resource constraints. de erro Esta mensagem significa que o pool SQL sem servidor não pode ser executado neste momento. Aqui estão algumas opções de solução de problemas:

Limite de tempo de consulta excedido

O erro Query timeout expired será retornado se a consulta for executada por mais de 30 minutos no pool SQL sem servidor. Esse limite para pool SQL sem servidor não pode ser alterado.

  • Tente otimizar a sua consulta aplicando as melhores práticas.
  • Tente materializar partes de suas consultas usando create external table as select (CETAS).
  • Verifique se há uma carga de trabalho simultânea em execução no pool SQL sem servidor, pois as outras consultas podem receber os recursos. Nesse caso, você pode dividir a carga de trabalho em vários espaços de trabalho.

Nome do objeto inválido

O erro Invalid object name 'table name' indica que você está usando um objeto, como uma tabela ou exibição, que não existe no banco de dados do pool SQL sem servidor. Experimente estas opções:

  • Liste as tabelas ou exibições e verifique se o objeto existe. Use o SQL Server Management Studio ou o Azure Data Studio porque o Synapse Studio pode mostrar algumas tabelas que não estão disponíveis no pool SQL sem servidor.

  • Se você vir o objeto, verifique se está usando algum agrupamento de banco de dados binário/diferencia maiúsculas de minúsculas. Talvez o nome do objeto não corresponda ao nome que você usou na consulta. Com um agrupamento de banco de dados binário, Employee e employee são dois objetos diferentes.

  • Se você não vir o objeto, talvez esteja tentando consultar uma tabela de um lago ou banco de dados do Spark. A tabela pode não estar disponível no pool SQL sem servidor porque:

    • A tabela tem alguns tipos de coluna que não podem ser representados no pool SQL sem servidor.
    • A tabela tem um formato que não é suportado no pool SQL sem servidor. Exemplos são Avro ou ORC.

Dados binários ou de cadeia de caracteres seriam truncados

Este erro acontece se o comprimento da cadeia de caracteres ou do tipo de coluna binária (por exemplo VARCHAR, , VARBINARYou NVARCHAR) for menor do que o tamanho real dos dados que você está lendo. Você pode corrigir esse erro aumentando o comprimento do tipo de coluna:

  • Se a coluna de cadeia de caracteres for definida como o VARCHAR(32) tipo e o texto tiver 60 caracteres, use o VARCHAR(60) tipo (ou mais) no esquema de coluna.
  • Se você estiver usando a inferência de esquema (sem o WITH esquema), todas as colunas de cadeia de caracteres serão definidas automaticamente como o VARCHAR(8000) tipo. Se você estiver recebendo esse erro, defina explicitamente o esquema em uma WITH cláusula com o tipo de coluna maior VARCHAR(MAX) para resolver esse erro.
  • Se a tabela estiver no banco de dados Lake, tente aumentar o tamanho da coluna de cadeia de caracteres no pool do Spark.
  • SET ANSI_WARNINGS OFF Tente habilitar o pool SQL sem servidor para truncar automaticamente os valores VARCHAR, se isso não afetar suas funcionalidades.

Aspas não fechadas após a cadeia de caracteres

Em casos raros, quando você usa o operador LIKE em uma coluna de cadeia de caracteres ou alguma comparação com os literais de cadeia de caracteres, você pode obter o seguinte erro:

Unclosed quotation mark after the character string

Esse erro pode acontecer se você usar o Latin1_General_100_BIN2_UTF8 agrupamento na coluna. Tente definir Latin1_General_100_CI_AS_SC_UTF8 o agrupamento na coluna em vez do Latin1_General_100_BIN2_UTF8 agrupamento para resolver o problema. Se o erro ainda for retornado, levante uma solicitação de suporte por meio do portal do Azure.

Não foi possível alocar espaço tempdb durante a transferência de dados de uma distribuição para outra

O erro Could not allocate tempdb space while transferring data from one distribution to another é retornado quando o mecanismo de execução da consulta não pode processar dados e transferi-los entre os nós que estão executando a consulta. É um caso especial de falha na consulta genérica porque não pode ser executada devido a um erro de restrições de recursos atuais. Este erro é retornado quando os recursos alocados para o tempdb banco de dados são insuficientes para executar a consulta.

Aplique as práticas recomendadas antes de enviar um tíquete de suporte.

A consulta falha com um erro ao lidar com um arquivo externo (contagem máxima de erros atingida)

Se sua consulta falhar com a mensagem error handling external file: Max errors count reachedde erro , isso significa que há uma incompatibilidade de um tipo de coluna especificado e os dados que precisam ser carregados.

Para obter mais informações sobre o erro e quais linhas e colunas examinar, altere a versão do analisador de 2.0 para 1.0.

Exemplo

Se você quiser consultar o arquivo names.csv com esta Consulta 1, o pool SQL sem servidor do Azure Synapse retorna com o seguinte erro: Error handling external file: 'Max error count reached'. File/External table name: [filepath]. Por exemplo:

O ficheiro names.csv contém:

Id,first name,  
1, Adam
2,Bob
3,Charles
4,David
5,Eva

Consulta 1:

SELECT
    TOP 100 *
FROM
    OPENROWSET(
        BULK '[FILE-PATH OF CSV FILE]',
        FORMAT = 'CSV',
        PARSER_VERSION='2.0',
       FIELDTERMINATOR =';',
       FIRSTROW = 2
    )  
    WITH (
    [ID] SMALLINT,  
    [Text] VARCHAR (1) COLLATE Latin1_General_BIN2  
)

    AS [result]

Motivo

Assim que a versão do analisador é alterada da versão 2.0 para 1.0, as mensagens de erro ajudam a identificar o problema. A nova mensagem de erro é agora Bulk load data conversion error (truncation) for row 1, column 2 (Text) in data file [filepath].

O truncamento informa que o tipo de coluna é muito pequeno para caber nos dados. O primeiro nome mais longo neste names.csv arquivo tem sete caracteres. O tipo de dados a ser utilizado deve ser, no mínimo, VARCHAR(7). O erro é causado por esta linha de código:

    [Text] VARCHAR (1) COLLATE Latin1_General_BIN2

Alterar a consulta de acordo resolve o erro. Após a depuração, altere a versão do analisador para 2.0 novamente para obter o máximo desempenho.

Para obter mais informações sobre quando usar qual versão do analisador, consulte Usar OPENROWSET usando pool SQL sem servidor no Synapse Analytics.

SELECT
    TOP 100 *
FROM
    OPENROWSET(
        BULK '[FILE-PATH OF CSV FILE]',
        FORMAT = 'CSV',
        PARSER_VERSION='2.0',
        FIELDTERMINATOR =';',
        FIRSTROW = 2
    )  
    WITH (
    [ID] SMALLINT,  
    [Text] VARCHAR (7) COLLATE Latin1_General_BIN2  
)

    AS [result]

Não é possível carregar em massa porque o arquivo não pôde ser aberto

O erro Cannot bulk load because the file could not be opened é retornado se um arquivo for modificado durante a execução da consulta. Normalmente, você pode receber um erro como Cannot bulk load because the file {file path} could not be opened. Operating system error code 12. (The access code is invalid.)

Os pools SQL sem servidor não podem ler arquivos que estão sendo modificados enquanto a consulta está em execução. A consulta não pode ser bloqueada nos ficheiros. Se você sabe que a operação de modificação é acrescentar, você pode tentar definir a seguinte opção: {"READ_OPTIONS":["ALLOW_INCONSISTENT_READS"]}.

Para obter mais informações, consulte como consultar arquivos somente acréscimo ou criar tabelas em arquivos somente acréscimo.

A consulta falha com erro de conversão de dados

Sua consulta pode falhar com a mensagem Bulk load data conversion error (type mismatches or invalid character for the specified code page) for row n, column m [columnname] in the data file [filepath]. de erro Esta mensagem significa que seus tipos de dados não corresponderam aos dados reais para o número da linha n e a coluna m.

Por exemplo, se você espera apenas inteiros em seus dados, mas na linha n há uma cadeia de caracteres, essa mensagem de erro é a que você receberá.

Para resolver esse problema, inspecione o arquivo e os tipos de dados escolhidos. Verifique também se as configurações do delimitador de linha e do terminador de campo estão corretas. O exemplo a seguir mostra como a inspeção pode ser feita usando VARCHAR como o tipo de coluna.

Para obter mais informações sobre terminadores de campo, delimitadores de linha e caracteres de aspas de escape, consulte Consultar arquivos CSV.

Exemplo

Se você quiser consultar o arquivo names.csv:

Id, first name,  
1,Adam
2,Bob
3,Charles
4,David
five,Eva

Com a seguinte consulta:

Consulta 1:

SELECT
    TOP 100 *
FROM
    OPENROWSET(
        BULK '[FILE-PATH OF CSV FILE]',
        FORMAT = 'CSV',
        PARSER_VERSION='1.0',
       FIELDTERMINATOR =',',
       FIRSTROW = 2
    )  
    WITH (
    [ID] SMALLINT,  
    [Firstname] VARCHAR (25) COLLATE Latin1_General_BIN2  
)

    AS [result]

O pool SQL sem servidor do Azure Synapse retorna o erro Bulk load data conversion error (type mismatch or invalid character for the specified code page) for row 6, column 1 (ID) in data file [filepath].

É necessário navegar pelos dados e tomar uma decisão informada para lidar com este problema. Para examinar os dados que causam esse problema, o tipo de dados precisa ser alterado primeiro. Em vez de consultar a coluna ID com o tipo de dados SMALLINT, VARCHAR(100) agora é usado para analisar esse problema.

Com esta Consulta 2 ligeiramente alterada, os dados podem agora ser processados para devolver a lista de nomes.

Consulta 2:

SELECT
    TOP 100 *
FROM
    OPENROWSET(
        BULK '[FILE-PATH OF CSV FILE]',
        FORMAT = 'CSV',
        PARSER_VERSION='1.0',
       FIELDTERMINATOR =',',
       FIRSTROW = 2
    )  
    WITH (
    [ID] VARCHAR(100),  
    [Firstname] VARCHAR (25) COLLATE Latin1_General_BIN2  
)

    AS [result]

Você pode observar que os dados têm valores inesperados para ID na quinta linha. Nessas circunstâncias, é importante alinhar com o proprietário da empresa dos dados para concordar sobre como dados corrompidos como este exemplo podem ser evitados. Se a prevenção não for possível ao nível da aplicação, o VARCHAR de tamanho razoável pode ser a única opção aqui.

Gorjeta

Tente tornar VARCHAR() o mais curto possível. Evite VARCHAR(MAX) se possível, pois pode prejudicar o desempenho.

O resultado da consulta não parece o esperado

Sua consulta pode não falhar, mas você pode ver que seu conjunto de resultados não está conforme o esperado. As colunas resultantes podem estar vazias ou dados inesperados podem ser retornados. Nesse cenário, é provável que um delimitador de linha ou terminador de campo tenha sido escolhido incorretamente.

Para resolver esse problema, dê outra olhada nos dados e altere essas configurações. Depurar essa consulta é fácil, como mostra o exemplo a seguir.

Exemplo

Se você quiser consultar o arquivo names.csv com a consulta na Consulta 1, o pool SQL sem servidor do Azure Synapse retorna com um resultado que parece estranho:

Em names.csv:

Id,first name,  
1, Adam
2, Bob
3, Charles
4, David
5, Eva

SELECT
    TOP 100 *
FROM
    OPENROWSET(
        BULK '[FILE-PATH OF CSV FILE]',
        FORMAT = 'CSV',
        PARSER_VERSION='1.0',
       FIELDTERMINATOR =';',
       FIRSTROW = 2
    )  
    WITH (
    [ID] VARCHAR(100),  
    [Firstname] VARCHAR (25) COLLATE Latin1_General_BIN2  
)

    AS [result]

| ID            |   Firstname   |  
| ------------- |-------------  |  
| 1,Adam        | NULL |  
| 2,Bob         | NULL |  
| 3,Charles     | NULL |  
| 4,David       | NULL |  
| 5,Eva         | NULL |

Parece não haver nenhum valor na coluna Firstname. Em vez disso, todos os valores acabaram ficando na ID coluna. Esses valores são separados por uma vírgula. O problema foi causado por esta linha de código porque é necessário escolher a vírgula em vez do símbolo ponto-e-vírgula como terminador de campo:

FIELDTERMINATOR =';',

Alterar esse único caractere resolve o problema:

FIELDTERMINATOR =',',

O conjunto de resultados criado pela Consulta 2 agora tem a aparência esperada:

Consulta 2:

SELECT
    TOP 100 *
FROM
    OPENROWSET(
        BULK '[FILE-PATH OF CSV FILE]',
        FORMAT = 'CSV',
        PARSER_VERSION='1.0',
       FIELDTERMINATOR =',',
       FIRSTROW = 2
    )  
    WITH (
    [ID] VARCHAR(100),  
    [Firstname] VARCHAR (25) COLLATE Latin1_General_BIN2  
)

    AS [result]

Devoluções:

| ID            | Firstname   |  
| ------------- |-------------  |  
| 1             | Adam |  
| 2             | Bob |  
| 3             | Charles |  
| 4             | David |  
| 5             | Eva |

A coluna do tipo não é compatível com o tipo de dados externos

Se sua consulta falhar com a mensagem Column [column-name] of type [type-name] is not compatible with external data type […], de erro, é provável que um tipo de dados PARQUET tenha sido mapeado para um tipo de dados SQL incorreto.

Por exemplo, se o seu arquivo Parquet tiver um preço de coluna com números flutuantes (como 12,89) e você tentou mapeá-lo para INT, essa mensagem de erro é a que você receberá.

Para resolver esse problema, inspecione o arquivo e os tipos de dados escolhidos. Esta tabela de mapeamento ajuda a escolher um tipo de dados SQL correto. Como prática recomendada, especifique o mapeamento apenas para colunas que, de outra forma, seriam resolvidas no tipo de dados VARCHAR. Evitar o VARCHAR quando possível leva a um melhor desempenho nas consultas.

Exemplo

Se você quiser consultar o arquivo taxi-data.parquet com esta Consulta 1, o pool SQL sem servidor do Azure Synapse retorna o seguinte erro:

O ficheiro taxi-data.parquet contém:

|PassengerCount |SumTripDistance|AvgTripDistance |
|---------------|---------------|----------------|
| 1 | 2635668.66000064 | 6.72731710678951 |
| 2 | 172174.330000005 | 2.97915543404919 |
| 3 | 296384.390000011 | 2.8991352022851  |
| 4 | 12544348.58999806| 6.30581582240281 |
| 5 | 13091570.2799993 | 111.065989028627 |

Consulta 1:

SELECT
    *
FROM
    OPENROWSET(
        BULK '<filepath>taxi-data.parquet',
        FORMAT='PARQUET'
    )  WITh
        (
        PassengerCount INT,  
        SumTripDistance INT,  
        AVGTripDistance FLOAT
        )

    AS [result]

Column 'SumTripDistance' of type 'INT' is not compatible with external data type 'Parquet physical type: DOUBLE', please try with 'FLOAT'. File/External table name: '<filepath>taxi-data.parquet'.

Essa mensagem de erro informa que os tipos de dados não são compatíveis e vem com a sugestão de usar FLOAT em vez de INT. O erro é causado por esta linha de código:

SumTripDistance INT,

Com esta Consulta 2 ligeiramente alterada, os dados podem agora ser processados e mostram as três colunas:

Consulta 2:

SELECT
    *
FROM
    OPENROWSET(
        BULK '<filepath>taxi-data.parquet',
        FORMAT='PARQUET'
    )  WITh
        (
        PassengerCount INT,  
        SumTripDistance FLOAT,  
        AVGTripDistance FLOAT
        )

    AS [result]

A consulta faz referência a um objeto que não é suportado no modo de processamento distribuído

O erro The query references an object that is not supported in distributed processing mode indica que você usou um objeto ou função que não pode ser usado enquanto consulta dados no Armazenamento do Azure ou no armazenamento analítico do Azure Cosmos DB.

Alguns objetos, como exibições do sistema e funções, não podem ser usados enquanto você consulta dados armazenados no Azure Data Lake ou no armazenamento analítico do Azure Cosmos DB. Evite usar as consultas que unem dados externos com exibições do sistema, carregar dados externos em uma tabela temporária ou usar algumas funções de segurança ou metadados para filtrar dados externos.

Falha ao chamar WaitlOCompletion

A mensagem WaitIOCompletion call failed de erro indica que a consulta falhou enquanto aguardava para concluir a operação de E/S que lê dados do armazenamento remoto, Azure Data Lake.

A mensagem de erro tem o seguinte padrão: Error handling external file: 'WaitIOCompletion call failed. HRESULT = ???'. File/External table name...

Certifique-se de que seu armazenamento seja colocado na mesma região do pool SQL sem servidor. Verifique as métricas de armazenamento e verifique se não há outras cargas de trabalho na camada de armazenamento, como o upload de novos arquivos, que possam saturar as solicitações de E/S.

O campo HRESULT contém o código do resultado. Os códigos de erro a seguir são os mais comuns, juntamente com suas possíveis soluções.

Esse código de erro significa que o arquivo de origem não está armazenado.

Há razões pelas quais esse código de erro pode acontecer:

  • O ficheiro foi eliminado por outra aplicação.
    • Nesse cenário comum, a execução da consulta é iniciada, enumera os arquivos e os arquivos são encontrados. Mais tarde, durante a execução da consulta, um arquivo é excluído. Por exemplo, ele pode ser excluído pelo Databricks, Spark ou Azure Data Factory. A consulta falha porque o arquivo não foi encontrado.
  • Esse problema também pode ocorrer com o formato Delta. A consulta pode ser bem-sucedida na nova tentativa porque há uma nova versão da tabela e o arquivo excluído não é consultado novamente.
  • Um plano de execução inválido é armazenado em cache.
    • Como mitigação temporária, execute o comando DBCC FREEPROCCACHE. Se o problema persistir, crie um tíquete de suporte.

Sintaxe incorreta perto de NOT

O erro Incorrect syntax near 'NOT' indica que existem algumas tabelas externas com colunas que contêm a restrição NOT NULL na definição de coluna.

  • Atualize a tabela para remover NOT NULL da definição de coluna.
  • Por vezes, este erro também pode ocorrer de forma transitória com tabelas criadas a partir de uma instrução CETAS. Se o problema não for resolvido, você pode tentar soltar e recriar a tabela externa.

A coluna de partição retorna valores NULL

Se sua consulta retornar valores NULL em vez de particionar colunas ou não conseguir encontrar as colunas de partição, você terá algumas etapas de solução de problemas possíveis:

  • Se você usar tabelas para consultar um conjunto de dados particionado, lembre-se de que as tabelas não oferecem suporte ao particionamento. Substitua a tabela pelos modos de exibição particionados.
  • Se você usar as exibições particionadas com o OPENROWSET que consulta arquivos particionados usando a função FILEPATH(), certifique-se de especificar corretamente o padrão curinga no local e usar o índice adequado para referenciar o curinga.
  • Se você estiver consultando os arquivos diretamente na pasta particionada, esteja ciente de que as colunas de particionamento não são as partes das colunas de arquivo. Os valores de particionamento são colocados nos caminhos da pasta e não nos arquivos. Por esse motivo, os arquivos não contêm os valores de particionamento.

Inserir valor em lote para tipo de coluna DATETIME2 falhou

O erro Inserting value to batch for column type DATETIME2 failed indica que o pool sem servidor não pode ler os valores de data dos arquivos subjacentes. O valor datetime armazenado no arquivo Parquet ou Delta Lake não pode ser representado como uma DATETIME2 coluna.

Inspecione o valor mínimo no arquivo usando o Spark e verifique se algumas datas são menores que 0001-01-03. Se você armazenou os arquivos usando a versão Spark 2.4 (versão de tempo de execução sem suporte) ou com a versão superior do Spark que ainda usa o formato de armazenamento datetime herdado, os valores datetime anteriores são gravados usando o calendário juliano que não está alinhado com o calendário gregoriano proléptico usado em pools SQL sem servidor.

Pode haver uma diferença de dois dias entre o calendário juliano usado para escrever os valores no Parquet (em algumas versões do Spark) e o calendário gregoriano proléptico usado no pool SQL sem servidor. Essa diferença pode causar a conversão para um valor de data negativo, que é inválido.

Tente usar o Spark para atualizar esses valores porque eles são tratados como valores de data inválidos no SQL. O exemplo a seguir mostra como atualizar os valores que estão fora dos intervalos de datas SQL para NULL no Delta Lake:

from delta.tables import *
from pyspark.sql.functions import *

deltaTable = DeltaTable.forPath(spark,  
             "abfss://my-container@myaccount.dfs.core.windows.net/delta-lake-data-set")
deltaTable.update(col("MyDateTimeColumn") < '0001-02-02', { "MyDateTimeColumn": null } )

Essa alteração remove os valores que não podem ser representados. Os outros valores de data podem estar carregados corretamente, mas representados incorretamente porque ainda há uma diferença entre os calendários gregoriano juliano e proléptico. Você pode ver mudanças de data inesperadas, mesmo para as datas anteriores 1900-01-01 , se você usar o Spark 3.0 ou versões mais antigas.

Considere migrar para o Spark 3.1 ou superior e mudar para o calendário gregoriano proléptico. As versões mais recentes do Spark usam por padrão um calendário gregoriano proléptico alinhado com o calendário no pool SQL sem servidor. Recarregue seus dados herdados com a versão superior do Spark e use a seguinte configuração para corrigir as datas:

spark.conf.set("spark.sql.legacy.parquet.int96RebaseModeInWrite", "CORRECTED")

Falha na consulta devido a uma alteração de topologia ou falha de contêiner de computação

Esse erro pode indicar que algum problema de processo interno aconteceu no pool SQL sem servidor. Registre um tíquete de suporte com todos os detalhes necessários que podem ajudar a equipe de suporte do Azure a investigar o problema.

Descreva qualquer coisa que possa ser incomum em comparação com a carga de trabalho normal. Por exemplo, talvez houvesse um grande número de solicitações simultâneas ou uma carga de trabalho ou consulta especial começasse a ser executada antes que esse erro acontecesse.

Expansão curinga atingiu o tempo limite

Conforme descrito na seção Consultar pastas e vários arquivos, o pool SQL sem servidor oferece suporte à leitura de vários arquivos/pastas usando curingas. Há um limite máximo de 10 curingas por consulta. Você deve estar ciente de que essa funcionalidade tem um custo. Leva tempo para o pool sem servidor listar todos os arquivos que podem corresponder ao curinga. Isso introduz latência e essa latência pode aumentar se o número de arquivos que você está tentando consultar for alto. Neste caso, você pode se deparar com o seguinte erro:

"Wildcard expansion timed out after X seconds."

Há várias etapas de mitigação que você pode fazer para evitar isso:

  • Aplique as práticas recomendadas descritas em Pool SQL sem servidor de práticas recomendadas.
  • Tente reduzir o número de arquivos que você está tentando consultar, compactando arquivos em arquivos maiores. Tente manter os tamanhos dos ficheiros acima dos 100MB.
  • Certifique-se de que os filtros sobre colunas de particionamento são usados sempre que possível.
  • Se você estiver usando o formato de arquivo delta, use o recurso otimizar gravação no Spark. Isso pode melhorar o desempenho das consultas, reduzindo a quantidade de dados que precisam ser lidos e processados. Como usar otimizar a gravação é descrito em Usando otimizar a gravação no Apache Spark.
  • Para evitar alguns dos curingas de nível superior codificando efetivamente os filtros implícitos sobre colunas de particionamento, use SQL dinâmico.

Coluna ausente ao usar a inferência automática de esquema

Você pode facilmente consultar arquivos sem conhecer ou especificar o esquema, omitindo a cláusula WITH. Nesse caso, os nomes das colunas e os tipos de dados serão inferidos a partir dos ficheiros. Tenha em mente que, se você estiver lendo o número de arquivos ao mesmo tempo, o esquema será inferido a partir do primeiro serviço de arquivos obtido do armazenamento. Isso pode significar que algumas das colunas esperadas são omitidas, tudo porque o arquivo usado pelo serviço para definir o esquema não continha essas colunas. Para especificar explicitamente o esquema, use a cláusula OPENROWSET WITH. Se você especificar o esquema (usando a tabela externa ou a cláusula OPENROWSET WITH), o modo de caminho lax padrão será usado. Isso significa que as colunas que não existem em alguns arquivos serão retornadas como NULLs (para linhas desses arquivos). Para entender como o modo de caminho é usado, verifique a documentação e o exemplo a seguir.

Configuração

Os pools SQL sem servidor permitem que você use o T-SQL para configurar objetos de banco de dados. Existem algumas restrições:

  • Não é possível criar objetos em master bancos de dados e/ lakehouse ou Spark.
  • Você deve ter uma chave mestra para criar credenciais.
  • Você deve ter permissão para fazer referência aos dados usados nos objetos.

Não é possível criar um banco de dados

Se você receber o erro CREATE DATABASE failed. User database limit has been already reached., criou o número máximo de bancos de dados suportados em um espaço de trabalho. Para obter mais informações, consulte Restrições.

  • Se você precisar separar os objetos, use esquemas dentro dos bancos de dados.
  • Se você precisar fazer referência ao armazenamento do Azure Data Lake, crie bancos de dados lakehouse ou bancos de dados Spark que serão sincronizados no pool SQL sem servidor.

A criação ou alteração da tabela falhou porque o tamanho mínimo da linha excede o tamanho máximo permitido da linha da tabela de 8060 bytes

Qualquer tabela pode ter até 8 KB de tamanho por linha (não incluindo dados VARCHAR(MAX)/VARBINARY(MAX) fora da linha). Se criar uma tabela em que o tamanho total das células na linha exceda 8060 bytes, obterá o seguinte erro:

Msg 1701, Level 16, State 1, Line 3
Creating or altering table '<table name>' failed because the minimum row size would be <???>,
including <???> bytes of internal overhead.
This exceeds the maximum allowable table row size of 8060 bytes.

Esse erro também pode acontecer no banco de dados Lake se você criar uma tabela do Spark com os tamanhos de coluna que excedem 8060 bytes e o pool SQL sem servidor não puder criar uma tabela que faça referência aos dados da tabela do Spark.

Como atenuação, evite usar os tipos de tamanho fixo como CHAR(N) e substitua-os por tipos de tamanho VARCHAR(N) variável, ou diminua o tamanho no CHAR(N). Consulte Limitação de grupo de linhas de 8KB no SQL Server.

Crie uma chave mestra no banco de dados ou abra a chave mestra na sessão antes de executar esta operação

Se sua consulta falhar com a mensagem Please create a master key in the database or open the master key in the session before performing this operation.de erro , isso significa que seu banco de dados de usuários não tem acesso a uma chave mestra no momento.

Muito provavelmente, você criou um novo banco de dados de usuários e ainda não criou uma chave mestra.

Para resolver esse problema, crie uma chave mestra com a seguinte consulta:

CREATE MASTER KEY [ ENCRYPTION BY PASSWORD ='strongpasswordhere' ];

Nota

Substitua 'strongpasswordhere' por um segredo diferente aqui.

A instrução CREATE não é suportada no banco de dados mestre

Se sua consulta falhar com a mensagem Failed to execute query. Error: CREATE EXTERNAL TABLE/DATA SOURCE/DATABASE SCOPED CREDENTIAL/FILE FORMAT is not supported in master database.de erro , isso significa que o master banco de dados no pool SQL sem servidor não suporta a criação de:

  • Tabelas externas.
  • Fontes de dados externas.
  • Credenciais com escopo de banco de dados.
  • Formatos de arquivo externos.

Aqui está a solução:

  1. Crie um banco de dados de usuários:

    CREATE DATABASE <DATABASE_NAME>

  2. Execute uma instrução CREATE no contexto de DATABASE_NAME>, que falhou anteriormente para o master banco de <dados.

    Aqui está um exemplo da criação de um formato de arquivo externo:

    USE <DATABASE_NAME>
CREATE EXTERNAL FILE FORMAT [SynapseParquetFormat]  
WITH ( FORMAT_TYPE = PARQUET)

Não é possível criar o login ou usuário do Microsoft Entra

Se você receber um erro ao tentar criar um novo login ou usuário do Microsoft Entra em um banco de dados, verifique o login usado para se conectar ao seu banco de dados. O login que está tentando criar um novo usuário do Microsoft Entra deve ter permissão para acessar o domínio do Microsoft Entra e verificar se o usuário existe. Esteja ciente de que:

  • Os logons SQL não têm essa permissão, portanto, você sempre receberá esse erro se usar a autenticação SQL.
  • Se você usar um login do Microsoft Entra para criar novos logons, verifique se você tem permissão para acessar o domínio do Microsoft Entra.

Azure Cosmos DB

Os pools SQL sem servidor permitem que você consulte o armazenamento analítico do Azure Cosmos DB usando a OPENROWSET função. Verifique se o contêiner do Azure Cosmos DB tem armazenamento analítico. Certifique-se de que especificou corretamente a conta, o banco de dados e o nome do contêiner. Além disso, certifique-se de que sua chave de conta do Azure Cosmos DB é válida. Para obter mais informações, veja os Pré-requisitos.

Não é possível consultar o Azure Cosmos DB usando a função OPENROWSET

Se você não puder se conectar à sua conta do Azure Cosmos DB, verifique os pré-requisitos. Possíveis erros e ações de solução de problemas estão listados na tabela a seguir.

Erro Causa raiz
Erros de sintaxe:
- Sintaxe incorreta perto de OPENROWSET.
- ... não é uma opção de provedor reconhecida BULK OPENROWSET .
- Sintaxe incorreta perto de ....		 Possíveis causas profundas:
- Não usar o Azure Cosmos DB como o primeiro parâmetro.
- Usando um literal de cadeia de caracteres em vez de um identificador no terceiro parâmetro.
- Não especificar o terceiro parâmetro (nome do contêiner).
Ocorreu um erro na cadeia de conexão do Azure Cosmos DB. - A conta, o banco de dados ou a chave não são especificados.
- Uma opção em uma cadeia de conexão não é reconhecida.
- Um ponto-e-vírgula (;) é colocado no final de uma cadeia de conexão.
A resolução do caminho do Azure Cosmos DB falhou com o erro "Nome da conta incorreto" ou "Nome incorreto do banco de dados". O nome da conta, o nome do banco de dados ou o contêiner especificados não podem ser encontrados ou o armazenamento analítico não foi habilitado para a coleção especificada.
A resolução do caminho do Azure Cosmos DB falhou com o erro "Valor secreto incorreto" ou "O segredo é nulo ou vazio". A chave da conta não é válida ou está ausente.

O aviso de agrupamento UTF-8 é devolvido durante a leitura dos tipos de cadeia de carateres do Azure Cosmos DB

O pool SQL sem servidor retorna um aviso em tempo de compilação se o OPENROWSET agrupamento de colunas não tiver codificação UTF-8. Você pode alterar facilmente o agrupamento padrão para todas as OPENROWSET funções em execução no banco de dados atual usando a instrução T-SQL:

ALTER DATABASE CURRENT COLLATE Latin1_General_100_CI_AS_SC_UTF8;

O agrupamento Latin1_General_100_BIN2_UTF8 proporciona o melhor desempenho quando filtra os dados com predicados de cadeia.

Linhas ausentes no repositório analítico do Azure Cosmos DB

Alguns itens do Azure Cosmos DB podem não ser retornados OPENROWSET pela função. Esteja ciente de que:

  • Há um atraso de sincronização entre o repositório transacional e analítico. O documento inserido no repositório transacional do Azure Cosmos DB pode aparecer no repositório analítico após dois a três minutos.
  • O documento pode violar algumas restrições de esquema.

A consulta retorna valores NULL em alguns itens do Azure Cosmos DB

O Azure Synapse SQL retorna NULL em vez dos valores que você vê no repositório de transações nos seguintes casos:

  • Há um atraso de sincronização entre o repositório transacional e analítico. O valor inserido no repositório transacional do Azure Cosmos DB pode aparecer no repositório analítico após dois a três minutos.
  • Pode haver um nome de coluna ou expressão de caminho errado na cláusula WITH. O nome da coluna (ou expressão de caminho após o tipo de coluna) na cláusula WITH deve corresponder aos nomes de propriedade na coleção do Azure Cosmos DB. A comparação diferencia maiúsculas de minúsculas. Por exemplo, productCode e ProductCode são propriedades diferentes. Verifique se os nomes das colunas correspondem exatamente aos nomes de propriedade do Azure Cosmos DB.
  • A propriedade pode não ser movida para o armazenamento analítico porque viola algumas restrições de esquema, como mais de 1.000 propriedades ou mais de 127 níveis de aninhamento.
  • Se você usar uma representação de esquema bem definida, o valor no repositório transacional pode ter um tipo errado. O esquema bem definido bloqueia os tipos de cada propriedade por meio da amostragem dos documentos. Qualquer valor adicionado no repositório transacional que não corresponda ao tipo é tratado como um valor errado e não migrado para o repositório analítico.
  • Se você usar a representação de esquema de fidelidade total, certifique-se de que está adicionando o sufixo de tipo após o nome da propriedade, como $.price.int64. Se você não vir um valor para o caminho referenciado, talvez ele esteja armazenado em um caminho de tipo diferente, por exemplo, $.price.float64. Para obter mais informações, consulte Consultar coleções do Azure Cosmos DB no esquema de fidelidade total.

A coluna não é compatível com o tipo de dados externos

O erro Column 'column name' of the type 'type name' is not compatible with the external data type 'type name'. será retornado se o tipo de coluna especificado na cláusula WITH não corresponder ao tipo no contêiner do Azure Cosmos DB. Tente alterar o tipo de coluna conforme descrito na seção Azure Cosmos DB para mapeamentos de tipo SQL ou use o tipo VARCHAR.

Resolver: o caminho do Azure Cosmos DB falhou com erro

Se você receber o erro Resolving Azure Cosmos DB path has failed with error 'This request is not authorized to perform this operation'. , verifique se usou pontos de extremidade privados no Azure Cosmos DB. Para permitir que o pool SQL sem servidor acesse um repositório analítico com pontos de extremidade privados, você deve configurar pontos de extremidade privados para o repositório analítico do Azure Cosmos DB.

Problemas de desempenho do Azure Cosmos DB

Se você tiver alguns problemas de desempenho inesperados, certifique-se de que aplicou as práticas recomendadas, como:

Delta Lake

Há algumas limitações que você pode ver no suporte ao Delta Lake em pools SQL sem servidor:

  • Certifique-se de que você está fazendo referência à pasta Delta Lake raiz na função OPENROWSET ou no local da tabela externa.
    • A pasta raiz deve ter uma subpasta chamada _delta_log. A consulta falhará se não houver nenhuma _delta_log pasta. Se você não vir essa pasta, estará fazendo referência a arquivos Parquet simples que devem ser convertidos em Delta Lake usando pools do Apache Spark.
    • Não especifique curingas para descrever o esquema de partição. A consulta Delta Lake identifica automaticamente as partições Delta Lake.
  • As tabelas Delta Lake criadas nos pools do Apache Spark estão automaticamente disponíveis no pool SQL sem servidor, mas o esquema não é atualizado (limitação de visualização pública). Se você adicionar colunas na tabela Delta usando um pool do Spark, as alterações não serão mostradas no banco de dados do pool SQL sem servidor.
  • As tabelas externas não suportam particionamento. Use exibições particionadas na pasta Delta Lake para usar a eliminação de partição. Consulte problemas conhecidos e soluções alternativas mais adiante no artigo.
  • Os pools SQL sem servidor não oferecem suporte a consultas de viagem no tempo. Use pools do Apache Spark no Synapse Analytics para ler dados históricos.
  • Os pools SQL sem servidor não oferecem suporte à atualização de arquivos Delta Lake. Você pode usar o pool SQL sem servidor para consultar a versão mais recente do Delta Lake. Use pools do Apache Spark no Synapse Analytics para atualizar o Delta Lake.
  • Os pools SQL sem servidor no Synapse Analytics são compatíveis com o leitor Delta versão 1. Os recursos Delta que exigem leitores Delta com versão 2 ou superior (por exemplo , mapeamento de coluna) não são suportados nos pools SQL sem servidor.
  • Os pools SQL sem servidor no Synapse Analytics não suportam os conjuntos de dados com o filtro BLOOM. O pool SQL sem servidor ignora os filtros BLOOM.
  • O suporte ao Delta Lake não está disponível em pools SQL dedicados. Certifique-se de usar pools SQL sem servidor para consultar arquivos Delta Lake.
  • Para obter mais informações sobre problemas conhecidos com pools SQL sem servidor, consulte Problemas conhecidos do Azure Synapse Analytics.

Não há suporte para renomeação de coluna na tabela Delta

O pool SQL sem servidor não oferece suporte à consulta de tabelas Delta Lake com as colunas renomeadas. O pool SQL sem servidor não pode ler dados da coluna renomeada.

O valor de uma coluna na tabela Delta é NULL

Se você estiver usando um conjunto de dados Delta que requer um leitor Delta versão 2 ou superior e usa os recursos que não são suportados na versão 1 (por exemplo, renomear colunas, soltar colunas ou mapeamento de colunas), os valores nas colunas referenciadas podem não ser mostrados.

O texto JSON não está formatado corretamente

Esse erro indica que o pool SQL sem servidor não pode ler o log de transações do Delta Lake. Você provavelmente verá o seguinte erro:

Msg 13609, Level 16, State 4, Line 1
JSON text is not properly formatted. Unexpected character '' is found at position 263934.
Msg 16513, Level 16, State 0, Line 1
Error reading external metadata.

Certifique-se de que seu conjunto de dados Delta Lake não está corrompido. Verifique se você pode ler o conteúdo da pasta Delta Lake usando o pool do Apache Spark no Azure Synapse. Dessa forma, você garantirá que o _delta_log arquivo não esteja corrompido.

Solução

Tente criar um ponto de verificação no conjunto de dados Delta Lake usando o pool do Apache Spark e execute novamente a consulta. O ponto de verificação agrega arquivos de log JSON transacionais e pode resolver o problema.

Se o conjunto de dados for válido, crie um tíquete de suporte e forneça mais informações:

  • Não faça alterações, como adicionar ou remover as colunas ou otimizar a tabela, pois essa operação pode alterar o estado dos arquivos de log de transações do Delta Lake.
  • Copie o _delta_log conteúdo da pasta para uma nova pasta vazia. Não copie os .parquet data ficheiros.
  • Tente ler o conteúdo copiado na nova pasta e verifique se está a receber o mesmo erro.
  • Envie o conteúdo do arquivo copiado _delta_log para o suporte do Azure.

Agora você pode continuar usando a pasta Delta Lake com o pool Spark. Você fornecerá dados copiados ao suporte da Microsoft se tiver permissão para compartilhar essas informações. A equipe do Azure investigará o delta_log conteúdo do arquivo e fornecerá mais informações sobre possíveis erros e soluções alternativas.

Falha ao resolver logs Delta

O erro a seguir indica que o checkpointSchema pool SQL sem servidor não pode resolver logs Delta: Resolving Delta logs on path '%ls' failed with error: Cannot parse json object from log folder. A causa mais comum é que last_checkpoint_file na _delta_log pasta é maior que 200 bytes devido ao campo adicionado no Spark 3.3.

Há duas opções disponíveis para contornar esse erro:

  • Modifique a configuração apropriada no bloco de anotações do Spark e gere um novo ponto de verificação, para que seja last_checkpoint_file recriado. Caso você esteja usando o Azure Databricks, a modificação de configuração é a seguinte: spark.conf.set("spark.databricks.delta.checkpointSchema.writeThresholdLength", 0);
  • Downgrade para Spark 3.2.1.

Nossa equipe de engenharia está atualmente trabalhando em um suporte completo para o Spark 3.3.

A tabela delta criada no Spark não é mostrada no pool sem servidor

Nota

A replicação de tabelas Delta criadas no Spark ainda está em visualização pública.

Se você criou uma tabela Delta no Spark e ela não é mostrada no pool SQL sem servidor, verifique o seguinte:

  • Aguarde algum tempo (geralmente 30 segundos) porque as tabelas do Spark estão sincronizadas com atraso.
  • Se a tabela não aparecer no pool SQL sem servidor depois de algum tempo, verifique o esquema da tabela Delta do Spark. As tabelas Spark com tipos complexos ou os tipos que não são suportados no serverless não estão disponíveis. Tente criar uma tabela do Spark Parquet com o mesmo esquema em um banco de dados lake e verifique se essa tabela aparece no pool SQL sem servidor.
  • Verifique a pasta Delta Lake de acesso à Identidade Gerenciada do espaço de trabalho referenciada pela tabela. O pool SQL sem servidor usa a Identidade Gerenciada do espaço de trabalho para obter as informações da coluna da tabela do armazenamento para criar a tabela.

Base de dados Lake

As tabelas de banco de dados Lake que são criadas usando o Spark ou Synapse designer estão automaticamente disponíveis no pool SQL sem servidor para consulta. Você pode usar o pool SQL sem servidor para consultar as tabelas Parquet, CSV e Delta Lake criadas usando o pool do Spark e adicionar esquemas, modos de exibição, procedimentos, funções de valor de tabela e usuários do Microsoft Entra em db_datareader função ao seu banco de dados Lake. Possíveis problemas estão listados nesta seção.

Uma tabela criada no Spark não está disponível no pool sem servidor

As tabelas criadas podem não estar imediatamente disponíveis no pool SQL sem servidor.

  • As tabelas estarão disponíveis em pools sem servidor com algum atraso. Talvez seja necessário aguardar de 5 a 10 minutos após a criação de uma tabela no Spark para vê-la no pool SQL sem servidor.
  • Somente as tabelas que fazem referência aos formatos Parquet, CSV e Delta estão disponíveis no pool SQL sem servidor. Outros tipos de tabela não estão disponíveis.
  • Uma tabela que contenha alguns tipos de coluna sem suporte não estará disponível no pool SQL sem servidor.
  • O acesso às tabelas do Delta Lake nos bancos de dados do Lake está em visualização pública. Verifique outros problemas listados nesta seção ou na seção Delta Lake.

Uma tabela externa criada no Spark está mostrando resultados inesperados no pool sem servidor

Pode acontecer que haja uma incompatibilidade entre a tabela externa do Spark de origem e a tabela externa replicada no pool sem servidor. Isso pode acontecer se os arquivos usados na criação de tabelas externas do Spark estiverem sem extensões. Para obter os resultados adequados, certifique-se de que todos os arquivos estão com extensões como .parquet.

A operação não é permitida para um banco de dados replicado

Este erro é retornado se você estiver tentando modificar um banco de dados Lake, criar tabelas externas, fontes de dados externas, credenciais de escopo de banco de dados ou outros objetos em seu banco de dados Lake. Esses objetos podem ser criados somente em bancos de dados SQL.

Os bancos de dados Lake são replicados do pool do Apache Spark e gerenciados pelo Apache Spark. Portanto, você não pode criar objetos como em bancos de dados SQL usando a linguagem T-SQL.

Somente as seguintes operações são permitidas nos bancos de dados Lake:

  • Criar, descartar ou alterar modos de exibição, procedimentos e funções de valor de tabela embutido (iTVF) nos esquemas diferentes de dbo.
  • Criação e descartamento dos usuários do banco de dados a partir do Microsoft Entra ID.
  • Adicionar ou remover usuários de banco de dados do db_datareader esquema.

Outras operações não são permitidas em bancos de dados Lake.

Nota

Se você estiver criando um modo de exibição, procedimento ou função no dbo esquema (ou omitindo esquema e usando o padrão que geralmente dboé), você receberá a mensagem de erro.

As tabelas delta em bancos de dados Lake não estão disponíveis no pool SQL sem servidor

Certifique-se de que a Identidade Gerenciada do espaço de trabalho tenha acesso de leitura no armazenamento ADLS que contém a pasta Delta. O pool SQL sem servidor lê o esquema da tabela Delta Lake dos logs Delta colocados no ADLS e usa a Identidade Gerenciada do espaço de trabalho para acessar os logs de transações Delta.

Tente configurar uma fonte de dados em algum Banco de Dados SQL que faça referência ao seu armazenamento do Azure Data Lake usando a credencial de Identidade Gerenciada e tente criar uma tabela externa sobre a fonte de dados com a Identidade Gerenciada para confirmar se uma tabela com a Identidade Gerenciada pode acessar seu armazenamento.

As tabelas delta em bancos de dados Lake não têm esquema idêntico no Spark e em pools sem servidor

Os pools SQL sem servidor permitem que você acesse tabelas Parquet, CSV e Delta criadas no banco de dados Lake usando o designer Spark ou Synapse. O acesso às tabelas Delta ainda está em visualização pública e, atualmente, sem servidor sincronizará uma tabela Delta com o Spark no momento da criação, mas não atualizará o esquema se as colunas forem adicionadas posteriormente usando a ALTER TABLE instrução no Spark.

Esta é uma limitação de visualização pública. Solte e recrie a tabela Delta no Spark (se possível) em vez de alterar tabelas para resolver esse problema.

Desempenho

O pool SQL sem servidor atribui os recursos às consultas com base no tamanho do conjunto de dados e na complexidade da consulta. Não é possível alterar ou limitar os recursos fornecidos às consultas. Há alguns casos em que você pode enfrentar degradações inesperadas no desempenho da consulta e talvez seja necessário identificar as causas raiz.

A duração da consulta é muito longa

Se você tiver consultas com uma duração de consulta superior a 30 minutos, a consulta retornando lentamente os resultados para o cliente será lenta. O pool SQL sem servidor tem um limite de 30 minutos para execução. Mais tempo é gasto no streaming de resultados. Experimente as soluções seguintes:

  • Se você usar o Synapse Studio, tente reproduzir os problemas com algum outro aplicativo, como o SQL Server Management Studio ou o Azure Data Studio.
  • Se sua consulta for lenta quando executada usando o SQL Server Management Studio, o Azure Data Studio, o Power BI ou algum outro aplicativo, verifique os problemas de rede e as práticas recomendadas.
  • Coloque a consulta no comando CETAS e meça a duração da consulta. O comando CETAS armazena os resultados no Armazenamento do Azure Data Lake e não depende da conexão do cliente. Se o comando CETAS for concluído mais rápido do que a consulta original, verifique a largura de banda de rede entre o cliente e o pool SQL sem servidor.

A consulta é lenta quando executada usando o Synapse Studio

Se você usa o Synapse Studio, tente usar um cliente de área de trabalho, como o SQL Server Management Studio ou o Azure Data Studio. O Synapse Studio é um cliente Web que se conecta ao pool SQL sem servidor usando o protocolo HTTP, que geralmente é mais lento do que as conexões SQL nativas usadas no SQL Server Management Studio ou no Azure Data Studio.

A consulta é lenta quando executada usando um aplicativo

Verifique os seguintes problemas se a execução lenta da consulta:

  • Certifique-se de que os aplicativos cliente estão colocados com o ponto de extremidade do pool SQL sem servidor. A execução de uma consulta em toda a região pode causar latência adicional e fluxo lento do conjunto de resultados.
  • Certifique-se de que você não tem problemas de rede que podem causar o fluxo lento do conjunto de resultados
  • Certifique-se de que o aplicativo cliente tem recursos suficientes (por exemplo, não usando 100% CPU).
  • Verifique se a conta de armazenamento ou o armazenamento analítico do Azure Cosmos DB está colocado na mesma região que o ponto de extremidade SQL sem servidor.

Consulte as práticas recomendadas para colocar os recursos.

Altas variações nas durações de consulta

Se você estiver executando a mesma consulta e observando variações nas durações da consulta, vários motivos podem causar esse comportamento:

  • Verifique se esta é a primeira execução de uma consulta. A primeira execução de uma consulta coleta as estatísticas necessárias para criar um plano. As estatísticas são recolhidas através da análise dos ficheiros subjacentes e podem aumentar a duração da consulta. No Synapse Studio, você verá as consultas de "criação de estatísticas globais" na lista de solicitações SQL que são executadas antes da consulta.
  • As estatísticas podem expirar após algum tempo. Periodicamente, você pode observar um impacto no desempenho porque o pool sem servidor deve verificar e reconstruir as estatísticas. Você pode notar outras consultas de "criação de estatísticas globais" na lista de solicitações SQL que são executadas antes da consulta.
  • Verifique se há alguma carga de trabalho em execução no mesmo ponto de extremidade quando você executou a consulta com a duração mais longa. O ponto de extremidade SQL sem servidor aloca igualmente os recursos para todas as consultas que são executadas em paralelo, e a consulta pode ser atrasada.

Ligações

O pool SQL sem servidor permite que você se conecte usando o protocolo TDS e a linguagem T-SQL para consultar dados. A maioria das ferramentas que podem se conectar ao SQL Server ou ao Banco de Dados SQL do Azure também pode se conectar ao pool SQL sem servidor.

O pool SQL está esquentando

Após um longo período de inatividade, o pool SQL sem servidor será desativado. A ativação acontece automaticamente na primeira próxima atividade, como a primeira tentativa de conexão. O processo de ativação pode demorar um pouco mais do que um único intervalo de tentativa de ligação, pelo que a mensagem de erro é apresentada. Tentar novamente a tentativa de conexão deve ser suficiente.

Como prática recomendada, para os clientes que oferecem suporte a ele, use as palavras-chave da cadeia de conexão ConnectionRetryCount e ConnectRetryInterval para controlar o comportamento de reconexão.

Se a mensagem de erro persistir, registre um tíquete de suporte por meio do portal do Azure.

Não é possível conectar-se a partir do Synapse Studio

Consulte a secção Synapse Studio.

Não é possível conectar-se ao pool do Azure Synapse a partir de uma ferramenta

Algumas ferramentas podem não ter uma opção explícita que você pode usar para se conectar ao pool SQL sem servidor do Azure Synapse. Use uma opção que você usaria para se conectar ao SQL Server ou ao Banco de dados SQL. A caixa de diálogo de conexão não precisa ser marcada como "Synapse" porque o pool SQL sem servidor usa o mesmo protocolo do SQL Server ou do Banco de dados SQL.

Mesmo que uma ferramenta permita inserir apenas um nome de servidor lógico e predefina o database.windows.net domínio, coloque o nome do espaço de trabalho do Azure Synapse seguido do sufixo -ondemand e do database.windows.net domínio.

Segurança

Verifique se um usuário tem permissões para acessar bancos de dados, permissões para executar comandos e permissões para acessar o armazenamento do Azure Data Lake ou do Azure Cosmos DB.

Não é possível acessar a conta do Azure Cosmos DB

Você deve usar uma chave do Azure Cosmos DB somente leitura para acessar seu armazenamento analítico, portanto, certifique-se de que ele não expirou ou não foi regenerado.

Se você receber o erro "Resolvendo o caminho do Azure Cosmos DB falhou com erro", certifique-se de que configurou um firewall.

Não é possível acessar o banco de dados lakehouse ou Spark

Se um usuário não puder acessar um banco de dados lakehouse ou Spark, talvez não tenha permissão para acessar e ler o banco de dados. Um usuário com permissão CONTROL SERVER deve ter acesso total a todos os bancos de dados. Como uma permissão restrita, você pode tentar usar CONNECT ANY DATABASE e SELECT ALL USER SECURABLES.

O usuário SQL não pode acessar tabelas Dataverse

As tabelas Dataverse acessam o armazenamento usando a identidade Microsoft Entra do chamador. Um usuário SQL com altas permissões pode tentar selecionar dados de uma tabela, mas a tabela não poderá acessar os dados do Dataverse. Este cenário não é suportado.

Falhas de entrada da entidade de serviço do Microsoft Entra quando o SPI cria uma atribuição de função

Se você quiser criar uma atribuição de função para um identificador de entidade de serviço (SPI) ou aplicativo Microsoft Entra usando outro SPI, ou se já tiver criado um e ele não conseguir entrar, provavelmente receberá o seguinte erro: Login error: Login failed for user '<token-identified principal>'.

Para os principais de serviço, o início de sessão deve ser criado com um ID de aplicação, como um ID de segurança (SID) e não com um ID de objeto. Existe uma limitação conhecida para os principais de serviço, que impede o Azure Synapse de obter o ID da aplicação do Microsoft Graph quando cria uma atribuição de função para outro SPI ou aplicação.

Solução 1

Vá para o portal>do Azure Synapse Studio>Manage>Access control e adicione manualmente Synapse Administrator ou Synapse SQL Administrator para a entidade de serviço desejada.

Solução 2

Você deve criar manualmente um login adequado com código SQL:

use master
go
CREATE LOGIN [<service_principal_name>] FROM EXTERNAL PROVIDER;
go
ALTER SERVER ROLE sysadmin ADD MEMBER [<service_principal_name>];
go

Solução 3

Você também pode configurar uma entidade de serviço Azure Synapse admin usando o PowerShell. Você deve ter o módulo Az.Synapse instalado.

A solução é usar o cmdlet New-AzSynapseRoleAssignment com -ObjectId "parameter". Nesse campo de parâmetro, forneça a ID do aplicativo em vez da ID do objeto usando as credenciais da entidade de serviço do Azure do administrador do espaço de trabalho.

Script do PowerShell:

$spAppId = "<app_id_which_is_already_an_admin_on_the_workspace>"
$SPPassword = "<application_secret>"
$tenantId = "<tenant_id>"
$secpasswd = ConvertTo-SecureString -String $SPPassword -AsPlainText -Force
$cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $spAppId, $secpasswd

Connect-AzAccount -ServicePrincipal -Credential $cred -Tenant $tenantId

New-AzSynapseRoleAssignment -WorkspaceName "<workspaceName>" -RoleDefinitionName "Synapse Administrator" -ObjectId "<app_id_to_add_as_admin>" [-Debug]

Validação

Conecte-se ao ponto de extremidade SQL sem servidor e verifique se o logon externo com SID (app_id_to_add_as_admin no exemplo anterior) foi criado:

SELECT name, convert(uniqueidentifier, sid) AS sid, create_date
FROM sys.server_principals 
WHERE type in ('E', 'X');

Ou tente entrar no ponto de extremidade SQL sem servidor usando o aplicativo set admin.

Restrições

Algumas restrições gerais do sistema podem afetar sua carga de trabalho:

Property Limitação
Número máximo de espaços de trabalho do Azure Synapse por assinatura Veja limites.
Número máximo de bancos de dados por pool sem servidor 100 (não incluindo bancos de dados sincronizados do pool do Apache Spark).
Número máximo de bancos de dados sincronizados a partir do pool do Apache Spark Não limitado.
Número máximo de objetos de bancos de dados por banco de dados A soma do número de todos os objetos em um banco de dados não pode exceder 2.147.483.647. Consulte Limitações no mecanismo de banco de dados do SQL Server.
Comprimento máximo do identificador em caracteres 128. Consulte Limitações no mecanismo de banco de dados do SQL Server.
Duração máxima da consulta 30 minutos.
Tamanho máximo do conjunto de resultados Até 400 GB compartilhados entre consultas simultâneas.
Simultaneidade máxima Não limitado e depende da complexidade da consulta e da quantidade de dados digitalizados. Um conjunto de SQL sem servidor pode lidar simultaneamente com 1000 sessões ativas que estão a executar consultas leves. Os números cairão se as consultas forem mais complexas ou analisarem uma quantidade maior de dados, portanto, nesse caso, considere diminuir a simultaneidade e executar consultas por um período de tempo mais longo, se possível.
Tamanho máximo do nome da tabela externa 100 caracteres.

Não é possível criar um banco de dados no pool SQL sem servidor

Os pools SQL sem servidor têm limitações e você não pode criar mais de 100 bancos de dados por espaço de trabalho. Se você precisar separar objetos e isolá-los, use esquemas.

Se você receber o erro CREATE DATABASE failed. User database limit has been already reached , criou o número máximo de bancos de dados suportados em um espaço de trabalho.

Não é necessário usar bancos de dados separados para isolar dados de locatários diferentes. Todos os dados são armazenados externamente em um data lake e no Azure Cosmos DB. Os metadados como tabela, exibições e definições de função podem ser isolados com êxito usando esquemas. O isolamento baseado em esquema também é usado no Spark, onde bancos de dados e esquemas são os mesmos conceitos.

Próximos passos