From 803a256f5f7716a4e3ce42ed52ac36f1874ebc44 Mon Sep 17 00:00:00 2001
From: David Szmolka <69192509+sfc-gh-dszmolka@users.noreply.github.com>
Date: Thu, 9 Jan 2025 14:16:38 +0100
Subject: [PATCH] =?UTF-8?q?docs:=20NO-SNOW=20(issue=20#1040)=20add=20a=20l?=
 =?UTF-8?q?ittle=20bit=20more=20clarification=20how=20to=20spec=E2=80=A6?=
 =?UTF-8?q?=20(#3321)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Description
Doc-only change, no code was modified.
Looks like `location` can use a bit more clarification as users
encounter an error when trying to intuitively populate this parameter.
Using working example from the linked issue.

## References
closes #1040
---
 docs/resources/external_table.md                 | 16 +++++++++++++++-
 .../snowflake_external_table/resource.tf         | 14 ++++++++++++++
 pkg/resources/external_table.go                  |  2 +-
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/docs/resources/external_table.md b/docs/resources/external_table.md
index f9cd0a5456..260806f64b 100644
--- a/docs/resources/external_table.md
+++ b/docs/resources/external_table.md
@@ -31,6 +31,20 @@ resource "snowflake_external_table" "external_table" {
     type = "text"
   }
 }
+
+# with a location pointing to an existing stage
+# name is hardcoded, please see resource documentation for other options
+resource "snowflake_external_table" "external_table_with_location" {
+  database = "db"
+  schema   = "schema"
+  name     = "external_table_with_location"
+  location = "@MYDB.MYSCHEMA.MYSTAGE"
+
+  column {
+    name = "id"
+    type = "int"
+  }
+}
 ```
 
 -> **Note** Instead of using fully_qualified_name, you can reference objects managed outside Terraform by constructing a correct ID, consult [identifiers guide](https://registry.terraform.io/providers/Snowflake-Labs/snowflake/latest/docs/guides/identifiers#new-computed-fully-qualified-name-field-in-resources).
@@ -44,7 +58,7 @@ resource "snowflake_external_table" "external_table" {
 - `column` (Block List, Min: 1) Definitions of a column to create in the external table. Minimum one required. (see [below for nested schema](#nestedblock--column))
 - `database` (String) The database in which to create the external table.
 - `file_format` (String) Specifies the file format for the external table.
-- `location` (String) Specifies a location for the external table.
+- `location` (String) Specifies a location for the external table, using its FQDN. You can hardcode it (`"@MYDB.MYSCHEMA.MYSTAGE"`), or populate dynamically (`"@${snowflake_stage.mystage.fully_qualified_name}"`)
 - `name` (String) Specifies the identifier for the external table; must be unique for the database and schema in which the externalTable is created.
 - `schema` (String) The schema in which to create the external table.
 
diff --git a/examples/resources/snowflake_external_table/resource.tf b/examples/resources/snowflake_external_table/resource.tf
index 5f355a14db..3752c04dd8 100644
--- a/examples/resources/snowflake_external_table/resource.tf
+++ b/examples/resources/snowflake_external_table/resource.tf
@@ -15,3 +15,17 @@ resource "snowflake_external_table" "external_table" {
     type = "text"
   }
 }
+
+# with a location pointing to an existing stage
+# name is hardcoded, please see resource documentation for other options
+resource "snowflake_external_table" "external_table_with_location" {
+  database = "db"
+  schema   = "schema"
+  name     = "external_table_with_location"
+  location = "@MYDB.MYSCHEMA.MYSTAGE"
+
+  column {
+    name = "id"
+    type = "int"
+  }
+}
\ No newline at end of file
diff --git a/pkg/resources/external_table.go b/pkg/resources/external_table.go
index bd03b75bf6..9cdb256359 100644
--- a/pkg/resources/external_table.go
+++ b/pkg/resources/external_table.go
@@ -76,7 +76,7 @@ var externalTableSchema = map[string]*schema.Schema{
 		Type:        schema.TypeString,
 		Required:    true,
 		ForceNew:    true,
-		Description: "Specifies a location for the external table.",
+		Description: "Specifies a location for the external table, using its FQDN. You can hardcode it (`\"@MYDB.MYSCHEMA.MYSTAGE\"`), or populate dynamically (`\"@${snowflake_stage.mystage.fully_qualified_name}\"`)",
 	},
 	"file_format": {
 		Type:        schema.TypeString,