Suporte de API do driver ODBC¶
O driver ODBC do Snowflake oferece suporte à versão 3.52 da API ODBC. Este tópico lista as rotinas ODBC relevantes para o Snowflake e indica se elas são compatíveis. As rotinas são organizadas em categorias com base na função que desempenham.
Para obter a referência completa da API, consulte a Referência do programador ODBC da Microsoft.
Conexão a uma fonte de dados¶
Nome da função |
Com suporte |
Notas |
|---|---|---|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. |
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. |
|
✔ |
Como obter informações de drivers e fontes de dados¶
Nome da função |
Com suporte |
Notas |
|---|---|---|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
Configuração e recuperação de atributos de drivers¶
Nome da função |
Com suporte |
Notas |
|---|---|---|
|
✔ |
A configuração SQL_ATTR_METADATA_ID afeta apenas as funções SQLTables e SQLColumns (e não as outras funções de catálogo suportadas). |
|
✔ |
Não há suporte para o modo somente leitura. SQL_MODE_READ_ONLY é passado para o driver, mas o Snowflake ainda grava no banco de dados. . . Além disso, alguns atributos foram introduzidos após a versão 3.52 da API: SQL_ATTR_ASYNC_DBC_EVENT, SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE, SQL_ATTR_ASYNC_DBC_PCALLBACK, SQL_ATTR_ASYNC_DBC_PCONTEXT, SQL_ATTR_DBC_INFO_TOKEN. |
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. |
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. |
|
✔ |
|
|
✔ |
O atributo SQL_ATTR_CONNECTION_POOLING foi introduzido após a versão 3.52 da API ODBC e não é suportado. |
|
✔ |
SQL_ATTR_CURSOR_SCROLLABLE aceita apenas um valor SQL_NONSCROLLABLE. . SQL_ATTR_USE_BOOKMARKS aceita apenas um valor SQL_UB_OFF. . . Para compatibilidade com ferramentas de terceiros, SQL_ATTR_ENABLE_AUTO_IPD é definido como verdadeiro por padrão, mesmo que o padrão ODBC diga que ele deve ser falso. Para alterar o valor padrão para falso, defina o parâmetro EnableAutoIpdByDefault como |
|
✔ |
Além dos atributos padrão, a implementação do Snowflake oferece suporte ao atributo SQL_SF_STMT_ATTR_LAST_QUERY_ID, que permite ao usuário recuperar a ID da consulta mais recente associada ao identificador da instrução especificada. Veja um exemplo parcial na seção Exemplos abaixo. |
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. Substituída por |
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. Substituída por |
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. Substituída por |
Cada uma das funções anteriores tem uma função correspondente que aceita caracteres amplos (unicode). Cada uma dessas funções unicode tem o nome mostrado acima, seguido por «W». Por exemplo, a função SQLGetStmtAttr, que aceita uma matriz de caracteres como terceiro parâmetro, tem uma função correspondente chamada SQLGetStmtAttrW, que aceita uma matriz de caracteres amplos como terceiro parâmetro.
Comportamento específico do Snowflake¶
SQLSetConnectAttrEsse método é compatível com dois atributos específicos do Snowflake:
Nome do atributo
Descrição
SQL_SF_CONN_ATTR_APPLICATION
Substitui o valor especificado pela configuração APPLICATION no registro ou no arquivo .ini.
SQL_SF_CONN_ATTR_PRIV_KEY
Ponteiro EVP_PKEY* que aponta para uma cópia da chave privada na memória. Substitui as configurações PRIV_KEY_FILE e PRIV_KEY_PWD no registro ou no arquivo .ini. O Snowflake recomenda o uso desse atributo para definir a chave privada.
No driver Snowflake ODBC versão 3.4.0 e superior, você pode usar os dois atributos adicionais a seguir no
SQLSetConnectAttr:Nome do atributo
Descrição
SQL_SF_CONN_ATTR_PRIV_KEY_CONTENTPermite passar o conteúdo de uma chave privada diretamente para a conexão. Certifique-se de passar o conteúdo completo da chave, incluindo o cabeçalho e o rodapé.
SQL_SF_CONN_ATTR_PRIV_KEY_PASSWORDSe você estiver passando uma chave privada criptografada no
SQL_SF_CONN_ATTR_PRIV_KEY_CONTENT, este atributo permitirá que você especifique a senha.O uso de
SQL_SF_CONN_ATTR_PRIV_KEY_CONTENTpoderá ser necessário se seu aplicativo e o driver ODBC estiverem vinculados a versões incompatíveis do OpenSSL e você estiver observando falhas provenientes do driver ODBC quando a autenticação do par de chaves for usada.O seguinte código C++ ilustra a implementação:
Configuração e recuperação dos campos descritores¶
Nome da função |
Com suporte |
Notas |
|---|---|---|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
Preparação de solicitações SQL¶
Nome da função |
Com suporte |
Notas |
|---|---|---|
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. |
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC. |
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 2.x. Substituída por |
Nota
Há um limite máximo para o tamanho dos dados que você pode vincular. Para obter mais detalhes, consulte Limites no tamanho do texto de consulta.
Instruções SQL com suporte para preparação lista os tipos de instruções SQL que são suportadas na preparação.
Envio de solicitações¶
Nome da função |
Com suporte |
Notas |
|---|---|---|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
Independentemente do tipo de dados vinculado ao parâmetro, o Snowflake realiza uma conversão no lado do servidor e retorna um VARCHAR com um comprimento máximo de 134217728. |
|
✔ |
|
|
✔ |
O suporte para essa função foi adicionado na versão 2.23.3 do driver ODBC. |
|
✔ |
O suporte para essa função foi adicionado na versão 2.23.3 do driver ODBC. |
Obtenção de resultados e informações sobre os resultados¶
Nome da função |
Com suporte |
Notas |
|---|---|---|
|
✔ |
No momento, o driver ODBC não oferece suporte a dados semiestruturados, incluindo os tipos de dados |
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. Substituída por |
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
Nas colunas GEOGRAPHY, |
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 2.x. Substituída por |
|
✔ |
|
|
✔ |
O argumento |
|
Substituída por |
|
|
O Snowflake não oferece suporte à funcionalidade. |
|
|
O Snowflake não oferece suporte à funcionalidade. |
Obtenção de informações sobre as tabelas de sistema da fonte de dados (funções de catálogo)¶
Nome da função |
Com suporte |
Notas |
|---|---|---|
|
Retorna um conjunto de resultados vazio. |
|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
No conjunto de resultados, a coluna |
|
Retorna um conjunto de resultados vazio. |
|
|
Retorna um conjunto de resultados vazio. |
|
|
Retorna um conjunto de resultados vazio. |
|
|
✔ |
Se o parâmetro passado para a função for “TABLE”, a função retorna todos os tipos de tabelas, incluindo tabelas transitórias e tabelas temporárias. . . Se o parâmetro passado para a função for “VIEW”, a função retorna todos os tipos de exibições, inclusive as exibições materializadas. . . Se o parâmetro passado para a função for “TABLE, VIEW” ou “%”, a função retorna informações sobre todos os tipos de tabelas e todos os tipos de exibições. |
Se o nome passado para a função de catálogo tiver um caractere inválido, ou se o nome não corresponder a nenhum objeto do banco de dados, a função retorna um conjunto de resultados vazio.
A configuração SQL_ATTR_METADATA_ID afeta apenas as funções SQLTables, SQLColumns e SQLProcedures.
Encerramento de uma instrução¶
Nome da função |
Com suporte |
Notas |
|---|---|---|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
|
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. Substituída por |
Encerramento de uma conexão¶
Nome da função |
Com suporte |
Notas |
|---|---|---|
|
Introduzida na versão da API posterior à versão 3.52. |
|
|
✔ |
|
|
✔ |
|
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. |
|
✔ |
O driver do Snowflake oferece suporte, mas foi depreciada na API ODBC versão 3.x. |
Tipos de dados SQL personalizados¶
Alguns tipos de dados SQL aceitos pelo Snowflake não têm mapeamento direto no ODBC (por exemplo, TIMESTAMP_*tz, VARIANT). Para permitir que o driver ODBC trabalhe com os tipos de dados sem suporte, o arquivo de cabeçalho enviado com o driver inclui definições para os seguintes tipos de dados personalizados:
O código a seguir mostra um exemplo de uso dos tipos de dados personalizados:
Exemplos¶
Esta seção oferece exemplos de utilização da API.
Recuperação da ID da última consulta¶
Recuperar a ID da última consulta é uma extensão do Snowflake para o padrão ODBC.
Para recuperar a ID da última consulta, chame a função SQLGetStmtAttr (ou SQLGetStmtAttrW), e passe o atributo SQL_SF_STMT_ATTR_LAST_QUERY_ID e uma matriz de caracteres grande o suficiente para armazenar a ID da consulta.
O exemplo abaixo mostra como recuperar a ID da consulta de uma consulta:
Se você estiver usando Linux ou macOS, chame SQLGetStmtAttrW e passe parâmetros do tipo de dados apropriado (por exemplo, «wchar» em vez de «char»).
Práticas recomendadas para melhorar o desempenho na recuperação de dados¶
Ao recuperar dados com SQLFetch, você pode usar as funções SQLGetData ou SQLBindCol para acessar o conteúdo das células. Na maioria dos casos, o uso de SQLBindCol proporciona melhor desempenho porque reduz o número de chamadas ODBC que você precisa fazer para recuperar os dados, e porque permite que você tire proveito da cópia de dados na memória.
Como usar SQLGetData para recuperar dados da célula¶
O exemplo a seguir usa a função SQLGetData para recuperar valores de células do buffer de dados retornados por SQLFetch. Observe que você precisa chamar SQLGetData uma vez para cada célula da linha.
Como usar SQLBindCol para vincular as colunas de uma linha de dados¶
O exemplo a seguir usa a função SQLBindCol para recuperar valores de células do buffer de dados retornados por SQLFetch. Ela cria um buffer na memória para o número de colunas em uma linha e depois faz uma única chamada SQLBindCol para vincular os buffers do aplicativo ao conjunto de resultados. Finalmente, ela chama SQLFetch uma vez por linha e carrega os valores das células no buffer. Essa abordagem pode aumentar significativamente a velocidade e a eficiência da recuperação de dados.
Como usar SQLBindCol para vincular colunas de várias linhas de dados¶
Você pode melhorar ainda mais o desempenho ao buscar várias linhas em uma única chamada SQLFetch, o que reduz o número de chamadas ODBC SQLFetch necessárias para processar todas as linhas de uma tabela de consulta.
O exemplo a seguir:
Determina o número de colunas no conjunto de resultados.
Cria uma matriz na memória para armazenar os dados de várias colunas.
Chama
SQLBindColpara cada coluna para vincular os buffers do aplicativo ao conjunto de resultados.Chama
SQLFetchpara obter o número especificado de linhas (100) e processa os dados no buffer de memória sem fazer chamadas ODBC, até que o final da tabela de consulta seja alcançado.
Essa abordagem pode aumentar significativamente a velocidade e a eficiência da recuperação de dados. Para uma tabela de consulta com 20 colunas e 1.000 linhas, esse exemplo faria apenas 20 chamadas SQLBindCol e 10 SQLFetch em vez de 20.000 chamadas SQLGetData para carregar todos os dados da tabela.