Driver ODBC da Microsoft para o Microsoft Fabric Data Engineering

O ODBC (Open Database Connectivity) é um padrão amplamente adotado que permite que os aplicativos cliente se conectem e trabalhem com dados de bancos de dados e plataformas de Big Data.

O driver Microsoft ODBC para Engenharia de Dados Fabric permite conectar, consultar e gerenciar cargas de trabalho Spark no Fabric com a confiabilidade e simplicidade do padrão ODBC. Baseado nas APIs Livy do Fabric, o driver oferece conectividade segura e flexível com o Spark SQL para seus aplicativos C/C++, .NET e Python, além de outros aplicativos e ferramentas de BI compatíveis com ODBC.

Características principais

• Compatível com ODBC 3.x: implementação completa da especificação ODBC 3.x
• Autenticação do Microsoft Entra ID: vários fluxos de autenticação, incluindo CLI do Azure, interativo, credenciais do cliente, autenticação baseada em certificado e token de acesso
• Suporte à consulta SQL do Spark: execução direta de instruções SQL do Spark
• Suporte a tipos de dados abrangentes: suporte para todos os tipos de dados SQL do Spark, incluindo tipos complexos (ARRAY, MAP, STRUCT)
• Reutilização de sessão: gerenciamento de sessão interno para melhorar o desempenho
• Modo de alta concorrência: Use sessões compartilhadas e pré-aquecidas do Livy no servidor para reduzir a latência no estabelecimento da conexão e a proliferação de clusters do Spark
• Suporte à tabela grande: manipulação otimizada para grandes conjuntos de resultados com tamanhos de página configuráveis
• Pré-busca assíncrona: carregamento de dados em segundo plano para melhorar o desempenho
• Suporte a proxy: configuração de proxy HTTP para ambientes empresariais
• Suporte a vários esquemas em um lakehouse: Conecte-se a um esquema específico dentro de um lakehouse
• Integração OneLake: Acesse os dados do lakehouse armazenados no OneLake, incluindo tabelas em múltiplos esquemas, por meio de uma interface ODBC unificada sem configuração de armazenamento separada
• suporte a itens Environment: Anexar itens de ambiente Fabric durante a execução do trabalho para aplicar bibliotecas de workspace, propriedades do Spark e variáveis a cada sessão
• Custom Spark configuration: passe as propriedades de configuração do Spark diretamente pela string de conexão para ajustar o comportamento da sessão

Pré-requisitos

Antes de usar o Microsoft ODBC Driver for Microsoft Fabric Data Engineering, verifique se você tem:

• Sistema operacional: Windows 10/11 ou Windows Server 2016+
• Fabric Access: Acesso a um espaço de trabalho Fabric
• Credenciais do Microsoft Entra ID: credenciais adequadas para autenticação
• IDs de espaço de trabalho e casa do lago: identificadores GUID para seu espaço de trabalho Fabric e casa do lago
• CLI do Azure (opcional): necessário para o método de autenticação da CLI do Azure

Baixar e instalar o MSI

• Baixar Driver ODBC da Microsoft para Data Engineering do Microsoft Fabric (zip)

1. Baixar o pacote MSI do Microsoft ODBC Driver para Engenharia de Dados do Microsoft Fabric
2. Clique duas vezes em MicrosoftFabricODBCDriver-2.0.msi.
3. Siga o assistente de instalação e aceite o contrato de licença
4. Escolha o diretório de instalação (padrão: C:\Program Files\Microsoft ODBC Driver for Microsoft Fabric Data Engineering\)
5. Concluir a instalação

Instalação silenciosa

# Silent installation
msiexec /i "MicrosoftFabricODBCDriver-2.0.msi" /quiet

# Installation with logging
msiexec /i "MicrosoftFabricODBCDriver-2.0.msi" /l*v install.log

Verifique a instalação

Após a instalação, verifique se o driver está registrado:

1. Executar odbcad32.exe (Administrador da Fonte de Dados ODBC)
2. Navegue até a guia Drivers
3. Verifique se "Microsoft ODBC Driver for Microsoft Fabric Data Engineering" está listado

Exemplo de início rápido

Este exemplo demonstra como conectar ao Fabric e executar uma consulta usando o Microsoft ODBC Driver for Microsoft Fabric Data Engineering. Antes de executar esse código, verifique se você concluiu os pré-requisitos e instalou o driver.

Exemplo em C/C++

#include <windows.h>
#include <sql.h>
#include <sqlext.h>
#include <iostream>

int main() {
    SQLHENV environment = SQL_NULL_HENV;
    SQLHDBC connection = SQL_NULL_HDBC;
    SQLHSTMT statement = SQL_NULL_HSTMT;

    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &environment);
    SQLSetEnvAttr(
        environment,
        SQL_ATTR_ODBC_VERSION,
        (SQLPOINTER)SQL_OV_ODBC3,
        0);
    SQLAllocHandle(SQL_HANDLE_DBC, environment, &connection);

    const char* connectionString =
        "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
        "WorkspaceId=<workspace-id>;"
        "LakehouseId=<lakehouse-id>;"
        "AuthFlow=AZURE_CLI;";

    SQLRETURN result = SQLDriverConnectA(
        connection,
        NULL,
        (SQLCHAR*)connectionString,
        SQL_NTS,
        NULL,
        0,
        NULL,
        SQL_DRIVER_NOPROMPT);

    if (SQL_SUCCEEDED(result)) {
        SQLAllocHandle(SQL_HANDLE_STMT, connection, &statement);
        result = SQLExecDirectA(
            statement,
            (SQLCHAR*)"SELECT 'Hello from Fabric!' AS message",
            SQL_NTS);

        if (SQL_SUCCEEDED(result)) {
            char message[256];
            SQLLEN indicator;

            while (SQLFetch(statement) == SQL_SUCCESS) {
                SQLGetData(
                    statement,
                    1,
                    SQL_C_CHAR,
                    message,
                    sizeof(message),
                    &indicator);
                std::cout << message << std::endl;
            }
        }

        SQLFreeHandle(SQL_HANDLE_STMT, statement);
        SQLDisconnect(connection);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, connection);
    SQLFreeHandle(SQL_HANDLE_ENV, environment);
    return 0;
}

Exemplo de Python

import pyodbc

# Connection string with required parameters
connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
)

# Connect and execute query
conn = pyodbc.connect(connection_string, timeout=30)
cursor = conn.cursor()

cursor.execute("SELECT 'Hello from Fabric!' as message")
row = cursor.fetchone()
print(row.message)

conn.close()

Exemplo de .NET

using System.Data.Odbc;

// Connection string with required parameters
string connectionString = 
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
    "WorkspaceId=<workspace-id>;" +
    "LakehouseId=<lakehouse-id>;" +
    "AuthFlow=AZURE_CLI;";

using var connection = new OdbcConnection(connectionString);
await connection.OpenAsync();

Console.WriteLine("Connected successfully!");

using var command = new OdbcCommand("SELECT 'Hello from Fabric!' as message", connection);
using var reader = await command.ExecuteReaderAsync();

if (await reader.ReadAsync())
{
    Console.WriteLine(reader.GetString(0));
}

Formato da cadeia de conexão

Cadeia de conexão básica

O Microsoft ODBC Driver for Microsoft Fabric Data Engineering usa o seguinte formato de cadeia de conexão:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};<parameter1>=<value1>;<parameter2>=<value2>;...

Componentes da cadeia de conexão

Cadeias de conexão de exemplo

Conexão básica (autenticação da CLI do Azure)

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI

Com opções de desempenho

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;ReuseSession=true;LargeTableSupport=true;PageSizeBytes=18874368

Com o registro de logs

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LogLevel=DEBUG;LogFile=odbc_driver.log

Com modo de alta concorrência

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=bi-dashboard

Veja a seção Modo de alta simultaneidade (HC) para obter instruções completas de configuração.

Autenticação

O Microsoft ODBC Driver for Microsoft Fabric Data Engineering dá suporte a vários métodos de autenticação por meio da ID do Microsoft Entra (anteriormente Azure Active Directory). A autenticação é configurada usando o AuthFlow parâmetro na cadeia de conexão.

Métodos de autenticação

Você pode especificar valores de autenticação em SNAKE_CASE MAIÚSCULO, PascalCase ou em formato numérico. O driver também aceita apelidos curtos como Browser, Interactive, CLI, Certificate, Token, e File. O driver ignora caracteres de sublinhado ao comparar valores.

Autenticação da CLI do Azure

Melhor para: desenvolvimento e aplicativos interativos

# Python Example
connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "Scope=https://api.fabric.microsoft.com/.default;"
)
conn = pyodbc.connect(connection_string)

Pré-requisitos:

• CLI do Azure instalada: az --version
• Conectado: az login

Autenticação interativa do navegador

Melhor para: aplicativos voltados para o usuário

# Python Example
connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=INTERACTIVE;"
    "TenantId=<tenant-id>;"
    "Scope=https://api.fabric.microsoft.com/.default;"
)
conn = pyodbc.connect(connection_string)

Comportamento:

• Abre uma janela do navegador para autenticação do usuário
• As credenciais são armazenadas em cache para conexões subsequentes

Autenticação de credenciais do cliente (principal de serviço)

Melhor para: serviços automatizados e trabalhos em segundo plano

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=CLIENT_CREDENTIAL;"
    f"TenantId={tenant_id};"
    f"ClientId={client_id};"
    f"ClientSecret={client_secret};"
)

Parâmetros necessários

• TenantId: ID do locatário do Azure
• ClientId: ID do aplicativo (cliente) da Microsoft Entra ID
• ClientSecret: segredo do cliente do Microsoft Entra ID

Práticas recomendadas

• Armazenar segredos com segurança (Azure Key Vault, variáveis de ambiente)
• Usar identidades gerenciadas quando possível
• Alternar segredos regularmente

Autenticação baseada em certificado

Melhor para: aplicativos empresariais que exigem autenticação baseada em certificado

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=CLIENT_CERTIFICATE;"
    "TenantId=<tenant-id>;"
    "ClientId=<client-id>;"
    "CertificatePath=C:\\certs\\mycert.pfx;"
    "CertificatePassword=<password>;"
)

Parâmetros necessários:

• TenantId: ID do locatário do Azure
• ClientId: ID do aplicativo (cliente)
• CertificatePath: caminho para o arquivo de certificado PFX/PKCS12
• CertificatePassword: senha do certificado

Autenticação de token de acesso

Melhor para: cenários de autenticação personalizados

# Acquire token through custom mechanism
access_token = acquire_token_from_custom_source()

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=ACCESS_TOKEN;"
    f"AccessToken={access_token};"
)

Autenticação de token de arquivo

Use a autenticação por token em arquivo para ambientes em contêineres e pipelines automatizados, nos quais outro processo grava um token ao portador no arquivo de token bem conhecido do driver:

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=FILE_TOKEN;"
)

O driver resolve a localização do arquivo token no Windows e Linux.

Aliases de propriedades entre drivers

O driver ODBC aceita nomes selecionados de propriedades ADO.NET e JDBC, além dos nomes nativos ODBC. Esse suporte pode reduzir as mudanças na cadeia de conexão quando você se move entre drivers Fabric.

O driver resolve 17 aliases entre drivers ao estabelecer a conexão.

Parâmetros de configuração

Parâmetros necessários

Esses parâmetros devem estar presentes em todas as cadeias de conexão:

Parâmetros opcionais

Configurações de conexão

Configurações de desempenho

Configurações de registro em log

Configurações de proxy

Configurações de alta concorrência (HC)

Use esses parâmetros para ativar e configurar o modo de alta concorrência (HC). O modo HC é opcional. Se você não definir LivyMode ou UseHighConcurrency, o driver usa o caminho clássico de sessão única. Para orientações e exemplos, veja Modo de alta concorrência (HC).

Precedência de modos e validação

• LivyMode Tem prioridade sobre UseHighConcurrency quando você define ambos os parâmetros.
• Os valores dos parâmetros não diferenciam maiúsculas de minúsculas.
• UseHighConcurrency aceita true, 1, yes, ou on para ativar o modo HC. Aceita false, 0, no, ou off para desativar o modo HC.
• Para outros valores não vazios, SQLDriverConnect retorna um erro. Somente o DSN SQLConnect registra a falha de validação e usa o caminho clássico.

Configurações de compatibilidade

O driver aceita TenantPrincipal e PoolMax, incluindo suas alternativas por variáveis de ambiente, para compatibilidade com configurações anteriores do HC. O driver analisa e valida esses valores, mas eles não afetam a correspondência de sessões HC ou a capacidade do pool de runtime. Não confie neles para isolamento de inquilinos ou limites de conexão.

Alternativas de variáveis de ambiente

O driver usa as seguintes variáveis de ambiente apenas quando o parâmetro correspondente DSN ou string de conexão não está definido:

Para FABRIC_ODBC_USE_HC, a habilitação somente por ambiente reconhece true, 1 ou yes (sem diferenciar maiúsculas de minúsculas). Outros valores deixam o HC desativado. Os on aliases e off se aplicam apenas a valores DSN e de string de conexão.

Configurações de ambiente

Você pode anexar um item de ambiente Fabric à sessão do Spark iniciada pelo driver. As bibliotecas do ambiente selecionado, as propriedades do Spark e as variáveis são aplicadas automaticamente quando a sessão é criada.

Exemplo de cadeia de conexão com um item de ambiente:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;EnvironmentId=<environment-id>

Configuração personalizada do Spark

Você pode passar as propriedades de configuração do Spark diretamente no cadeia de conexão. Qualquer parâmetro prefixado com spark. é aplicado automaticamente à sessão do Spark no momento da criação, permitindo que você substitua os padrões de workspace ou runtime.

Exemplo de configurações do Spark:

spark.sql.shuffle.partitions=200
spark.sql.adaptive.enabled=true
spark.sql.autoBroadcastJoinThreshold=10485760

Exemplo de string de conexão com propriedades personalizadas do Spark:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;spark.sql.shuffle.partitions=200;spark.sql.adaptive.enabled=true

Modo de alta concorrência (HC)

O modo de alta concorrência (HC) permite que conexões ODBC com o mesmo workspace e lakehouse se conectem a sessões Livy Spark compartilhadas e já ativas no servidor, em vez de provisionar um cluster separado para cada conexão. Use-o para cargas de trabalho, como painéis de BI, kernels de notebook e distribuição de ETL, que abrem muitas conexões de curta duração e podem compartilhar a capacidade do Spark gerenciada pelo servidor.

O modo HC é opcional. Se você não configurar uma configuração HC, o driver usa o caminho clássico de sessão única.

Escolher um modo de conexão

Use o modo HC quando:

• Sua carga de trabalho abre muitas conexões ODBC de curta duração, como painéis de BI, kernels de notebook ou processos ETL paralelos.
• As conexões têm como alvo o mesmo espaço de trabalho e o mesmo lakehouse e podem compartilhar uma sessão Spark gerenciada pelo servidor.
• Reduzir a latência de início a frio por conexão é importante.

Use o modo clássico quando:

• Cada conexão requer uma sessão Spark isolada devido a diferentes configurações do Spark ou isolamento rigoroso de recursos.
• O endpoint do Fabric Livy para o workspace de destino e o lakehouse não é compatível com o modo HC.

Ativar o modo de alta concorrência

Adicione um parâmetro de modo de alta concorrência ao DSN ou à cadeia de conexão.

Recomendado: Definir LivyMode

Use LivyMode para selecionar explicitamente o modo de aquisição de sessão:

LivyMode=HighConcurrency

Os valores com suporte são Classic, HighConcurrencye Auto. Os valores não diferenciam maiúsculas de minúsculas. Auto Atualmente seleciona o modo clássico.

Alternativa: Set UseHighConcurrency

Use a configuração booleana para compatibilidade com configurações existentes:

UseHighConcurrency=true

Para ativar o modo de alta concorrência, use true, 1, yes, ou on. Para desativá-lo, use false, 0, no, ou off. Os valores não diferenciam maiúsculas de minúsculas. SQLDriverConnect rejeita outros valores não vazios com SQLSTATE HY024. Somente DSN SQLConnect registra em log a falha de validação e usa o modo clássico.

Parâmetros necessários no modo HC

A ativação HC requer os seguintes identificadores válidos:

Inclua SessionTag porque isso influencia o matching do lado do servidor para sessões quentes.

Associação de sessões

O modo HC não garante que toda conexão reutilize uma sessão existente. Para cada solicitação de aquisição de sessão, o driver envia:

• O SessionTag valor.
• A configuração efetiva do Spark, incluindo as configurações de conf.* e EnvironmentId.

O serviço Fabric Livy avalia esses valores e decide se deve anexar a conexão a uma sessão quente ou criar uma nova sessão. Para melhorar o reuso das sessões, use valores consistentes entre conexões que tenham a intenção de compartilhar a capacidade do Spark gerenciado pelo servidor.

Cadeias de conexão de exemplo

Conexão HC mínima (autenticação da CLI do Azure):

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=bi-dashboard

HC com tempos ajustados:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=etl-prod;AcquireTimeoutSeconds=180;HeartbeatTimeoutInSecond=600

HC com um ambiente e substituições de configuração do Spark:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;EnvironmentId=<environment-id>;SessionTag=ml-team;conf.spark.sql.shuffle.partitions=200;conf.spark.executor.memory=8g

Python (pyodbc):

import pyodbc

conn = pyodbc.connect(
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LivyMode=HighConcurrency;"
    "SessionTag=notebook-kernel"
)

Configurar o modo HC em um DSN

Você pode armazenar as configurações de HC em um DSN em vez de repeti-las em cada cadeia de conexão. Quando uma cadeia de conexão não especifica um valor, o driver lê estas configurações da DSN:

• LivyMode
• UseHighConcurrency
• EnvironmentId
• SessionTag
• IdempotencyKey
• HeartbeatTimeoutInSecond
• AcquireTimeoutSeconds

O driver também lê apenas TenantPrincipal compatibilidade e PoolMax configurações. Para salvar essas configurações, edite o DSN em odbcad32.exe ou use SQLWritePrivateProfileString. Use os nomes dos parâmetros na tabela de configurações do HC.

Desativar o modo HC

Você pode desativar novas aquisições de sessão HC sem precisar reimplantar o driver. Use o método que corresponde a como você ativou o modo HC:

As configurações de conexão string e DSN têm precedência sobre o fallback da variável ambiental. Essas mudanças afetam apenas novas conexões. As sessões de HC existentes continuam até serem encerradas.

Entenda o comportamento em tempo de execução do HC

• Validação:SQLDriverConnect rejeita valores booleanos HC e inteiros positivos inválidos com SQLSTATE HY024. Rejeita um valor inválido de LivyMode e valores inválidos ou grandes demais de WorkspaceId, LakehouseId e IdempotencyKey com SQLSTATE HY000. Um valor de compatibilidade TenantPrincipal sobredimensionado também retorna HY000. Para SQLConnect somente DSN, o driver registra falhas comuns na validação de HC e usa o modo clássico. Valores sensíveis relacionados à segurança excessivamente grandes ainda causam falha na conexão.
• Dados sensíveis: O driver exclui ou remove IdempotencyKey outros campos sensíveis dos logs HC e da saída de diagnóstico.
• Cancelamento: O cancelamento da instrução ocorre de forma cooperativa. O processamento no servidor já em andamento é finalizado de forma limpa, em vez de ser encerrado imediatamente.
• Disjuntores: Os modos HC e clássico usam disjuntores separados. Esgotar um modo não afeta o outro.
• Banco de dados inicial: As conexões HC não executam a instrução USE inicial para o parâmetro Database. Execute USE <database> após conectar ou use nomes de tabelas totalmente qualificados.
• Diagnóstico: Defina LogLevel=DEBUG para registrar a aquisição de HC, a sondagem, a liberação e as decisões de mapeamento de erros. Para solução de problemas focada, configure LIVY_HC_VERBOSE=1 para incluir diagnósticos HC HTTP adicionais e eliminados.

Configurar DSN

Criar um DSN do sistema

1. Abrir Administrador ODBC

   %SystemRoot%\System32\odbcad32.exe
   

2. Criar um novo DSN do sistema

   • Vá para a aba "DSN do Sistema"
   • Selecione "Adicionar"
   • Selecione "Microsoft ODBC Driver for Microsoft Fabric Data Engineering"
   • Selecione "Concluir"

3. Definir configurações de DSN

   • Nome da fonte de dados: insira um nome exclusivo (por exemplo, FabricODBC)
   • Descrição: descrição opcional
   • ID do espaço de trabalho: GUID do espaço de trabalho do Fabric
   • ID do Lakehouse: O GUID do Lakehouse do Fabric
   • Autenticação: selecionar método de autenticação
   • Environment ID (opcional): insira o GUID do item de ambiente Fabric a ser anexado durante a criação da sessão
   • Modo Livy (opcional): Definido para HighConcurrency ativar o modo HC
   • Tag de sessão (opcional): Insira um rótulo operacional não sensível para correspondência de sessão HC
   • Definir configurações adicionais conforme necessário

4. Testar Conexão

   • Selecione "Testar Conexão" para verificar as configurações
   • Selecione "OK" para salvar

Usar DSN em aplicativos

# Python - Connect using DSN
conn = pyodbc.connect("DSN=FabricODBC")

// .NET - Connect using DSN
using var connection = new OdbcConnection("DSN=FabricODBC");
await connection.OpenAsync();

Exemplos de uso

Conexão e consulta básicas

Python

import pyodbc

def main():
    connection_string = (
        "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
        "WorkspaceId=<workspace-id>;"
        "LakehouseId=<lakehouse-id>;"
        "AuthFlow=AZURE_CLI;"
        "ReuseSession=true;"
    )
    
    conn = pyodbc.connect(connection_string, timeout=30)
    cursor = conn.cursor()
    
    print("Connected successfully!")
    
    # Show available tables
    print("\nAvailable tables:")
    cursor.execute("SHOW TABLES")
    for row in cursor.fetchall():
        print(f"  {row}")
    
    # Query data
    print("\nQuery results:")
    cursor.execute("SELECT * FROM employees LIMIT 10")
    
    # Print column names
    columns = [desc[0] for desc in cursor.description]
    print(f"Columns: {columns}")
    
    # Print rows
    for row in cursor.fetchall():
        print(row)
    
    conn.close()

if __name__ == "__main__":
    main()

.NET

using System.Data.Odbc;

class Program
{
    static async Task Main(string[] args)
    {
        string connectionString = 
            "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
            "WorkspaceId=<workspace-id>;" +
            "LakehouseId=<lakehouse-id>;" +
            "AuthFlow=AZURE_CLI;" +
            "ReuseSession=true;";

        using var connection = new OdbcConnection(connectionString);
        await connection.OpenAsync();
        
        Console.WriteLine("Connected successfully!");

        // Show available tables
        Console.WriteLine("\nAvailable tables:");
        using (var cmd = new OdbcCommand("SHOW TABLES", connection))
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                Console.WriteLine($"  {reader.GetString(0)}");
            }
        }

        // Query data
        Console.WriteLine("\nQuery results:");
        using (var cmd = new OdbcCommand("SELECT * FROM employees LIMIT 10", connection))
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            // Print column names
            var columns = new List<string>();
            for (int i = 0; i < reader.FieldCount; i++)
            {
                columns.Add(reader.GetName(i));
            }
            Console.WriteLine($"Columns: {string.Join(", ", columns)}");

            // Print rows
            while (await reader.ReadAsync())
            {
                var values = new object[reader.FieldCount];
                reader.GetValues(values);
                Console.WriteLine(string.Join("\t", values));
            }
        }
    }
}

Trabalhando com grandes conjuntos de resultados

import pyodbc

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LargeTableSupport=true;"
    "PageSizeBytes=18874368;"  # 18 MB pages
    "EnableAsyncPrefetch=1;"
)

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()

# Execute large query
cursor.execute("SELECT * FROM large_table")

# Process in batches
row_count = 0
while True:
    rows = cursor.fetchmany(1000)  # Fetch 1000 rows at a time
    if not rows:
        break
    
    for row in rows:
        # Process row
        row_count += 1
        
    if row_count % 10000 == 0:
        print(f"Processed {row_count} rows")

print(f"Total rows processed: {row_count}")
conn.close()

Executar instruções DML

bool executeDml(SQLHDBC connection, const char* sql, const char* description) {
    SQLHSTMT statement = SQL_NULL_HSTMT;
    SQLAllocHandle(SQL_HANDLE_STMT, connection, &statement);

    std::cout << "Executing: " << description << std::endl;
    SQLRETURN result = SQLExecDirectA(
        statement,
        (SQLCHAR*)sql,
        SQL_NTS);

    bool succeeded = SQL_SUCCEEDED(result);
    if (succeeded) {
        SQLLEN rowCount;
        SQLRowCount(statement, &rowCount);
        std::cout << "Rows affected: " << rowCount << std::endl;
    }

    SQLFreeHandle(SQL_HANDLE_STMT, statement);
    return succeeded;
}

Use executeDml com as instruções INSERT, UPDATE ou DELETE. A contagem de linhas reportada depende se o resultado contém uma contagem de atualizações reconhecida pelo driver.

Descoberta de esquema

import pyodbc

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()

# List all tables
print("Tables in current default schema / database:")
cursor.execute("SHOW TABLES")
tables = cursor.fetchall()
for table in tables:
    print(f"  {table}")

# Describe table structure
print("\nTable structure for 'employees':")
cursor.execute("DESCRIBE employees")
for col in cursor.fetchall():
    print(f"  {col}")

# List schemas (for multi-schema Lakehouses)
print("\nAvailable schemas:")
cursor.execute("SHOW SCHEMAS")
for db in cursor.fetchall():
    print(f"  {db}")

conn.close()

Mapeamento de tipo de dados

O driver mapeia tipos de dados SQL do Spark para tipos SQL ODBC:

Integração de ferramentas de BI

Microsoft Excel

1. Abrir o Excel –> Dados –> Obter dados –> de outras fontes –> do ODBC
2. Selecione o DSN configurado (por exemplo, FabricODBC)
3. Autentique-se se solicitado
4. Navegar e selecionar tabelas
5. Carregar dados na planilha do Excel

Power BI Desktop

1. Abrir o Power BI Desktop –> Obter Dados –> ODBC
2. Selecione o DSN configurado
3. Navegar no catálogo de dados e selecionar tabelas
4. Transformar dados conforme necessário
5. Criar visualizações

SQL Server Management Studio (Servidor Vinculado)

-- Create linked server
EXEC sp_addlinkedserver 
    @server = 'FABRIC_LINKED_SERVER',
    @srvproduct = 'Microsoft Fabric',
    @provider = 'MSDASQL',
    @datasrc = 'FabricODBC'

-- Configure RPC
EXEC master.dbo.sp_serveroption 
    @server = N'FABRIC_LINKED_SERVER',
    @optname = N'rpc out',
    @optvalue = N'true';

-- Query via linked server
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SHOW TABLES');
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SELECT * FROM employees LIMIT 20');

-- Execute statements
EXEC('SELECT * FROM employees LIMIT 10') AT FABRIC_LINKED_SERVER;

Resolução de problemas

Esta seção fornece diretrizes para resolver problemas comuns que você pode encontrar ao usar o Microsoft ODBC Driver for Microsoft Fabric Data Engineering.

Problemas comuns

As seções a seguir descrevem problemas comuns e suas soluções:

Falhas na conexão

Problema: Não consigo conectar ao Fabric

Soluções:

1. Verifique se a ID do workspace e a ID do lakehouse são GUIDs válidos
2. Verifique a autenticação da CLI do Azure: az account show
3. Verifique se você tem permissões de workspace apropriadas do Fabric
4. Verificar as configurações de proxy e conectividade de rede

Erros de autenticação

Problema: a autenticação falha com a CLI do Azure

Soluções:

• Executar az login para atualizar credenciais
• Verifique o locatário correto: az account set --subscription <subscription-id>
• Verificar a validade do token: az account get-access-token --resource https://api.fabric.microsoft.com

Tempos limite da consulta

Problema: consultas estão atingindo o tempo limite em tabelas grandes

Soluções:

• Habilitar LargeTableSupport=true
• Ajustar PageSizeBytes para o tamanho ideal do bloco
• Habilitar pré-busca assíncrona: EnableAsyncPrefetch=1
• Usar LIMIT cláusula para restringir o tamanho do resultado

Habilitar registro de log

Ao solucionar problemas, habilitar o log detalhado pode ajudá-lo a identificar a causa raiz dos problemas. Você pode habilitar o registro em log por meio da cadeia de conexão.

Para habilitar o registro em log detalhado:

LogLevel=DEBUG;LogFile=C:\temp\odbc_driver_debug.log;

Níveis de log:

• DEBUG: Informações detalhadas de depuração e o nível de log de driver mais extenso
• INFO: informações gerais (padrão)
• WARN: somente avisos
• ERROR: apenas erros

Rastreamento ODBC

Para diagnósticos de baixo nível, você pode habilitar o rastreamento ODBC do Windows para capturar chamadas detalhadas da API ODBC e o comportamento do driver. Lembre-se de desativar o rastreamento quando não for necessário para manter o desempenho ideal.

Para habilitar o rastreamento ODBC:

1. Abrir odbcad32.exe
2. Vá para a guia "Rastreamento"
3. Definir caminho do arquivo de rastreamento (por exemplo, C:\temp\odbctrace.log)
4. Selecione "Iniciar Rastreamento Agora"
5. Reproduzir o problema
6. Selecione "Parar Rastreamento Agora"

Conteúdo relacionado

• Driver ODBC da Microsoft para o Microsoft Fabric Data Engineering no Linux
• Ambientes de execução do Apache Spark no Azure Fabric
• Fabric Runtime 1.3
• O que é a API livy para engenharia de dados
• Microsoft JDBC Driver para Microsoft Fabric Data Engineering