Node.js 选项参考¶

当构造新的 Connection 对象时，您传入一个 JavaScript 对象，该对象指定连接的选项（例如您的账户标识符、您的用户名等）。以下各节介绍您可以设置的选项。要设置选项，请将选项名称指定为 JavaScript 对象中的属性名称。

连接选项
其他选项
- xmlParserConfig 选项

必需的连接选项¶

account

您的账户标识符。

region （已弃用）

指定您的账户所在区域的 ID。

备注

此选项已弃用，此处包含此选项只是为了向后兼容。如使用账户定位器作为标识符中所述，Snowflake 建议转换为将区域嵌入账户标识符中，如下所示。

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

Copy

此外，您还必须指定用于对服务器进行身份验证的选项。

身份验证选项¶

application

指定连接到 Snowflake 的客户端应用程序的名称。

authenticator

指定用于验证用户登录凭据的身份验证器。您可以将此设置为以下某个值：

值	描述
`SNOWFLAKE`	使用内部 Snowflake 身份验证器。您还必须设置 `password` 选项。
`EXTERNALBROWSER`	使用您的 Web 浏览器与 Okta、AD FS 或已为账户定义的其他兼容 SAML 2.0 的身份提供商 (IdP) 进行身份验证。
`https://<okta_account_name>.okta.com`	通过 Okta 使用原生 SSO。
`OAUTH`	使用 OAuth 进行身份验证。您还必须将 `token` 选项设置为 OAuth 令牌（见下文）。
`SNOWFLAKE_JWT`	使用密钥对身份验证。请参阅使用密钥对身份验证和密钥对轮换。
`USERNAME_PASSWORD_MFA`	使用多重身份验证 (MFA)。请参阅使用 MFA 密码。
`oauth_authorization_code`	使用 Web 浏览器和选定的身份提供商（包括将 Snowflake 作为 IdP 的情况）通过 OAuth 授权码手动进行身份验证。有关更多信息，请参阅使用 OAuth 2.0 授权码流程。
`oauth_client_credentials`	使用您选择的身份提供商，通过 OAuth 客户端凭据自动进行身份验证（将 Snowflake 作为 IdP 时，不支持客户端凭据流程）。有关更多信息，请参阅使用 OAuth 2.0 客户端凭据流程。

默认值为 SNOWFLAKE。

有关身份验证的更多信息，请参阅管理/使用联合身份验证和客户端、驱动程序和连接器。

username

Snowflake 用户或身份提供程序的登录名（例如，Okta 的登录名）。如果您将 authenticator 选项设置为 SNOWFLAKE、SNOWFLAKE_JWT 或 Okta 账户的 Okta URL 端点（例如 :code:` https:// (https://) <okta_account_name> .okta.com ），请设置此选项。如果未设置 :code:`authenticator 选项，则必须设置此值。

password

用户的密码。如果您将 authenticator 选项设置为 SNOWFLAKE 或 Okta 账户的 Okta URL 端点 <label-nodejs_native_sso>`（例如 :code: https:// (https://) <okta_account_name> .okta.com ），或者如果您未设置 :code:`authenticator 选项，请设置此选项。

token: 指定要用于身份验证的 OAuth 令牌。如果将 authenticator 选项设置为 OAUTH，请设置此选项。
privateKey: 指定用于密钥对身份验证的私钥（ PEM 格式）。有关详细信息，请参阅使用密钥对身份验证和密钥对轮换。
privateKeyPath: 指定私钥文件（例如 rsa_key.p8）的本地路径。有关详细信息，请参阅使用密钥对身份验证和密钥对轮换。
privateKeyPass: 指定用于解密私钥文件（如果文件已加密）的密码。有关详细信息，请参阅使用密钥对身份验证和密钥对轮换。
oauthClientId: 身份提供商为 Snowflake 集成提供的 client id 的值（Snowflake 安全集成元数据）。
oauthClientSecret: 身份提供商为 Snowflake 集成提供的 client secret 的值（Snowflake 安全集成元数据）。
oauthAuthorizationUrl: 向驱动程序提供授权码的身份提供商端点。当使用 Snowflake 作为身份提供商时，此值源自 server 或 account 参数。
oauthTokenRequestUrl: 向驱动程序提供访问令牌的身份提供商端点。当使用 Snowflake 作为身份提供商时，此值源自 server 或 account 参数。
oauthScope: 身份提供商授权请求中请求的范围。默认情况下，它源自角色。当需要多个作用域时，该值应为以空格分隔的多个作用域列表。
oauthRedirectUri: 用于授权码重定向的 URI（Snowflake 安全集成元数据）。默认值：http://127.0.0.1:{randomAvailablePort}/。

passcode: 指定在使用多重身份验证 (MFA) 进行登录时 Duo 提供的 passcode。有关详细信息，请参阅使用 MFA 密码。
passcodeInPassword: 指定 MFA passcode 是否嵌入登录密码中。如果是 true，则将 MFA 密码追加到 password 的末尾。默认：false。有关详细信息，请参阅使用 MFA 密码。

其他连接选项¶

accessUrl

指定用于连接到 Snowflake 的完全限定端点。accessUrl 包括完整的架构和主机，以及可选的端口号，类似于 https://myaccount.us-east-1.snowflakecomputing.cn。

备注

使用 accessUrl 选项时，不使用 account 选项中指定的值。

browserActionTimeout

指定与 SSO 身份验证相关的浏览器活动的超时（以毫秒为单位）。默认值为 120000（毫秒）。

openExternalBrowserCallback

打开浏览器窗口，进行 SSO 身份验证。默认情况下，该驱动程序使用 npm open 包。例如：

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

Copy

clientConfigFile

与 Easy Logging 功能关联的客户端配置文件的路径。

clientRequestMFAToken

设置驱动程序是否使用本地凭据存储中的 MFA 令牌进行身份验证，而不是从服务器请求新令牌。默认：false。

clientStoreTemporaryCredential

设置驱动程序是否使用本地凭据存储中的 SSO 令牌进行身份验证，而不是从服务器请求新令牌。默认：false。

clientSessionKeepAlive

默认情况下，客户端连接通常在执行最近的查询后大约 3-4 小时超时。

如果 clientSessionKeepAlive 选项设置为 true，则客户端与服务器的连接将无限期保持活动状态，即使未执行任何查询也是如此。

此选项的默认设置为 false。

如果将此选项设置为 true，请确保程序在程序完成后显式断开与服务器的连接。不要在未断开连接的情况下退出。

clientSessionKeepAliveHeartbeatFrequency

（仅当 clientSessionKeepAlive 为 true 时才适用）

设置检测信号消息之间的频率（以秒为单位的间隔）。

您可以粗略地将连接检测信号消息视为替换查询并重新启动连接的超时倒计时。换言之，如果连接在至少 4 小时处于非活动状态后超时，则检测信号会重置计时器，以便直到最近一次检测信号（或查询）后至少 4 小时才会发生超时。

默认值为 3600 秒（一小时）。值的有效范围为 900 至 3600。由于超时通常发生在至少 4 小时后，因此每 1 小时一次检测信号通常足以使连接保持活动状态。小于 3600 秒的检测信号间隔很少是必需的或有用的。

credentialCacheDir

设置启用令牌缓存功能时存储凭据缓存的目录。默认值：用户的 $HOME 目录。

database

连接后用于会话的默认数据库。

disableSamlUrlCheck

指定是否禁用 SAML 响应的验证检查。默认：false。

host

驱动程序应连接的主机地址。

keepAlive

指定是否在收到新连接请求后立即在套接字上启用保持活动功能。

默认情况下，HTTP 协议会为每个请求创建一个新的 TCP 连接。启用此参数允许驱动程序为多个请求重用连接，而不是为每个请求创建新的连接。

默认值为 true。

noProxy

指定驱动程序应绕过代理服务器直接连接的主机列表（例如 *.amazonaws.com 可绕过 Amazon S3 访问）。对于多个主机，请用竖线符号 (|) 分隔主机名。您还可以使用星号作为通配符。例如：

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

proxyHost

指定经过身份验证的代理服务器的主机名。

proxyPassword

为 proxyUser 指定的用户指定密码。

proxyPort

指定经过身份验证的代理服务器的端口。

proxyProtocol

指定用于连接到经过身份验证的代理服务器的协议。使用此属性指定 HTTP 协议： http 或 https。

proxyUser

指定用于连接到经过身份验证的代理服务器的用户名。

role

连接后用于会话的默认安全角色。

schema

连接后用于会话的默认架构。

timeout

保持连接处于活动状态且无响应的毫秒数。默认值：60000（1 分钟）。

warehouse

连接后用于会话的默认虚拟仓库。用于执行查询、加载数据等。

某些连接选项假定系统中已存在指定的数据库对象（数据库、架构、仓库或角色）。如果指定的对象不存在，则在连接期间不设置默认值。

连接后，还可以通过 USE <object> 命令设置或替换所有可选连接选项。

配置选项¶

arrayBindingThreshold

设置驱动程序在批量插入操作中使用的最大绑定数。默认值为 100000 (100K)。

cwd

当前用于 GET 和 PUt 操作的工作目录（当它与连接器目录不同时）。

representNullAsStringNull

指定 fetchAsString 方法如何返回空值。

``true``（已启用）：以字符串“NULL”的形式返回空值。
false``（已禁用）：以 ``null 的形式返回空值。

默认：``true``（已启用）

resultPrefetch

客户端用于预取大型结果集的线程数。有效值：1 至 10。

rowMode

指定如何返回包含重复列名的结果。值包括：

array：以数组形式返回结果集，包括重复的列名。
object：以对象形式返回结果集，省略重复的列名。
object_with_renamed_duplicated_columns：以对象形式返回结果集，同时为重复名称添加后缀以使其唯一。

默认值为 object。

xmlParserConfig 选项¶

从驱动程序版本 1.7.0 开始，可以使用以下 fast-xml-parser 库配置选项，在查询包含 XML 内容的列时，自定义驱动程序处理 XML 文档属性的方式。

默认情况下，Node.js 驱动程序在从查询返回 XML 数据时忽略 XML 元素属性。例如，在以下 XML 内容中， <animal> 元素包含 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>

Copy

默认情况下，当 Node.js 驱动程序返回结果集时，它会忽略 id 属性并返回以下输出。请注意，不包括属性名称和值。

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

有关如何设置这些选项的信息，请参阅解析 XML 数据。

为了帮助说明以下选项如何影响驱动程序解析 XML 数据的方式，每个选项描述都显示了它如何影响此示例。

ignoreAttributes

是否在解析过程中忽略 XML 属性。如果要使用其他解析器选项，则必须设置 ignoreAttributes: false。

默认：true

当设置为 false 时，驱动程序将返回输出，如下所示。请注意， id 属性现已包含在输出中（默认情况下，驱动程序在属性名称前加上 @_）：

{
    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

是否创建带有标签名称的属性并直接赋值。

默认：false

当设置为 true 时，驱动程序将返回输出，如下所示：

{
  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

附加到属性名称前面的字符串。

默认："@_"

当设置为 "" 以指定属性名称无前缀时，驱动程序将返回输出，如下所示：

{
    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

将标签的所有属性分组到指定的属性名称下。

默认：未设置

当设置为 @@ 以将所有标签属性分组到名为 @@, 的元素中时，驱动程序将返回输出，如下所示：

{
    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"
        }
      ]
    }
}