Categories:

System functions (System Information)

SYSTEM$VERIFY_EXTERNAL_VOLUME¶

Verifies the configuration for a specified external volume.

For external volumes with write access, Snowflake attempts the following additional operations to verify the configuration:

  • Write a test file.

  • Read the test file.

  • List the files in the storage location.

  • Delete the test file.

See also:

Storage for Apache Icebergâ„¢ tables , Configure an external volume , CREATE EXTERNAL VOLUME

Syntax¶

SYSTEM$VERIFY_EXTERNAL_VOLUME('<external_volume_name>')
Copy

Arguments¶

external_volume_name

Name of the external volume to verify. If the identifier contains spaces or special characters, the entire string must be enclosed in double quotes. Identifiers enclosed in double quotes are also case sensitive.

Returns¶

The function returns a JSON object with the properties described below:

Property

Description

success

The status of the verification test. Returns TRUE if all actions finished; returns FALSE if any action didn’t finish as expected.

storageLocationSelectionResult

The result of selecting an active storage location for the external volume. Returns TRUE if Snowflake can successfully select an active location; otherwise, returns FALSE.

storageLocationName

The name of the active storage location.

servicePrincipalProperties

The properties of the Snowflake service principal for the cloud provider of the active storage location.

location

The BASE_URL of the active storage location.

storageAccount

For Azure, the storage account of the active storage location.

region

The region of the active storage location.

writeResult

The result of writing a test file to the active storage location. Skipped for read-only external volumes.

readResult

The result of reading a test file from the active storage location. Skipped for read-only external volumes.

listResult

The result of listing the contents of the active storage location. Skipped for read-only external volumes.

deleteResult

The result of deleting a test file written to the active storage location. Skipped for read-only external volumes.

awsRoleArnValidationResult

For Amazon S3, returns the result of validating the Amazon Resource Name (ARN) for the IAM role used by the external volume.

azureGetUserDelegationKeyResult

For Azure, returns the result of getting a user delegation key.

Result values¶

Return properties that indicate a result can have the following values:

Result value

Description

PASSED

The operation succeeded.

SKIPPED

The operation isn’t applicable for the specified external volume. For example, the read, write, list, and delete operations are skipped for read-only external volumes.

<error_message>

A detailed error message.

Example output¶

{
  "success": true,
  "storageLocationSelectionResult": "PASSED",
  "storageLocationName": "my-azure-westus-1",
  "servicePrincipalProperties": "AZURE_MULTI_TENANT_APP_NAME: powerful-azure-ad-auth-test-snowflake-app_...; AZURE_CONSENT_URL: https://login.microsoftonline.com...",
  "location": "azure://myStorageAccount.blob.core.windows.net/myStorageLocation/",
  "storageAccount": "myStorageAccount",
  "region": "westus",
  "writeResult": "PASSED",
  "readResult": "PASSED",
  "listResult": "PASSED",
  "deleteResult": "PASSED",
  "awsRoleArnValidationResult": "SKIPPED",
  "azureGetUserDelegationKeyResult": "PASSED"
}
Copy

Access control requirements¶

A role used to execute this SQL command must have the following privileges at a minimum:

Privilege

Object

Notes

OWNERSHIP

External volume

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

Examples¶

Verify an external volume named my_s3_external_volume:

SELECT SYSTEM$VERIFY_EXTERNAL_VOLUME('my_s3_external_volume');
Copy
Language: English