Referência de opções do Node.js¶

Opções de conexão necessárias¶

account

Seu identificador de conta.

region (Obsoleto)

A ID para a região onde sua conta está localizada.

Nota

Esta opção é obsoleta e está incluída aqui apenas para compatibilidade retroativa. O Snowflake recomenda a transição para incorporar a região no identificador de conta, como descrito em Uso de um localizador de contas como identificador, como a seguir.

var connection = snowflake.createConnection({
  account: "myaccount.us-east-2",
  username: "myusername",
  password: "mypassword"
});

Copy

Além disso, é necessário especificar as opções para autenticação no servidor.

Opções de autenticação¶

application

Especifica o nome do aplicativo do cliente que conecta ao Snowflake.

authenticator

Especifica o autenticador a ser usado para verificar as credenciais de login de usuário. Você pode definir isto para um dos seguintes valores:

Valor	Descrição
SNOWFLAKE	Use o autenticador interno do Snowflake. Você também deve definir a opção password.
EXTERNALBROWSER	Use seu navegador para autenticar com Okta, AD FS ou qualquer outro provedor de identidade compatível com SAML 2.0 (IdP) que tenha sido definido para sua conta.
https://<okta_account_name>.okta.com	Use SSO nativo através do Okta.
OAUTH	Use OAuth para autenticação. Você também deve definir a opção token para o token OAuth (consulte abaixo).
SNOWFLAKE_JWT	Use autenticação de par de chaves. Consulte Use autenticação de par de chaves e rotação de par de chaves.
USERNAME_PASSWORD_MFA	Use autenticação multifator (MFA). Consulte Use uma senha numérica MFA.
OAUTH_AUTHORIZATION_CODE	Autentique-se manualmente usando um código de autorização OAuth com seu navegador da Web e um provedor de identidade escolhido (incluindo Snowflake como IdP). Para obter mais informações, consulte Usar o fluxo do código de autorização OAuth 2.0.
OAUTH_CLIENT_CREDENTIALS	Autentique-se automaticamente usando as credenciais de cliente OAuth com o provedor de identidade escolhido (o Snowflake como IdP não é compatível com o fluxo de credenciais de cliente). Para obter mais informações, consulte Usar o fluxo de credenciais de cliente OAuth 2.0.
PROGRAMMATIC_ACCESS_TOKEN	Autenticar com um token de acesso programático (PAT). Ele lê o token das opções :codenowrap:.`token` ou password. Para obter mais informações, consulte Uso de tokens de acesso programático para autenticação.
WORKLOAD_IDENTITY	Autenticar com o autenticador de federação de identidade de carga de trabalho (WIF).

O valor padrão é SNOWFLAKE.

Para obter mais informações sobre autenticação, consulte Gerenciamento/uso da autenticação federada e Clientes, drivers e conectores.

username

O nome de login para seu usuário Snowflake ou seu provedor de identidade (por exemplo, seu nome de login para Okta). Defina esta opção se você definir a opção authenticator como SNOWFLAKE, SNOWFLAKE_JWT ou o ponto de extremidade do URL Okta para sua conta Okta (por exemplo, https://<okta_account_name>.okta.com). Se você não definir a opção authenticator, deverá definir esse valor.

password

Senha do usuário. Defina esta opção se você definir a opção authenticator para SNOWFLAKE ou o ponto de extremidade da URL Okta para sua conta Okta (por exemplo, https://<okta_account_name>.okta.com) ou se você deixar a opção authenticator por definir.

Se você definir a opção authenticator para PROGRAMMATIC_ACCESS_TOKEN, poderá passar o token de acesso programático nesta opção.

token

Especifica o token OAuth a ser usado para autenticação ou token de acesso programático. Defina esta opção se você definir a opção authenticator para OAUTH ou PROGRAMMATIC_ACCESS_TOKEN.

privateKey

Especifica a chave privada (em formato PEM) para autenticação do par de chaves. Para obter mais detalhes, consulte Use autenticação de par de chaves e rotação de par de chaves.

privateKeyPath

Especifica o caminho local para o arquivo de chave privada (por exemplo, rsa_key.p8). Para obter mais detalhes, consulte Use autenticação de par de chaves e rotação de par de chaves.

privateKeyPass

Especifica a senha para descriptografar o arquivo de chave privada, se o arquivo estiver criptografado. Para obter mais detalhes, consulte Use autenticação de par de chaves e rotação de par de chaves.

oauthClientId

Valor de client id fornecido pelo provedor de identidade para integração do Snowflake (metadados de integração de segurança do Snowflake).

oauthClientSecret

Valor de client secret fornecido pelo provedor de identidade para integração do Snowflake (metadados de integração de segurança do Snowflake)

oauthAuthorizationUrl

Ponto de extremidade do provedor de identidade que fornece o código de autorização ao driver. Quando o Snowflake é usado como um provedor de identidade, esse valor é derivado dos parâmetros server ou account.

oauthTokenRequestUrl

Ponto de extremidade do provedor de identidade que fornece os tokens de acesso ao driver. Ao usar o Snowflake como um provedor de identidade, esse valor é derivado dos parâmetros server ou account.

oauthScope

Escopo solicitado na solicitação de autorização do provedor de identidade. Por padrão, ele é derivado da função. Quando vários escopos são necessários, o valor deve ser uma lista separada por espaços de vários escopos.

oauthRedirectUri

URI a ser usado para redirecionamento do código de autorização (metadados de integração de segurança do Snowflake). Padrão: http://127.0.0.1:{randomAvailablePort}.

workloadIdentityProvider

Descrição:

Plataforma do provedor de identidade de carga de trabalho. Os valores possíveis incluem: AWS, AZURE, GCP e OIDC.

passcode

Especifica o passcode fornecido pelo Duo ao usar autenticação multifator (MFA) para logins. Para obter mais detalhes, consulte Use uma senha numérica MFA.

passcodeInPassword

Especifica se o passcode MFA está incorporado na senha de login. Se true, a senha numérica MFA é anexada ao fim de password. Padrão: false. Para obter mais detalhes, consulte Use uma senha numérica MFA.

Opções adicionais de conexão¶

accessUrl

Especifica um ponto de extremidade totalmente qualificado para a conexão com o Snowflake. O accessUrl inclui o esquema completo e o host, assim como um número de porta opcional, semelhante ao https://myaccount.us-east-1.snowflakecomputing.com.

Nota

Ao utilizar a opção accessUrl, o valor especificado na opção account não é utilizado.

browserActionTimeout

Especifica o tempo limite, em milissegundos, para atividades do navegador relacionadas à autenticação SSO. O valor padrão é 120000 (milissegundos).

openExternalBrowserCallback

Abre uma janela do navegador para a autenticação SSO. Por padrão, o driver usa o pacote npm open. Por exemplo:

var connection = snowflake.createConnection({
  ...,
  openExternalBrowserCallback: () => {
    // your custom code to open browser window instead of our default implementation
  }
});

Copy

clientConfigFile

Caminho para o arquivo de configuração do cliente associado ao recurso de registro fácil.

clientRequestMFAToken

Define se o driver usa o token MFA no armazenamento de credenciais local para autenticação em vez de solicitar um novo token do servidor. Padrão: false.

clientStoreTemporaryCredential

Define se o driver usa o token SSO no armazenamento de credenciais local para autenticação em vez de solicitar um novo token do servidor. Padrão: false.

clientSessionKeepAlive

Por padrão, as conexões do cliente normalmente atingem o tempo limite cerca de 3-4 horas depois que a consulta mais recente foi executada.

Se a opção clientSessionKeepAlive estiver definida como true, a conexão do cliente com o servidor será mantida indefinidamente, mesmo que nenhuma consulta seja executada.

A configuração padrão desta opção é false.

Se você definir esta opção como true, certifique-se de que seu programa se desconecte explicitamente do servidor quando tiver terminado. Não saia sem desconectar.

clientSessionKeepAliveHeartbeatFrequency

(Aplica-se somente quando clientSessionKeepAlive é verdadeiro)

Define a frequência (intervalo em segundos) entre as mensagens de pulsação.

Pense em uma mensagem de pulsação da conexão como um substituto para uma consulta que reinicia a contagem regressiva do tempo limite para a conexão. Em outras palavras, se o tempo limite da conexão ocorrer após pelo menos 4 horas de inatividade, a pulsação redefine o timer para que o tempo limite não ocorra até pelo menos 4 horas após a pulsação mais recente (ou consulta).

O valor padrão é 3600 segundos (uma hora). O intervalo válido de valores é 900 - 3600. Como o tempo limite normalmente ocorre após pelo menos 4 horas, uma pulsação a cada 1 hora normalmente é suficiente para manter a conexão ativa. Intervalos de pulsação de menos de 3600 segundos raramente são necessários ou úteis.

credentialCacheDir

Define o diretório para armazenar o cache de credenciais quando o cache de token estiver habilitado. Padrão: diretório $HOME do usuário.

database

O banco de dados padrão a ser utilizado para a sessão após a conexão.

disableSamlUrlCheck

Especifica se deve desabilitar a verificação de validação de uma resposta SAML. Padrão: false.

host

Endereço de host ao qual o driver deve se conectar.

keepAlive

Especifica se a funcionalidade keep-alive deve ser habilitada no soquete imediatamente após receber uma nova solicitação de conexão.

Por padrão, o protocolo HTTP cria uma nova conexão TCP para cada solicitação. Habilitar esse parâmetro permite que o driver reutilize conexões para diversas solicitações em vez de criar novas conexões para cada solicitação.

O valor padrão é true.

noProxy

Especifica as listas de hosts aos quais o driver deve se conectar diretamente, ignorando o servidor proxy (por exemplo, *.amazonaws.com para fazer o bypass do acesso do Amazon S3). Para hosts múltiplos, separe os nomes do host com um símbolo de canal (|). Você também pode usar um asterisco como curinga. Por exemplo:

noProxy: "*.amazonaws.com|*.example.com"

proxyHost

Especifica o nome do host de um servidor proxy autenticado.

proxyPassword

Especifica a senha para o usuário especificada por proxyUser.

proxyPort

Especifica a porta de um servidor proxy autenticado.

proxyProtocol

Especifica o protocolo usado para conectar ao servidor proxy autenticado. Use esta propriedade para especificar o protocolo HTTP: http ou https.

proxyUser

Especifica o nome de usuário usado para se conectar a um servidor proxy autenticado.

queryTag

O QUERY_TAG opcional a ser usado para a conexão, para marcar instruções.

role

A função de segurança padrão a ser usada para a sessão após a conexão.

schema

O esquema padrão a ser usado para a sessão após a conexão.

timeout

Número de milissegundos para manter a conexão ativa sem resposta. Padrão: 60000 (1 minuto).

warehouse

O warehouse virtual padrão a ser utilizado para a sessão após a conexão. Utilizado para realizar consultas, carregar dados, etc.

Algumas opções de conexão consideram que o objeto de banco de dados especificado (banco de dados, esquema, warehouse ou função) já existe no sistema. Se o objeto especificado não existir, não é definido um padrão durante a conexão.

Após a conexão, todas as opções opcionais de conexão também podem ser definidas ou substituídas através do comando USE <objeto>.

Opções de configuração¶

arrayBindingThreshold

Define o número máximo de vinculações que o driver utiliza em uma operação de inserção em massa. O valor padrão é 65280.

cwd

Diretório de trabalho atual a ser usado para operações GET e PUt quando for diferente do diretório do conector.

representNullAsStringNull

Especifica como o método fetchAsString retorna valores nulos.

• true (habilitado): retorna valores nulos como a cadeia de caracteres, «NULL».

• false (desabilitado): retorna valores nulos como null.

Padrão: true (habilitado)

resultPrefetch

Número de threads a serem utilizados pelos clientes para pré-buscar grandes conjuntos de resultados. Valores válidos: 1-10.

rowMode

Especifica como retornar resultados que contenham nomes de colunas duplicados. Os valores incluem:

• array: retorna o conjunto de resultados como uma matriz, incluindo nomes de colunas duplicados.

• object: retorna o conjunto de resultados como um objeto, omitindo nomes de colunas duplicados.

• object_with_renamed_duplicated_columns: retorna o conjunto de resultados como um objeto, ao mesmo tempo que adiciona sufixos a nomes duplicados para torná-los únicos.

O valor padrão é object.

Opções de xmlParserConfig¶

A partir da versão 1.7.0 do driver, você pode usar as seguintes opções de configuração da biblioteca fast-xml-parser para personalizar como o driver processa os atributos do documento XML ao consultar colunas com conteúdo XML.

Você pode baixar o fast-xml-parser.

Por padrão, o driver Node.js ignora os atributos do elemento XML ao retornar dados XML de uma consulta. Por exemplo, no conteúdo XML a seguir, o elemento <animal> inclui um atributo id:

<exhibit name="Polar Bear Plunge">
  <animal id="000001">
    <scientificName>Ursus maritimus</scientificName>
    <englishName>Polar Bear</englishName>
    <name>Kalluk</name>
  </animal>
  <animal id="000002">
    <scientificName>Ursus maritimus</scientificName>
    <englishName>Polar Bear</englishName>
    <name>Chinook</name>
  </animal>
</exhibit>

Por padrão, quando o driver Node.js retorna o conjunto de resultados, ele ignora o atributo id e retorna a saída a seguir. Observe que os nomes e valores dos atributos não estão incluídos.

{
  exhibit: {
    animal: [
      {
        "scientificName": "Ursus maritimus",
        "englishName": "Polar Bear",
        "name": "Kalluk",
      },
      {
        "scientificName": "Ursus maritimus",
        "englishName": "Polar Bear",
        "name": "Chinook"
      }
    ]
  }
}

Para obter informações sobre como definir essas opções, consulte Análise de dados XML.

Para ajudar a ilustrar como as opções a seguir afetam o modo como o driver analisa os dados XML, cada descrição de opção mostra como isso afeta este exemplo.

ignoreAttributes

Se deve ignorar atributos XML durante a análise. Se quiser usar as outras opções do analisador, você deverá definir ignoreAttributes: false.

Padrão: true

Quando definido como false, o driver retorna a saída da seguinte forma. Observe que o atributo id agora está incluído na saída (por padrão, o driver adiciona um prefixo @_ aos nomes dos atributos):

{
    exhibit: {
      animal: [
        {
          "scientificName": "Ursus maritimus",
          "englishName": "Polar Bear",
          "name": "Kalluk",
          "@_id": "000001"
        },
        {
          "scientificName": "Ursus maritimus",
          "englishName": "Polar Bear",
          "name": "Chinook",
          "@_id": "000002"
        }
      ],
      "@_name": "Polar Bear Plunge"
    }
}

alwaysCreateTextNode

Se deseja criar uma propriedade com o nome da tag e atribuir o valor diretamente.

Padrão: false

Quando definido como true, o driver retorna a saída da seguinte forma:

{
  exhibit: {
    animal: [
      {
        "scientificName": {
          "#text": "Ursus maritimus"
        },
        "englishName": {
          "#text": "Polar Bear"
        },
        "name": {
          "#text": "Kalluk"
        },
        "@_id": "000001"
      },
      {
        "scientificName": {
          "#text": "Ursus maritimus"
        },
        "englishName": {
          "#text": "Polar Bear"
        },
        "name": {
          "#text": "Chinook"
        },
        "@_id": "000002"
      }
      "@_name": "Polar Bear Plunge"
    ]
  }
}

attributeNamePrefix

Cadeia de caracteres a ser anexada aos nomes de atributos.

Padrão: «@_»

Quando definido como "" para não especificar nenhum prefixo para nomes de atributos, o driver retorna a saída da seguinte forma:

{
    exhibit: {
      animal: [
        {
          "scientificName": "Ursus maritimus",
          "englishName": "Polar Bear",
          "name": "Kalluk",
          "id": "000001"
        },
        {
          "scientificName": "Ursus maritimus",
          "englishName": "Polar Bear",
          "name": "Chinook",
          "id": "000002"
        }
      ],
      "name": "Polar Bear Plunge"
    }
}

attributesGroupName

Agrupa todos os atributos de uma tag sob um nome de propriedade especificado.

Padrão: não definido

Quando definido como @@ para agrupar todos os atributos de tag em um elemento chamado @@,, o driver retorna a saída da seguinte forma:

{
    exhibit: {
      "@@": {
        "@_name": "Polar Bear Plunge"
      }
      animal: [
        {
          "@@": {
            "@_id": "000001"
          },
          "scientificName": "Ursus maritimus",
          "englishName": "Polar Bear",
          "name": "Kalluk"
        },
        {
          "@@": {
            "@_id": "000002"
          },
          "scientificName": "Ursus maritimus",
          "englishName": "Polar Bear",
          "name": "Chinook"
        }
      ]
    }
}