feat(kql_queryset): onboard resource and add definition (#217)

# 📥 Pull Request

close #130
close #131

## ❓ What are you trying to address

- Onboard new resource: `fabric_kql_queryset`
- Add definition support to the `fabric_kql_queryset` Data-Source

.changes/unreleased/added-20250125-145244.yaml

@@ -0,0 +1,5 @@
+kind: added
+body: "New Resource: `fabric_kql_queryset`"
+time: 2025-01-25T14:52:44.1990994+01:00
+custom:
+  Issue: "130"

.changes/unreleased/added-20250125-145341.yaml

@@ -0,0 +1,5 @@
+kind: added
+body: Definition support in the `fabric_kql_queryset` Data-Source
+time: 2025-01-25T14:53:41.6482592+01:00
+custom:
+  Issue: "131"

.github/workflows/test.yml

@@ -324,7 +324,7 @@ jobs:
           - cli: terraform
             version: "1.9"
           - cli: tofu
-            version: "1.8" 
+            version: "1.8"
           - cli: tofu
             version: "1.10"
     steps:

docs/data-sources/kql_queryset.md

@@ -6,6 +6,7 @@ description: |-
   Get a Fabric KQL Queryset.
   Use this data source to fetch a KQL Queryset https://learn.microsoft.com/fabric/real-time-intelligence/kusto-query-set.
   -> This item supports Service Principal authentication.
+  ~> This data-source is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_kql_queryset (Data Source)
@@ -16,17 +17,40 @@ Use this data source to fetch a [KQL Queryset](https://learn.microsoft.com/fabri
 
 -> This item supports Service Principal authentication.
 
+~> This data-source is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform
+# Get item details by name
+data "fabric_kql_queryset" "example_by_name" {
+  display_name = "example"
+  workspace_id = "00000000-0000-0000-0000-000000000000"
+}
+
+# Get item details by id
 data "fabric_kql_queryset" "example_by_id" {
   id           = "11111111-1111-1111-1111-111111111111"
   workspace_id = "00000000-0000-0000-0000-000000000000"
 }
 
-data "fabric_kql_queryset" "example_by_name" {
-  display_name = "example"
-  workspace_id = "00000000-0000-0000-0000-000000000000"
+# Get item details with definition
+# Examples uses `id` but `display_name` can be used as well
+data "fabric_kql_queryset" "example_definition" {
+  id                = "11111111-1111-1111-1111-111111111111"
+  workspace_id      = "00000000-0000-0000-0000-000000000000"
+  format            = "Default"
+  output_definition = true
+}
+
+# Access the content of the definition with JSONPath expression
+output "example_definition_content_jsonpath" {
+  value = provider::fabric::content_decode(data.fabric_kql_queryset.example_definition.definition["RealTimeQueryset.json"].content, ".payload.tabs[0]")
+}
+
+# Access the content of the definition as JSON object
+output "example_definition_content_object" {
+  value = provider::fabric::content_decode(data.fabric_kql_queryset.example_definition.definition["RealTimeQueryset.json"].content).payload.tabs[0]
 }
 
 # This is an invalid data source
@@ -48,11 +72,17 @@ data "fabric_kql_queryset" "example_by_name" {
 ### Optional
 
 - `display_name` (String) The KQL Queryset display name.
+- `format` (String) The KQL Queryset format. Possible values: `Default`
 - `id` (String) The KQL Queryset ID.
+- `output_definition` (Boolean) Output definition parts as gzip base64 content? Default: `false`
+
+!> Your terraform state file may grow a lot if you output definition content. Only use it when you must use data from the definition.
+
 - `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))
 
 ### Read-Only
 
+- `definition` (Attributes Map) Definition parts. Possible path keys: **Default** format: `RealTimeQueryset.json` (see [below for nested schema](#nestedatt--definition))
 - `description` (String) The KQL Queryset description.
 
 <a id="nestedatt--timeouts"></a>
@@ -62,3 +92,12 @@ data "fabric_kql_queryset" "example_by_name" {
 Optional:
 
 - `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
+
+<a id="nestedatt--definition"></a>
+
+### Nested Schema for `definition`
+
+Read-Only:
+
+- `content` (String) Gzip base64 content of definition part.
+Use [`provider::fabric::content_decode`](../functions/content_decode.md) function to decode content.

docs/resources/kql_queryset.md

@@ -0,0 +1,119 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "fabric_kql_queryset Resource - terraform-provider-fabric"
+subcategory: ""
+description: |-
+  Manage a Fabric KQL Queryset.
+  Use this resource to manage KQL Queryset https://learn.microsoft.com/fabric/real-time-intelligence/kusto-query-set.
+  -> This item supports Service Principal authentication.
+  ~> This resource is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
+---
+
+# fabric_kql_queryset (Resource)
+
+Manage a Fabric KQL Queryset.
+
+Use this resource to manage [KQL Queryset](https://learn.microsoft.com/fabric/real-time-intelligence/kusto-query-set).
+
+-> This item supports Service Principal authentication.
+
+~> This resource is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
+## Example Usage
+
+```terraform
+# Example 1 - Item without definition
+resource "fabric_kql_queryset" "example" {
+  display_name = "example"
+  workspace_id = "00000000-0000-0000-0000-000000000000"
+}
+
+# Example 2 - Item with definition bootstrapping only
+resource "fabric_kql_queryset" "example_definition_bootstrap" {
+  display_name              = "example"
+  description               = "example with definition bootstrapping"
+  workspace_id              = "00000000-0000-0000-0000-000000000000"
+  definition_update_enabled = false
+  format                    = "Default"
+  definition = {
+    "RealTimeQueryset.json" = {
+      source = "${local.path}/RealTimeQueryset.json"
+    }
+  }
+}
+
+# Example 3 - Item with definition update when source or tokens changed
+resource "fabric_kql_queryset" "example_definition_update" {
+  display_name = "example"
+  description  = "example with definition update when source or tokens changed"
+  workspace_id = "00000000-0000-0000-0000-000000000000"
+  format       = "Default"
+  definition = {
+    "RealTimeQueryset.json" = {
+      source = "${local.path}/RealTimeQueryset.json.tmpl"
+      tokens = {
+        "MyValue1" = "my value 1"
+        "MyValue2" = "my value 2"
+      }
+    }
+  }
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `display_name` (String) The KQL Queryset display name.
+- `workspace_id` (String) The Workspace ID.
+
+### Optional
+
+- `definition` (Attributes Map) Definition parts. Read more about [KQL Queryset definition part paths](https://learn.microsoft.com/rest/api/fabric/articles/item-management/definitions/kql-queryset-definition). Accepted path keys: **Default** format: `RealTimeQueryset.json` (see [below for nested schema](#nestedatt--definition))
+- `definition_update_enabled` (Boolean) Update definition on change of source content. Default: `true`.
+- `description` (String) The KQL Queryset description.
+- `format` (String) The KQL Queryset format. Possible values: `Default`
+- `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))
+
+### Read-Only
+
+- `id` (String) The KQL Queryset ID.
+
+<a id="nestedatt--definition"></a>
+
+### Nested Schema for `definition`
+
+Required:
+
+- `source` (String) Path to the file with source of the definition part.
+
+The source content may include placeholders for token substitution. Use the dot with the token name `{{ .TokenName }}`.
+
+Optional:
+
+- `tokens` (Map of String) A map of key/value pairs of tokens substitutes in the source.
+
+Read-Only:
+
+- `source_content_sha256` (String) SHA256 of source's content of definition part.
+
+<a id="nestedatt--timeouts"></a>
+
+### Nested Schema for `timeouts`
+
+Optional:
+
+- `create` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
+- `delete` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Setting a timeout for a Delete operation is only applicable if changes are saved into state before the destroy operation occurs.
+- `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Read operations occur during any refresh or planning operation when refresh is enabled.
+- `update` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# terraform import fabric_kql_queryset.example "<WorkspaceID>/<KQLQuerysetID>"
+terraform import fabric_kql_queryset.example "00000000-0000-0000-0000-000000000000/11111111-1111-1111-1111-111111111111"
+```

examples/data-sources/fabric_kql_queryset/data-source.tf

@@ -1,11 +1,32 @@
+# Get item details by name
+data "fabric_kql_queryset" "example_by_name" {
+  display_name = "example"
+  workspace_id = "00000000-0000-0000-0000-000000000000"
+}
+
+# Get item details by id
 data "fabric_kql_queryset" "example_by_id" {
   id           = "11111111-1111-1111-1111-111111111111"
   workspace_id = "00000000-0000-0000-0000-000000000000"
 }
 
-data "fabric_kql_queryset" "example_by_name" {
-  display_name = "example"
-  workspace_id = "00000000-0000-0000-0000-000000000000"
+# Get item details with definition
+# Examples uses `id` but `display_name` can be used as well
+data "fabric_kql_queryset" "example_definition" {
+  id                = "11111111-1111-1111-1111-111111111111"
+  workspace_id      = "00000000-0000-0000-0000-000000000000"
+  format            = "Default"
+  output_definition = true
+}
+
+# Access the content of the definition with JSONPath expression
+output "example_definition_content_jsonpath" {
+  value = provider::fabric::content_decode(data.fabric_kql_queryset.example_definition.definition["RealTimeQueryset.json"].content, ".payload.tabs[0]")
+}
+
+# Access the content of the definition as JSON object
+output "example_definition_content_object" {
+  value = provider::fabric::content_decode(data.fabric_kql_queryset.example_definition.definition["RealTimeQueryset.json"].content).payload.tabs[0]
 }
 
 # This is an invalid data source

examples/resources/fabric_kql_queryset/import.sh

@@ -0,0 +1,2 @@
+# terraform import fabric_kql_queryset.example "<WorkspaceID>/<KQLQuerysetID>"
+terraform import fabric_kql_queryset.example "00000000-0000-0000-0000-000000000000/11111111-1111-1111-1111-111111111111"

examples/resources/fabric_kql_queryset/outputs.tf

@@ -0,0 +1,3 @@
+output "example" {
+  value = resource.fabric_kql_queryset.example
+}

examples/resources/fabric_kql_queryset/providers.tf

@@ -0,0 +1,11 @@
+terraform {
+  required_version = ">= 1.8, < 2.0"
+  required_providers {
+    fabric = {
+      source  = "microsoft/fabric"
+      version = "0.0.0" # Check for the latest version on the Terraform Registry
+    }
+  }
+}
+
+provider "fabric" {}

examples/resources/fabric_kql_queryset/resource.tf

@@ -0,0 +1,36 @@
+# Example 1 - Item without definition
+resource "fabric_kql_queryset" "example" {
+  display_name = "example"
+  workspace_id = "00000000-0000-0000-0000-000000000000"
+}
+
+# Example 2 - Item with definition bootstrapping only
+resource "fabric_kql_queryset" "example_definition_bootstrap" {
+  display_name              = "example"
+  description               = "example with definition bootstrapping"
+  workspace_id              = "00000000-0000-0000-0000-000000000000"
+  definition_update_enabled = false
+  format                    = "Default"
+  definition = {
+    "RealTimeQueryset.json" = {
+      source = "${local.path}/RealTimeQueryset.json"
+    }
+  }
+}
+
+# Example 3 - Item with definition update when source or tokens changed
+resource "fabric_kql_queryset" "example_definition_update" {
+  display_name = "example"
+  description  = "example with definition update when source or tokens changed"
+  workspace_id = "00000000-0000-0000-0000-000000000000"
+  format       = "Default"
+  definition = {
+    "RealTimeQueryset.json" = {
+      source = "${local.path}/RealTimeQueryset.json.tmpl"
+      tokens = {
+        "MyValue1" = "my value 1"
+        "MyValue2" = "my value 2"
+      }
+    }
+  }
+}

internal/provider/provider.go

@@ -368,6 +368,7 @@ func (p *FabricProvider) Resources(ctx context.Context) []func() resource.Resour
 		func() resource.Resource { return eventhouse.NewResourceEventhouse(ctx) },
 		eventstream.NewResourceEventstream,
 		kqldatabase.NewResourceKQLDatabase,
+		kqlqueryset.NewResourceKQLQueryset,
 		func() resource.Resource { return lakehouse.NewResourceLakehouse(ctx) },
 		mlexperiment.NewResourceMLExperiment,
 		mlmodel.NewResourceMLModel,

internal/services/kqlqueryset/base.go

@@ -7,14 +7,26 @@ import (
 	fabcore "github.com/microsoft/fabric-sdk-go/fabric/core"
 
 	"github.com/microsoft/terraform-provider-fabric/internal/common"
+	"github.com/microsoft/terraform-provider-fabric/internal/pkg/fabricitem"
 )
 
 const (
-	ItemName           = "KQL Queryset"
-	ItemTFName         = "kql_queryset"
-	ItemsName          = "KQL Querysets"
-	ItemsTFName        = "kql_querysets"
-	ItemType           = fabcore.ItemTypeKQLQueryset
-	ItemDocsSPNSupport = common.DocsSPNSupported
-	ItemDocsURL        = "https://learn.microsoft.com/fabric/real-time-intelligence/kusto-query-set"
+	ItemName                  = "KQL Queryset"
+	ItemTFName                = "kql_queryset"
+	ItemsName                 = "KQL Querysets"
+	ItemsTFName               = "kql_querysets"
+	ItemType                  = fabcore.ItemTypeKQLQueryset
+	ItemDocsSPNSupport        = common.DocsSPNSupported
+	ItemDocsURL               = "https://learn.microsoft.com/fabric/real-time-intelligence/kusto-query-set"
+	ItemDefinitionEmpty       = `{}`
+	ItemDefinitionPathDocsURL = "https://learn.microsoft.com/rest/api/fabric/articles/item-management/definitions/kql-queryset-definition"
+	ItemPreview               = true
 )
+
+var itemDefinitionFormats = []fabricitem.DefinitionFormat{ //nolint:gochecknoglobals
+	{
+		Type:  fabricitem.DefinitionFormatDefault,
+		API:   "",
+		Paths: []string{"RealTimeQueryset.json"},
+	},
+}

internal/services/kqlqueryset/data_kql_queryset.go

@@ -10,15 +10,17 @@ import (
 )
 
 func NewDataSourceKQLQueryset() datasource.DataSource {
-	config := fabricitem.DataSourceFabricItem{
+	config := fabricitem.DataSourceFabricItemDefinition{
 		Type:   ItemType,
 		Name:   ItemName,
 		TFName: ItemTFName,
 		MarkdownDescription: "Get a Fabric " + ItemName + ".\n\n" +
 			"Use this data source to fetch a [" + ItemName + "](" + ItemDocsURL + ").\n\n" +
 			ItemDocsSPNSupport,
 		IsDisplayNameUnique: true,
+		DefinitionFormats:   itemDefinitionFormats,
+		IsPreview:           ItemPreview,
 	}
 
-	return fabricitem.NewDataSourceFabricItem(config)
+	return fabricitem.NewDataSourceFabricItemDefinition(config)
 }