feat: Add tags data source (#3211)

<!-- Feel free to delete comments as you fill this in -->
- add `tags` data source
- add missing examples for `streams` data source
<!-- summary of changes -->

## Test Plan
<!-- detail ways in which this PR has been tested or needs to be tested
-->
* [x] acceptance tests
<!-- add more below if you think they are relevant -->
* [ ] …

## References
<!-- issues documentation links, etc  -->
https://docs.snowflake.com/en/sql-reference/sql/show-tags

#1372

MIGRATION_GUIDE.md

@@ -9,6 +9,13 @@ across different versions.
 
 ## v0.98.0 ➞ v0.99.0
 
+### *(new feature)* snowflake_tags datasource
+Added a new datasource enabling querying and filtering tags. Notes:
+- all results are stored in `tags` field.
+- `like` field enables tags filtering by name.
+- `in` field enables tags filtering by `account`, `database`, `schema`, `application` and `application_package`.
+- `SHOW TAGS` output is enclosed in `show_output` field inside `tags`.
+
 ### snowflake_tag_masking_policy_association deprecation
 `snowflake_tag_masking_policy_association` is now deprecated in favor of `snowflake_tag` with a new `masking_policy` field. It will be removed with the v1 release. Please adjust your configuration files.
 

docs/data-sources/streams.md

@@ -14,9 +14,120 @@ Datasource used to get details of filtered streams. Filtering is aligned with th
 ## Example Usage
 
 ```terraform
-data "snowflake_streams" "current" {
-  database = "MYDB"
-  schema   = "MYSCHEMA"
+# Simple usage
+data "snowflake_streams" "simple" {
+}
+
+output "simple_output" {
+  value = data.snowflake_streams.simple.streams
+}
+
+# Filtering (like)
+data "snowflake_streams" "like" {
+  like = "stream-name"
+}
+
+output "like_output" {
+  value = data.snowflake_streams.like.streams
+}
+
+# Filtering by prefix (like)
+data "snowflake_streams" "like_prefix" {
+  like = "prefix%"
+}
+
+output "like_prefix_output" {
+  value = data.snowflake_streams.like_prefix.streams
+}
+
+# Filtering (limit)
+data "snowflake_streams" "limit" {
+  limit {
+    rows = 10
+    from = "prefix-"
+  }
+}
+
+output "limit_output" {
+  value = data.snowflake_streams.limit.streams
+}
+
+# Filtering (in)
+data "snowflake_streams" "in_account" {
+  in {
+    account = true
+  }
+}
+
+data "snowflake_streams" "in_database" {
+  in {
+    database = "<database_name>"
+  }
+}
+
+data "snowflake_streams" "in_schema" {
+  in {
+    schema = "<database_name>.<schema_name>"
+  }
+}
+
+data "snowflake_streams" "in_application" {
+  in {
+    application = "<application_name>"
+  }
+}
+
+data "snowflake_streams" "in_application_package" {
+  in {
+    application_package = "<application_package_name>"
+  }
+}
+
+output "in_output" {
+  value = {
+    "account" : data.snowflake_streams.in_account.streams,
+    "database" : data.snowflake_streams.in_database.streams,
+    "schema" : data.snowflake_streams.in_schema.streams,
+    "application" : data.snowflake_streams.in_application.streams,
+    "application_package" : data.snowflake_streams.in_application_package.streams,
+  }
+}
+
+output "in_output" {
+  value = data.snowflake_streams.in.streams
+}
+
+# Without additional data (to limit the number of calls make for every found stream)
+data "snowflake_streams" "only_show" {
+  # with_describe is turned on by default and it calls DESCRIBE STREAM for every stream found and attaches its output to streams.*.describe_output field
+  with_describe = false
+}
+
+output "only_show_output" {
+  value = data.snowflake_streams.only_show.streams
+}
+
+# Ensure the number of streams is equal to at least one element (with the use of postcondition)
+data "snowflake_streams" "assert_with_postcondition" {
+  like = "stream-name%"
+  lifecycle {
+    postcondition {
+      condition     = length(self.streams) > 0
+      error_message = "there should be at least one stream"
+    }
+  }
+}
+
+# Ensure the number of streams is equal to at exactly one element (with the use of check block)
+check "stream_check" {
+  data "snowflake_streams" "assert_with_check_block" {
+    like = "stream-name"
+  }
+
+  assert {
+    condition     = length(data.snowflake_streams.assert_with_check_block.streams) == 1
+    error_message = "streams filtered by '${data.snowflake_streams.assert_with_check_block.like}' returned ${length(data.snowflake_streams.assert_with_check_block.streams)} streams where one was expected"
+  }
 }
 ```
 

docs/data-sources/tags.md

@@ -0,0 +1,156 @@
+---
+page_title: "snowflake_tags Data Source - terraform-provider-snowflake"
+subcategory: ""
+description: |-
+  Datasource used to get details of filtered tags. Filtering is aligned with the current possibilities for SHOW TAGS https://docs.snowflake.com/en/sql-reference/sql/show-tags query. The results of SHOW are encapsulated in one output collection tags.
+---
+
+!> **V1 release candidate** This data source is a release candidate for the V1. We do not expect significant changes in it before the V1. We will welcome any feedback and adjust the data source if needed. Any errors reported will be resolved with a higher priority. We encourage checking this data source out before the V1 release. Please follow the [migration guide](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/MIGRATION_GUIDE.md#v0980--v0990) to use it.
+
+# snowflake_tags (Data Source)
+
+Datasource used to get details of filtered tags. Filtering is aligned with the current possibilities for [SHOW TAGS](https://docs.snowflake.com/en/sql-reference/sql/show-tags) query. The results of SHOW are encapsulated in one output collection `tags`.
+
+## Example Usage
+
+```terraform
+# Simple usage
+data "snowflake_tags" "simple" {
+}
+
+output "simple_output" {
+  value = data.snowflake_tags.simple.tags
+}
+
+# Filtering (like)
+data "snowflake_tags" "like" {
+  like = "tag-name"
+}
+
+output "like_output" {
+  value = data.snowflake_tags.like.tags
+}
+
+# Filtering by prefix (like)
+data "snowflake_tags" "like_prefix" {
+  like = "prefix%"
+}
+
+output "like_prefix_output" {
+  value = data.snowflake_tags.like_prefix.tags
+}
+
+# Filtering (in)
+data "snowflake_tags" "in_account" {
+  in {
+    account = true
+  }
+}
+
+data "snowflake_tags" "in_database" {
+  in {
+    database = "<database_name>"
+  }
+}
+
+data "snowflake_tags" "in_schema" {
+  in {
+    schema = "<database_name>.<schema_name>"
+  }
+}
+
+data "snowflake_tags" "in_application" {
+  in {
+    application = "<application_name>"
+  }
+}
+
+data "snowflake_tags" "in_application_package" {
+  in {
+    application_package = "<application_package_name>"
+  }
+}
+
+output "in_output" {
+  value = {
+    "account" : data.snowflake_tags.in_account.tags,
+    "database" : data.snowflake_tags.in_database.tags,
+    "schema" : data.snowflake_tags.in_schema.tags,
+    "application" : data.snowflake_tags.in_application.tags,
+    "application_package" : data.snowflake_tags.in_application_package.tags,
+  }
+}
+
+output "in_output" {
+  value = data.snowflake_tags.in.tags
+}
+
+# Ensure the number of tags is equal to at least one element (with the use of postcondition)
+data "snowflake_tags" "assert_with_postcondition" {
+  like = "tag-name%"
+  lifecycle {
+    postcondition {
+      condition     = length(self.tags) > 0
+      error_message = "there should be at least one tag"
+    }
+  }
+}
+
+# Ensure the number of tags is equal to at exactly one element (with the use of check block)
+check "tag_check" {
+  data "snowflake_tags" "assert_with_check_block" {
+    like = "tag-name"
+  }
+
+  assert {
+    condition     = length(data.snowflake_tags.assert_with_check_block.tags) == 1
+    error_message = "tags filtered by '${data.snowflake_tags.assert_with_check_block.like}' returned ${length(data.snowflake_tags.assert_with_check_block.tags)} tags where one was expected"
+  }
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- `in` (Block List, Max: 1) IN clause to filter the list of objects (see [below for nested schema](#nestedblock--in))
+- `like` (String) Filters the output with **case-insensitive** pattern, with support for SQL wildcard characters (`%` and `_`).
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `tags` (List of Object) Holds the aggregated output of all tags details queries. (see [below for nested schema](#nestedatt--tags))
+
+<a id="nestedblock--in"></a>
+### Nested Schema for `in`
+
+Optional:
+
+- `account` (Boolean) Returns records for the entire account.
+- `application` (String) Returns records for the specified application.
+- `application_package` (String) Returns records for the specified application package.
+- `database` (String) Returns records for the current database in use or for a specified database.
+- `schema` (String) Returns records for the current schema in use or a specified schema. Use fully qualified name.
+
+
+<a id="nestedatt--tags"></a>
+### Nested Schema for `tags`
+
+Read-Only:
+
+- `show_output` (List of Object) (see [below for nested schema](#nestedobjatt--tags--show_output))
+
+<a id="nestedobjatt--tags--show_output"></a>
+### Nested Schema for `tags.show_output`
+
+Read-Only:
+
+- `allowed_values` (Set of String)
+- `comment` (String)
+- `created_on` (String)
+- `database_name` (String)
+- `name` (String)
+- `owner` (String)
+- `owner_role_type` (String)
+- `schema_name` (String)