API do conector Python

O conector do Snowflake para Python implementa a especificação Python Database API v2.0 (PEP-249). Este tópico cobre a API padrão e as extensões específicas do Snowflake.

Neste tópico:

Módulo: snowflake.connector

O módulo principal é snowflake.connector, que cria um objeto Connection e fornece classes Error.

Constantes

apilevel

Constante de cadeia de caracteres que indica o nível de API com suporte. O conector é compatível com a API "2.0".

threadsafety

Constante de número inteiro que indica o nível de segurança de thread aceito pela interface. O conector do Snowflake para Python é compatível com o nível 2, que afirma que threads podem compartilhar o módulo e as conexões.

paramstyle

Constante de cadeia de caracteres que indica o tipo de formatação do marcador de parâmetro esperado pela interface. O conector é compatível com o tipo "pyformat" por padrão, que se aplica aos códigos de formato estendido do Python (por exemplo ...WHERE name=%s ou ...WHERE name=%(name)s). Connection.connect pode substituir paramstyle para alterar os formatos das variáveis de vinculação para "qmark" ou "numeric", onde as variáveis são ? ou :N, respectivamente.

Por exemplo:

format: .execute("... WHERE my_column = %s", (value,))
pyformat: .execute("... WHERE my_column = %(name)s", {"name": value})
qmark: .execute("... WHERE my_column = ?", (value,))
numeric: .execute("... WHERE my_column = :1", (value,))
Copy

Nota

A variável de vinculação ocorre no lado do cliente se paramstyle for "pyformat" ou "format", e no lado do servidor se "qmark" ou "numeric". Atualmente, não há diferença significativa entre essas opções em termos de desempenho ou recursos porque o conector não aceita a compilação de texto SQL seguido por múltiplas execuções. Em vez disso, as opções "qmark" e "numeric" se alinham com a compatibilidade do texto de consulta de outros drivers (ou seja, JDBC, ODBC, Go Snowflake Driver), compatíveis com a vinculação no lado do servidor com o formato de variável ? ou :N.

Funções

connect(parameters...)
Objetivo

Construtor para criar uma conexão com o banco de dados. Retorna um objeto Connection.

Por padrão, o modo de confirmação automática está habilitado (ou seja, se a conexão for fechada, todas as alterações são confirmadas). Se você precisar de uma transação, use o comando BEGIN para iniciar a transação, e COMMIT ou ROLLBACK para confirmar ou reverter qualquer alteração.

Parâmetros

Os parâmetros de entrada válidos são:

Parâmetro

Obrigatório

Descrição

account

Sim

O identificador de sua conta. O identificador da conta não inclui o sufixo snowflakecomputing.com. . . Para detalhes e exemplos, consulte Notas de uso (neste tópico).

user

Sim

Nome de login para o usuário.

password

Sim

Senha do usuário.

region

Obsoleto Esta descrição do parâmetro é apenas para compatibilidade com versões anteriores.

host

Não é mais usado Nome do host. Usado apenas internamente (ou seja, não precisa ser definido).

port

Não é mais usado Número da porta (443 por padrão). Usado apenas internamente (ou seja, não precisa ser definido).

database

Nome do banco de dados padrão a ser utilizado. Após o login, você pode usar USE DATABASE para alterar o banco de dados.

schema

Nome do esquema padrão a ser usado para o banco de dados. Após o login, você pode usar USE SCHEMA para alterar o esquema.

role

Nome da função padrão a ser usada. Após o login, você pode usar USE ROLE para alterar a função.

warehouse

Nome do warehouse padrão a ser utilizado. Após o login, você pode usar USE WAREHOUSE para alterar o warehouse.

passcode_in_password

False por padrão. Defina como True se a senha de MFA (autenticação multifator) estiver integrada à senha de login.

passcode

A senha fornecida por Duo ao usar a MFA (autenticação multifator) para login.

private_key

A chave privada utilizada para a autenticação. Para obter mais informações, consulte Uso de autenticação de pares de chaves e rotação de pares de chaves.

private_key_file

Especifica o caminho para o arquivo de chave privada para o usuário especificado. Consulte Uso de autenticação de pares de chaves e rotação de pares de chaves.

private_key_file_pwd

Especifica a senha para descriptografar o arquivo de chave privada para o usuário especificado. Consulte Uso de autenticação de pares de chaves e rotação de pares de chaves.

autocommit

None por padrão, que adota o parâmetro AUTOCOMMIT do Snowflake. Defina como True ou False para habilitar ou desabilitar o modo de confirmação automática na sessão, respectivamente.

client_prefetch_threads

Número de threads usados para baixar os conjuntos de resultados (4 por padrão). Aumentar o valor melhora o desempenho da busca, mas requer mais memória.

client_session_keep_alive

Para manter a sessão ativa indefinidamente (mesmo que não haja atividade do usuário), defina como True. Ao definir como True, chame o método close para encerrar o thread corretamente; caso contrário, o processo pode travar.

O valor padrão depende da versão do conector que você está usando:

  • Versão 2.4.6 e posteriores: None por padrão. . Quando o valor é None, o parâmetro de sessão CLIENT_SESSION_KEEP_ALIVE tem precedência. . . Para substituir o parâmetro de sessão, passe True ou False para este argumento.

  • Versão 2.4.5 e anteriores: False por padrão. . Quando o valor é False (seja especificando o valor explicitamente ou omitindo o argumento), o parâmetro de sessão CLIENT_SESSION_KEEP_ALIVE tem precedência. . . Passar client_session_keey_alive=False ao método connect não substitui o valor TRUE no parâmetro de sessão CLIENT_SESSION_KEEP_ALIVE.

login_timeout

Tempo limite em segundos para login. Por padrão, 60 segundos. A solicitação de login desiste após o tempo limite se a resposta HTTP for bem-sucedida.

network_timeout

Tempo limite em segundos para todas as outras operações. Por padrão, nenhum/infinito. Uma solicitação geral desiste após o tempo limite se a resposta HTTP for bem-sucedida.

ocsp_response_cache_filename

URI para o arquivo do cache de resposta OCSP. Por padrão, o arquivo do cache de resposta OCSP é criado no diretório do cache:

  • Linux: ~/.cache/snowflake/ocsp_response_cache

  • macOS: ~/Library/Caches/Snowflake/ocsp_response_cache

  • Windows: %USERPROFILE%\AppData\Local\Snowflake\Caches\ocsp_response_cache

Para localizar o arquivo em um diretório diferente, especifique o caminho e o nome do arquivo no URI (por exemplo, file:///tmp/my_ocsp_response_cache.txt).

authenticator

Autenticador para o Snowflake:

  • snowflake (padrão) para usar o autenticador interno do Snowflake.

  • externalbrowser para autenticar usando seu navegador da web e Okta, AD FS ou qualquer outro provedor de identidade (IdP) compatível com SAML 2.0 que tenha sido definido para sua conta.

  • https://<nome_da_conta_okta>.okta.com (ou seja, o ponto de extremidade da URL para sua conta Okta) para autenticar através de Okta nativo.

  • oauth para autenticar usando OAuth. Você também deve especificar o parâmetro token e definir seu valor para o token de acesso OAuth.

Se o valor não for snowflake, os parâmetros de usuário e senha devem ser suas credenciais de login para o IdP.

validate_default_parameters

False por padrão. Se True, então:

  • Acione uma exceção se o banco de dados, esquema ou warehouse especificado não existir.

  • Imprima um aviso em stderr se um nome de argumento inválido ou um valor de argumento do tipo de dado errado for passado.

paramstyle

pyformat por padrão para vinculação do lado do cliente. Especifique qmark ou numeric para mudar os formatos das variáveis para vinculação do lado do servidor.

timezone

None por padrão, que adota o parâmetro TIMEZONE do Snowflake. Defina com um fuso horário válido (por exemplo, America/Los_Angeles) para definir o fuso horário da sessão.

arrow_number_to_decimal

False por padrão, o que significa que os valores da coluna NUMBER são retornados como números de ponto flutuante de precisão dupla (float64). . . Defina isto como True para retornar valores de coluna DECIMAL como números decimais (decimal.Decimal) ao chamar os métodos fetch_pandas_all() e fetch_pandas_batches(). . . Este parâmetro foi introduzido na versão 2.4.3 do conector Snowflake para Python.

socket_timeout

Tempo limite em segundos para solicitações de leitura e conexão em nível de soquete. Para obter mais informações, consulte Gerenciamento de tempos limite de conexão.

backoff_policy

Nome da função geradora que define quanto tempo esperar entre novas tentativas. Para obter mais informações, consulte Gerenciamento de políticas de espera de conexão para novas tentativas.

Atributos

Error, Warning, ...

Todas as classes de exceção definidas pelo padrão de API do banco de dados Python. O conector do Snowflake para Python fornece os atributos msg, errno, sqlstate, sfqid e raw_msg.

Notas de uso para o parâmetro account (para o método connect)

Para o parâmetro obrigatório account, especifique seu identificador de conta.

Observe que o identificador de conta não inclui o nome de domínio snowflakecomputing.com. O Snowflake o acrescenta automaticamente ao criar a conexão.

O exemplo a seguir usa um identificador de conta que especifica myaccount na organização myorganization:

ctx = snowflake.connector.connect(
    user='<user_name>',
    password='<password>',
    account='myorganization-myaccount',
    ... )
Copy

O exemplo a seguir usa o localizador de conta xy12345 como identificador de conta:

ctx = snowflake.connector.connect(
    user='<user_name>',
    password='<password>',
    account='xy12345',
    ... )
Copy

Note que este exemplo usa uma conta na Região Oeste dos EUA (Oregon) da AWS. Se a conta estiver em uma região diferente ou se a conta usar um provedor de nuvem diferente, será necessário especificar segmentos adicionais após o localizador de conta.

Objeto: Connection

Um objeto Connection mantém a conexão e as informações da sessão para manter a conexão do banco de dados ativa. Se ela for encerrada ou se a sessão expirar, quaisquer operações subsequentes falharão.

Métodos

autocommit(True|False)
Objetivo

Habilita ou desabilita o modo de confirmação automática. Por padrão, a confirmação automática está habilitada (True).

close()
Objetivo

Fecha a conexão. Se uma transação ainda estiver aberta quando a conexão for fechada, as alterações são revertidas.

Fechar a conexão remove explicitamente a sessão ativa do servidor; caso contrário, a sessão ativa continua até ser eventualmente limpa do servidor, limitando o número de consultas simultâneas.

Por exemplo:

# context manager ensures the connection is closed
with snowflake.connector.connect(...) as con:
    con.cursor().execute(...)

# try & finally to ensure the connection is closed.
con = snowflake.connector.connect(...)
try:
    con.cursor().execute(...)
finally:
    con.close()
Copy
commit()
Objetivo

Se a confirmação automática estiver desabilitada, confirma a transação atual. Se a confirmação automática estiver habilitada, este método é ignorado.

rollback()
Objetivo

Se a confirmação automática estiver desabilitada, reverte a transação atual. Se a confirmação automática estiver habilitada, este método é ignorado.

cursor()
Objetivo

Construtor para a criação de um objeto Cursor. Os valores de retorno das chamadas fetch*() serão uma única sequência ou uma lista de sequências.

cursor(snowflake.connector.DictCursor)
Objetivo

Construtor para a criação de um objeto DictCursor. Os valores de retorno das chamadas fetch*() serão um único dict ou uma lista de objetos dict. Isto é útil para obter valores por nome de coluna a partir dos resultados.

execute_string(sql_text, remove_comments=False, return_cursors=True)
Objetivo

Execute uma ou mais instruções SQL passadas como cadeia de caracteres. Se remove_comments estiver definido como True, os comentários são removidos da consulta. Se return_cursors estiver definido como True, este método retorna uma sequência de objetos Cursor na ordem de execução.

Exemplo

Este exemplo mostra a execução de comandos múltiplos em uma única cadeia de caracteres e depois o uso da sequência de cursores que é retornada:

cursor_list = connection1.execute_string(
    "SELECT * FROM testtable WHERE col1 LIKE 'T%';"
    "SELECT * FROM testtable WHERE col2 LIKE 'A%';"
    )

for cursor in cursor_list:
   for row in cursor:
      print(row[0], row[1])
Copy

Nota

Métodos como execute_string() que permitem múltiplas instruções SQL em uma única cadeia são vulneráveis a ataques de injeção SQL. Evite usar concatenação de cadeias de caracteres, ou funções como format() do Python, para compor dinamicamente uma instrução SQL combinando SQL com dados dos usuários, a menos que você tenha validado os dados de usuário. O exemplo abaixo demonstra o problema:

# "Binding" data via the format() function (UNSAFE EXAMPLE)
value1_from_user = "'ok3'); DELETE FROM testtable WHERE col1 = 'ok1'; select pi("
sql_cmd = "insert into testtable(col1) values('ok1'); "                  \
          "insert into testtable(col1) values('ok2'); "                  \
          "insert into testtable(col1) values({col1});".format(col1=value1_from_user)
# Show what SQL Injection can do to a composed statement.
print(sql_cmd)

connection1.execute_string(sql_cmd)
Copy

A instrução composta dinamicamente parece ser (novas linhas foram adicionadas para facilitar a leitura):

insert into testtable(col1) values('ok1');
insert into testtable(col1) values('ok2');
insert into testtable(col1) values('ok3');
DELETE FROM testtable WHERE col1 = 'ok1';
select pi();
Copy

Se você estiver combinando instruções SQL com cadeias de caracteres inseridas por usuários não confiáveis, então é mais seguro vincular dados a uma instrução do que compor uma cadeia. O método execute_string() não aceita vincular parâmetros; portanto, para isso, utilize Cursor.execute() ou Cursor.executemany().

execute_stream(sql_stream, remove_comments=False)
Objetivo

Execute uma ou mais instruções SQL passadas como um objeto de fluxo. Se remove_comments estiver definido como True, os comentários são removidos da consulta. Este gerador produz cada objeto Cursor conforme instruções SQL são executadas.

get_query_status(query_id)
Objetivo

Retorna o status de uma consulta.

Parâmetros

query_id

Retornos

Retorna o objeto QueryStatus que representa o status da consulta.

Exemplo

Consulte Verificação do status de uma consulta.

get_query_status_throw_if_error(query_id)
Objetivo

Retorna o status de uma consulta. Se a consulta resultar em um erro, este método gera um ProgrammingError (como faria o método execute()).

Parâmetros

query_id

Retornos

Retorna o objeto QueryStatus que representa o status da consulta.

Exemplo

Consulte Verificação do status de uma consulta.

is_still_running(query_status)
Objetivo

Retorna True se o status da consulta indicar que a consulta ainda não foi concluída ou ainda está em processo.

Parâmetros

query_status

O objeto QueryStatus que representa o status da consulta. Para obter este objeto para uma consulta, consulte Verificação do status de uma consulta.

Exemplo

Consulte Verificação do status de uma consulta.

is_an_error(query_status)
Objetivo

Retorna True se o status da consulta indicar que a consulta resultou em um erro.

Parâmetros

query_status

O objeto QueryStatus que representa o status da consulta. Para obter este objeto para uma consulta, consulte Verificação do status de uma consulta.

Exemplo

Consulte Verificação do status de uma consulta.

Atributos

expired

Rastreia se o token mestre da conexão expirou.

messages

O objeto de lista incluindo sequências (classe de exceção, valor de exceção) para todas as mensagens recebidas do banco de dados subjacente para esta conexão.

A lista é limpa automaticamente por qualquer chamada de método.

errorhandler

Atributo de leitura/gravação que faz referência a um manipulador de erros a chamar no caso de uma condição de erro ser atendida.

O manipulador deve ser chamável por Python e aceitar os seguintes argumentos:

errorhandler(connection, cursor, errorclass, errorvalue)

Error, Warning, ...

Todas as classes de exceção definidas pelo padrão de API do banco de dados Python.

Objeto: Cursor

Um objeto Cursor representa um cursor de banco de dados para executar e buscar operações. Cada cursor tem seus próprios atributos, description e rowcount, de modo que os cursores são isolados.

Métodos

close()
Objetivo

Fecha o objeto do cursor.

describe(command [, parameters][, timeout][, file_stream])
Objetivo

Retorna metadados sobre o conjunto de resultados sem executar um comando de banco de dados. Isto retorna os mesmos metadados que estão disponíveis no atributo description após a execução de uma consulta.

Este método foi introduzido na versão 2.4.6 do conector do Snowflake para Python.

Parâmetros

Consulte os parâmetros para o método execute().

Retornos

Retorna uma lista de objetos ResultMetadata que descrevem as colunas no conjunto de resultados.

Exemplo

Consulte Recuperação de metadados de coluna.

execute(command [, parameters][, timeout][, file_stream])
Objetivo

Prepara e executa um comando de banco de dados.

Parâmetros

command

Uma cadeia de caracteres contendo a instrução SQL a executar.

parameters

(Opcional) Se você usou parâmetros para vinculação de dados na instrução SQL, defina com a lista ou dicionário de variáveis que devem ser vinculadas a esses parâmetros.

Para obter mais informações sobre o mapeamento dos tipos de dados Python para as variáveis aos tipos de dados SQL das colunas correspondentes, consulte Mapeamentos de tipo de dados para vinculações qmark e numeric.

timeout

(Opcional) Número de segundos a esperar para que a consulta seja concluída. Se a consulta não tiver sido concluída após este tempo, deverá ser cancelada.

file_stream

(Opcional) Ao executar um comando PUT, você pode usar este parâmetro para carregar um objeto semelhante a um arquivo na memória (por exemplo, o objeto I/O retornado da função Python open()), em vez de um arquivo no sistema de arquivos. Defina este parâmetro com aquele objeto I/O.

Ao especificar o URI para o arquivo de dados no comando PUT:

  • Você pode usar qualquer caminho de diretório. O caminho do diretório que você especifica no URI é ignorado.

  • Para o nome do arquivo, especifique o nome do arquivo que deve ser criado no estágio.

Por exemplo, para carregar um arquivo de um fluxo de arquivos para um arquivo nomeado:

@mystage/myfile.csv
Copy

use a seguinte chamada:

cursor.execute(
    "PUT file://this_directory_path/is_ignored/myfile.csv @mystage",
    file_stream=<io_object>)
Copy
Retornos

Retorna a referência de um objeto Cursor.

executemany(command, seq_of_parameters)
Objetivo

Prepara um comando de banco de dados e o executa para todas as sequências de parâmetros encontradas em seq_of_parameters. Você pode usar este método para executar uma operação de inserção em lote.

Parâmetros

command

O comando é uma cadeia de caracteres contendo o código a ser executado. A cadeia de caracteres deve conter um ou mais espaços reservados (como pontos de interrogação) para Vinculação de dados.

Por exemplo:

"insert into testy (v1, v2) values (?, ?)"
Copy

seq_of_parameters

Deve ser uma sequência (lista ou tupla) de listas ou tuplas. Consulte o código abaixo para exemplos de sequências.

Retornos

Retorna a referência de um objeto Cursor.

Exemplo
# This example uses qmark (question mark) binding, so
# you must configure the connector to use this binding style.
from snowflake import connector
connector.paramstyle='qmark'

stmt1 = "create table testy (V1 varchar, V2 varchar)"
cs.execute(stmt1)

# A list of lists
sequence_of_parameters1 = [ ['Smith', 'Ann'], ['Jones', 'Ed'] ]
# A tuple of tuples
sequence_of_parameters2 = ( ('Cho', 'Kim'), ('Cooper', 'Pat') )

stmt2 = "insert into testy (v1, v2) values (?, ?)"
cs.executemany(stmt2, sequence_of_parameters1)
cs.executemany(stmt2, sequence_of_parameters2)
Copy

Internamente, múltiplos métodos execute são chamados e o resultado definido com a última chamada execute permanecerá.

Nota

O método executemany só pode ser usado para executar uma única instrução SQL parametrizada e passar a ela múltiplos valores de vinculação.

A execução de múltiplas instruções SQL separadas por ponto e vírgula em uma chamada execute não é aceita. Em vez disso, emita uma chamada execute separada para cada instrução.

execute_async(...)
Objetivo

Prepara e envia um comando de banco de dados para execução assíncrona. Consulte Realização de uma consulta assíncrona.

Parâmetros

Este método usa os mesmos parâmetros que o método execute().

Retornos

Retorna a referência de um objeto Cursor.

Exemplo

Consulte Exemplos de consultas assíncronas.

fetch_arrow_all()
Objetivo

Este método busca todas as linhas em um cursor e as carrega em uma tabela PyArrow.

Parâmetros

Nenhum.

Retornos

Retorna uma tabela PyArrow contendo todas as linhas do conjunto de resultados.

Se não houver linhas, retorna None (nenhum).

Exemplo

Consulte Distribuição de cargas de trabalho que obtêm resultados com o Conector Snowflake para Python.

fetch_arrow_batches()
Objetivo

Este método busca um subconjunto das linhas em um cursor e as entrega em uma tabela PyArrow.

Parâmetros

Nenhum.

Retornos

Retorna uma tabela PyArrow contendo um subconjunto das linhas do conjunto de resultados.

Retorna None se não houver mais linhas a serem buscadas.

Exemplo

Consulte Distribuição de cargas de trabalho que obtêm resultados com o Conector Snowflake para Python.

get_result_batches()
Objetivo

Retorna uma lista de objetos ResultBatch que você pode usar para buscar um subconjunto de linhas do conjunto de resultados.

Parâmetros

Nenhum.

Retornos

Retorna uma lista de objetos ResultBatch ou None se a consulta não tiver terminado de ser executada.

Exemplo

Consulte Distribuição de cargas de trabalho que obtêm resultados com o Conector Snowflake para Python.

get_results_from_sfqid(query_id)
Objetivo

Recupera os resultados de uma consulta assíncrona ou de uma consulta síncrona previamente enviada.

Parâmetros

query_id

Exemplo

Consulte Uso do ID de consulta para recuperar os resultados de uma consulta.

fetchone()
Objetivo

Busca a próxima linha de um conjunto de resultados de consulta e retorna uma única sequência/dict ou None quando não houver mais dados disponíveis.

fetchmany([size=cursor.arraysize])
Objetivo

Busca as próximas linhas de um conjunto de resultados de consulta e retorna uma lista de sequências/dict. Uma sequência vazia é retornada quando não há mais linhas disponíveis.

fetchall()
Objetivo

Busca todas as linhas ou as linhas restantes de um conjunto de resultados de consulta e retorna uma lista de sequências/dict.

fetch_pandas_all()
Objetivo

Este método busca todas as linhas em um cursor e as carrega em um pandas DataFrame.

Parâmetros

Nenhum.

Retornos

Retorna um DataFrame contendo todas as linhas do conjunto de resultados. Para obter mais informações sobre dataframes pandas, consulte a documentação pandas DataFrame.

Se não houver linhas, retorna None (nenhum).

Notas de uso
  • Este método não substitui completamente o método read_sql() do pandas; é uma maneira rápida de recuperar dados de uma consulta SELECT e armazenar os dados em um pandas DataFrame.

  • Atualmente, este método funciona apenas para instruções SELECT.

Exemplos
ctx = snowflake.connector.connect(
          host=host,
          user=user,
          password=password,
          account=account,
          warehouse=warehouse,
          database=database,
          schema=schema,
          protocol='https',
          port=port)

# Create a cursor object.
cur = ctx.cursor()

# Execute a statement that will generate a result set.
sql = "select * from t"
cur.execute(sql)

# Fetch the result set from the cursor and deliver it as the pandas DataFrame.
df = cur.fetch_pandas_all()

# ...
Copy
fetch_pandas_batches()
Objetivo

Este método busca um subconjunto das linhas em um cursor e as entrega em um pandas DataFrame.

Parâmetros

Nenhum.

Retornos

Retorna um DataFrame contendo um subconjunto das linhas do conjunto de resultados. Para obter mais informações sobre dataframes pandas, consulte a documentação pandas DataFrame.

Retorna None se não houver mais linhas a serem buscadas.

Notas de uso
  • Dependendo do número de linhas no conjunto de resultados, assim como do número de linhas especificadas na chamada do método, o método pode precisar ser chamado mais de uma vez, ou pode retornar todas as linhas em um único lote, caso caibam.

  • Este método não substitui completamente o método read_sql() do pandas; é uma maneira rápida de recuperar dados de uma consulta SELECT e armazenar os dados em um pandas DataFrame.

  • Atualmente, este método funciona apenas para instruções SELECT.

Exemplos
ctx = snowflake.connector.connect(
          host=host,
          user=user,
          password=password,
          account=account,
          warehouse=warehouse,
          database=database,
          schema=schema,
          protocol='https',
          port=port)

# Create a cursor object.
cur = ctx.cursor()

# Execute a statement that will generate a result set.
sql = "select * from t"
cur.execute(sql)

# Fetch the result set from the cursor and deliver it as the pandas DataFrame.
for df in cur.fetch_pandas_batches():
    my_dataframe_processing_function(df)

# ...
Copy
__iter__()

Retorna a si próprio para tornar os cursores compatíveis com o protocolo de iteração.

Atributos

description

Atributo somente leitura que retorna metadados sobre as colunas no conjunto de resultados.

Este atributo é definido após você chamar o método execute() para executar a consulta. (Na versão 2.4.6 ou posterior, você pode recuperar estes metadados sem executar a consulta chamando o método describe()).

Este atributo é definido para um dos seguintes:

  • Versões 2.4.5 e anteriores: Este atributo é definido para uma lista de tuplas.

  • Versões 2.4.6 e posteriores: Este atributo é definido para uma lista de objetos ResultMetadata.

Cada tupla ou objeto ResultMetadata contém os metadados que descrevem uma coluna no conjunto de resultados. Você pode acessar os metadados por índice ou, nas versões 2.4.6 e posteriores, por atributo de objeto ResultMetadata:

Índice de valor

Atributo ResultMetadata

Descrição

0

name

Nome da coluna.

1

type_code

Código de tipo interno.

2

display_size

(Não usado. O mesmo que internal_size).

3

internal_size

Tamanho dos dados internos.

4

precision

Precisão dos dados numéricos.

5

scale

Escala para dados numéricos.

6

is_nullable

True se valores NULL permitidos para a coluna ou False.

Para exemplos de como obter este atributo, consulte Recuperação de metadados de coluna.

rowcount

Atributo somente leitura que retorna o número de linhas no último execute produzido. O valor é -1 ou None se nenhum execute for executado.

sfqid

Atributo somente leitura que retorna a ID de consulta do Snowflake no último execute ou execute_async executado.

arraysize

Atributo de leitura/gravação que especifica o número de linhas a serem buscadas de cada vez com fetchmany(). O padrão é 1, o que significa buscar uma única linha de cada vez.

connection

Atributo somente leitura que retorna uma referência ao objeto Connection sobre o qual o cursor foi criado.

messages

Objeto de lista que inclui as sequências (classe de exceção, valor de exceção) para todas as mensagens que recebeu do banco de dados subjacente para o cursor.

A lista é limpa automaticamente por qualquer chamada de método, exceto por chamadas fetch*().

errorhandler

Atributo de leitura/gravação que faz referência a um manipulador de erros a chamar no caso de uma condição de erro ser atendida.

O manipulador deve ser chamável por Python e aceitar os seguintes argumentos:

errorhandler(connection, cursor, errorclass, errorvalue)

Códigos de tipo

No objeto Cursor, o atributo description e o método describe() fornecem uma lista de tuplas (ou, nas versões 2.4.6 e posteriores, objetos ResultMetadata) que descrevem as colunas no conjunto de resultados.

Em uma tupla, o valor no índice 1 (o atributo type_code no objeto ResultMetadata) representa o tipo de dados da coluna. O conector Snowflake para Python usa o seguinte mapa para obter a representação da cadeia de caracteres, com base no código do tipo:

type_code

Representação da cadeia de caracteres

Tipo de dados

0

FIXED

NUMBER/INT

1

REAL

REAL

2

TEXT

VARCHAR/STRING

3

DATE

DATE

4

TIMESTAMP

TIMESTAMP

5

VARIANT

VARIANT

6

TIMESTAMP_LTZ

TIMESTAMP_LTZ

7

TIMESTAMP_TZ

TIMESTAMP_TZ

8

TIMESTAMP_NTZ

TIMESTAMP_TZ

9

OBJECT

OBJECT

10

ARRAY

ARRAY

11

BINARY

BINARY

12

TIME

TIME

13

BOOLEAN

BOOLEAN

Mapeamentos de tipo de dados para vinculações qmark e numeric

Se paramstyle for "qmark" ou "numeric", são usados os seguintes mapeamentos padrão do tipo de dados Python para o Snowflake:

Tipo de dados Python

Tipo de dados Snowflake

int

NUMBER(38, 0)

long

NUMBER(38, 0)

decimal

NUMBER(38, <escala>)

float

REAL

str

TEXT

unicode

TEXT

bytes

BINARY

bytearray

BINARY

bool

BOOLEAN

date

DATE

time

TIME

timedelta

TIME

datetime

TIMESTAMP_NTZ

struct_time

TIMESTAMP_NTZ

Se você precisar mapear para outro tipo do Snowflake (por exemplo, datetime para TIMESTAMP_LTZ), especifique o tipo de dados do Snowflake em uma tupla que consiste no tipo de dados do Snowflake seguido do valor. Consulte Data/hora da vinculação com TIMESTAMP para exemplos.

Objeto: Exception

O PEP-249 define as exceções que o conector do Snowflake para Python pode gerar em caso de erros ou avisos. O aplicativo precisa tratá-los adequadamente e decidir continuar ou parar de executar o código.

Métodos

Nenhum método está disponível para objetos Exception.

Atributos

errno

Código de erro de DB do Snowflake.

msg

Mensagem de erro incluindo código de erro, código do estado SQL e ID da consulta.

raw_msg

Mensagem de erro. Nenhum código de erro, código do estado SQL ou ID de consulta é incluído.

sqlstate

Código de estado SQL compatível com ANSI

sfqid

ID de consulta do Snowflake.

Objeto ResultBatch

Um objeto ResultBatch encapsula uma função que recupera um subconjunto de linhas em um conjunto de resultados. Para distribuir o trabalho de obtenção de resultados por múltiplos trabalhadores ou nós, você pode chamar o método get_result_batches() no objeto Cursor para recuperar uma lista de objetos ResultBatch e distribuir esses objetos para diferentes trabalhadores ou nós para processamento.

Atributos

rowcount

Atributo somente leitura que retorna o número de linhas no lote de resultados.

compressed_size

Atributo somente leitura que retorna o tamanho dos dados (quando compactados) no lote de resultados.

uncompressed_size

Atributo somente leitura que retorna o tamanho dos dados (não compactados) no lote de resultados.

Métodos

to_arrow()
Objetivo

Este método retorna uma tabela PyArrow contendo as linhas do objeto ResultBatch.

Parâmetros

Nenhum.

Retornos

Retorna uma tabela PyArrow contendo as linhas do objeto ResultBatch.

Se não houver linhas, retorna None (nenhum).

to_pandas()
Objetivo

Este método retorna um pandas DataFrame contendo as linhas no objeto ResultBatch.

Parâmetros

Nenhum.

Retornos

Retorna um Pandas DataFrame contendo as linhas do objeto ResultBatch.

Se não houver linhas, retorna um pandas DataFrame vazio.

Objeto: ResultMetadata

Um objeto ResultMetadata representa metadados sobre uma coluna no conjunto de resultados. Uma lista desses objetos é retornada pelo atributo description e pelo método describe do objeto Cursor.

Este objeto foi introduzido na versão 2.4.6 do conector do Snowflake para Python.

Métodos

Nenhum.

Atributos

name

Nome da coluna

type_code

Código de tipo interno.

display_size

Não usado. O mesmo que internal_size.

internal_size

Tamanho dos dados internos.

precision

Precisão dos dados numéricos.

scale

Escala para dados numéricos.

is_nullable

True se valores NULL permitidos para a coluna ou False.

Módulo: snowflake.connector.constants

O módulo snowflake.connector.constants define as constantes usadas na API.

Enumerações

class QueryStatus

Representa o status de uma consulta assíncrona. Esta enumeração tem as seguintes constantes:

Constante de enumeração

Descrição

RUNNING

A consulta ainda está em andamento.

ABORTING

A consulta está em processo de ser cancelada no lado do servidor.

SUCCESS

A consulta foi concluída com sucesso.

FAILED_WITH_ERROR

A consulta foi concluída sem sucesso.

QUEUED

A consulta está enfileirada para execução (ou seja, ainda não começou a funcionar), normalmente porque está esperando por recursos.

DISCONNECTED

A conexão da sessão está quebrada. O estado da consulta mudará para “FAILED_WITH_ERROR“ em breve.

RESUMING_WAREHOUSE

O warehouse está iniciando e a consulta ainda não está em andamento.

BLOCKED

A instrução está à espera de um bloqueio mantido por outra instrução.

NO_DATA

Os dados sobre a instrução ainda não estão disponíveis, normalmente porque a instrução ainda não começou a ser executada.

Módulo: snowflake.connector.pandas_tools

O módulo snowflake.connector.pandas_tools fornece funções para trabalhar com a biblioteca de análise de dados pandas.

Funções

write_pandas(parameters...)
Objetivo

Grava um pandas DataFrame em uma tabela de um banco de dados Snowflake.

Para gravar os dados na tabela, a função salva os dados em arquivos Parquet, usa o comando PUT para carregar esses arquivos em um estágio temporário e usa o comando COPY INTO <tabela> para copiar os dados dos arquivos para a tabela. Você pode usar alguns dos parâmetros da função para controlar como as instruções PUT e COPY INTO <tabela> são executadas.

Parâmetros

Os parâmetros de entrada válidos são:

Parâmetro

Obrigatório

Descrição

conn

Sim

Objeto Connection que mantém a conexão com o banco de dados Snowflake.

df

Sim

Objeto pandas.DataFrame contendo os dados a serem copiados para a tabela.

table_name

Sim

Nome da tabela onde os dados devem ser copiados.

database

Nome do banco de dados que contém a tabela. Por padrão, a função grava no banco de dados sendo utilizado na sessão. Nota: Se você especificar este parâmetro, também deve especificar o parâmetro schema.

schema

Nome do esquema que contém a tabela. Por padrão, a função grava na tabela do esquema que está em uso na sessão.

chunk_size

Número de elementos a serem inseridos de cada vez. Por padrão, a função insere todos os elementos de uma só vez como uma parte.

compression

O algoritmo de compactação a ser usado para os arquivos Parquet. Você pode especificar "gzip" para melhor compactação ou "snappy" para compactação mais rápida. Por padrão, a função utiliza "gzip".

on_error

Especifica como os erros devem ser tratados. Defina como um dos valores de cadeia de caracteres documentados na opção ON_ERROR copiar. Por padrão, a função utiliza "ABORT_STATEMENT".

parallel

Número de threads a serem utilizados ao carregar os arquivos Parquet no estágio temporário. Para o número padrão de threads utilizados e diretrizes sobre a escolha do número de threads, consulte o parâmetro paralelo do comando PUT.

quote_identifiers

Se False, impede o conector de usar aspas duplas ao redor dos identificadores antes de enviar os identificadores para o servidor. Por padrão, o conector usa aspas duplas em torno dos identificadores.

Retornos

Retorna uma tupla de (success, num_chunks, num_rows, output) onde:

  • success é True se a função tiver gravado com sucesso os dados na tabela.

  • num_chunks é o número de partes de dados que a função copiou.

  • num_rows é o número de linhas que a função inseriu.

  • output é a saída do comando COPY INTO <tabela>.

Exemplo

O exemplo seguinte grava os dados de um pandas DataFrame na tabela chamada “customers”.

import pandas
from snowflake.connector.pandas_tools import write_pandas

# Create the connection to the Snowflake database.
cnx = snowflake.connector.connect(...)

# Create a DataFrame containing data about customers
df = pandas.DataFrame([('Mark', 10), ('Luke', 20)], columns=['name', 'balance'])

# Write the data from the DataFrame to the table named "customers".
success, nchunks, nrows, _ = write_pandas(cnx, df, 'customers')
Copy
pd_writer(parameters...)
Objetivo

pd_writer é um método de inserção para inserção de dados em um banco de dados Snowflake.

Ao chamar pandas.DataFrame.to_sql (consulte a documentação do pandas), passe method=pd_writer para especificar que você deseja usar pd_writer como método para inserção de dados. (Você não precisa chamar pd_writer a partir de seu próprio código. O método to_sql chama pd_writer e fornece os parâmetros de entrada necessários).

Nota

Observe que quando os nomes das colunas no pandas DataFrame contêm apenas letras minúsculas, você deve colocar os nomes das colunas entre aspas duplas; caso contrário, o conector gerará um ProgrammingError.

A biblioteca snowflake-sqlalchemy não coloca nomes de colunas em letras minúsculas ao criar uma tabela, enquanto pd_writer coloca os nomes de colunas entre aspas. O problema surge porque o comando COPY INTO espera que os nomes das colunas sejam colocados entre aspas.

Melhorias futuras serão feitas na biblioteca snowflake-sqlalchemy.

Por exemplo:

import pandas as pd
from snowflake.connector.pandas_tools import pd_writer

sf_connector_version_df = pd.DataFrame([('snowflake-connector-python', '1.0')], columns=['NAME', 'NEWEST_VERSION'])

# Specify that the to_sql method should use the pd_writer function
# to write the data from the DataFrame to the table named "driver_versions"
# in the Snowflake database.
sf_connector_version_df.to_sql('driver_versions', engine, index=False, method=pd_writer)

# When the column names consist of only lower case letters, quote the column names
sf_connector_version_df = pd.DataFrame([('snowflake-connector-python', '1.0')], columns=['"name"', '"newest_version"'])
sf_connector_version_df.to_sql('driver_versions', engine, index=False, method=pd_writer)
Copy

A função pd_writer utiliza a função write_pandas() para gravar os dados do DataFrame no banco de dados Snowflake.

Parâmetros

Os parâmetros de entrada válidos são:

Parâmetro

Obrigatório

Descrição

table

Sim

Objeto pandas.io.sql.SQLTable para a tabela.

conn

Sim

Objeto sqlalchemy.engine.Engine ou sqlalchemy.engine.Connection usado para conectar ao banco de dados Snowflake.

keys

Sim

Nomes das colunas da tabela para os dados a serem inseridos.

data_iter

Sim

Iterador para as linhas que contêm os dados a serem inseridos.

Exemplo

O exemplo seguinte passa method=pd_writer para o método pandas.DataFrame.to_sql, que por sua vez chama a função pd_writer para gravar os dados do pandas DataFrame em um banco de dados Snowflake.

import pandas
from snowflake.connector.pandas_tools import pd_writer

# Create a DataFrame containing data about customers
df = pandas.DataFrame([('Mark', 10), ('Luke', 20)], columns=['name', 'balance'])

# Specify that the to_sql method should use the pd_writer function
# to write the data from the DataFrame to the table named "customers"
# in the Snowflake database.
df.to_sql('customers', engine, index=False, method=pd_writer)
Copy

Suporte para data e carimbo de data/hora

O Snowflake tem suporte para múltiplos tipos de dados DATE e TIMESTAMP, e o conector do Snowflake permite vincular objetos nativos datetime e date para operações de atualização e de busca.

Busca de dados

Ao buscar dados de data e hora, os tipos de dados do Snowflake são convertidos em tipos de dados do Python:

Tipos de dados do Snowflake

Tipo de dados Python

Comportamento

TIMESTAMP_TZ

datetime com tzinfo

Busca dados, incluindo a diferença de fuso horário, e os converte em um datetime com o objeto tzinfo.

TIMESTAMP_LTZ, TIMESTAMP

datetime com tzinfo

Busca dados, converte os dados em um objeto datetime e anexa tzinfo com base no parâmetro de sessão TIMESTAMP_TYPE_MAPPING.

TIMESTAMP_NTZ

datetime

Busca dados e os converte em um objeto datetime. Nenhuma informação de fuso horário é anexada ao objeto.

DATE

date

Busca dados e os converte em um objeto date. Nenhuma informação de fuso horário é anexada ao objeto.

Nota

tzinfo é um objeto de fuso horário baseado em diferença UTC e não nomes de fuso horário IANA. Os nomes de fuso horário podem não coincidir, mas objetos equivalentes baseados na diferença de fuso horário são considerados idênticos.

Atualização de dados

Ao atualizar os dados de data e hora, os tipos de dados do Python são convertidos em tipos de dados do Snowflake:

Tipo de dados Python

Tipos de dados do Snowflake

Comportamento

datetime

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Converte um objeto datetime em uma cadeia de caracteres no formato de YYYY-MM-DD HH24:MI:SS.FF TZH:TZM e a atualiza. Se não for fornecida uma diferença de fuso horário, a cadeia estará no formato de YYYY-MM-DD HH24:MI:SS.FF. O usuário é responsável por definir o tzinfo para o objeto datetime.

struct_time

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Converte um objeto struct_time em uma cadeia de caracteres no formato de YYYY-MM-DD HH24:MI:SS.FF TZH:TZM e a atualiza. A informação de fuso horário é recuperada de time.timezone, o que inclui a diferença de fuso horário do UTC. O usuário é responsável por definir a variável de ambiente TZ para time.timezone.

data

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Converte um objeto date em uma cadeia de caracteres no formato de YYYY-MM-DD. Nenhum fuso horário é considerado.

hora

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Converte um objeto time em uma cadeia de caracteres no formato de HH24:MI:SS.FF. Nenhum fuso horário é considerado.

timedelta

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Converte um objeto timedelta em uma cadeia de caracteres no formato de HH24:MI:SS.FF. Nenhum fuso horário é considerado.