API do conector Python¶

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%AppDataLocalSnowflakeCachesocsp_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.
		username_password_mfa para autenticar com o armazenamento em cache de tokens MFA. Para obter mais detalhes, consulte Uso do armazenamento em cache de tokens MFA para minimizar o número de tentativas durante a autenticação — opcional.
		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',
    ... )

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',
    ... )

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.

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

A ID da consulta. Consulte Recuperação da ID de consulta do Snowflake.

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

A ID da consulta. Consulte Recuperação da ID de consulta do Snowflake.

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.

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

A ID da consulta. Consulte Recuperação da ID de consulta do Snowflake.

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:

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:

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.

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.

Atributos¶

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.

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.

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.

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

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:

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: