📊 Microsoft Fabric KQL Queryset Terraform Module

Manages a Fabric KQL Queryset item (fabric_kql_queryset) — a saved collection of KQL queries typically pointed at one or more KQL databases/Eventhouses for interactive exploration — targeting the microsoft/fabric provider ~> 1.12.0.

• Creates and manages exactly one Fabric KQL Queryset (fabric_kql_queryset.this).
• Optionally carries a single Default-format definition part (RealTimeQueryset.json) — the saved-query JSON payload — modeled as a path-keyed Attributes Map, per this module suite's definition-carrying item pattern.
• Defaults to workspace-root placement (folder_id = null) and no predefined content (definition = {}).
• Optionally assigns existing fabric_tag GUIDs via tags — confirmed present on this resource's live schema.
• Emits the Queryset id for cross-referencing by sharing automation or downstream orchestration outside Terraform's own reference graph.

💡 Why it matters: a KQL Queryset is a low-blast-radius item (saved queries, not data), but its definition payload can still embed a specific database/Eventhouse binding and, via parameters, inject values at plan time — modeling it as a strictly-typed Attributes Map catches a malformed part or an illegal processing_mode at terraform validate, not as a 400 from the Fabric API mid-apply.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

flowchart TB
 Workspace["terraform-fabric-workspace"]:::keystone
 Folder["terraform-fabric-folder"]:::sibling
 Tag["terraform-fabric-tag"]:::sibling
 KqlQueryset["terraform-fabric-kql-queryset\n(this module)"]:::thisModule
 Downstream["Sharing / Real-Time Hub automation\n(outside Terraform)"]:::sibling

 Workspace -->|"workspace_id"| KqlQueryset
 Folder -->|"folder_id (optional)"| KqlQueryset
 Tag -->|"tags (optional set of GUIDs)"| KqlQueryset
 KqlQueryset -->|"id"| Downstream

 classDef thisModule fill:#0F6CBD,color:#FFFFFF,stroke:#0F6CBD
 classDef keystone fill:#143551,color:#FFFFFF,stroke:#143551
 classDef sibling fill:#E8EAED,color:#1A1A1A,stroke:#B0B7BF

This module never creates the workspace, folder, or tags it references — those are sibling modules whose id outputs feed this module's workspace_id / folder_id / tags inputs. The live v1.12.0 schema does not expose a separate top-level reference to a target KQL database/Eventhouse; any such binding is expressed entirely inside the definition JSON payload (see 🧠 Architecture Notes) — this is a confirmed schema fact, not an oversight, and there is deliberately no terraform-fabric-kql-database edge in the diagram above.

flowchart TB
 subgraph Inputs["Inputs"]
 DisplayName["display_name"]
 Description["description"]
 WorkspaceId["workspace_id"]
 FolderId["folder_id"]
 Format["format"]
 Definition["definition (Attributes Map)"]
 DefUpdate["definition_update_enabled"]
 Tags["tags"]
 Timeouts["timeouts"]
 end

 Keystone["fabric_kql_queryset.this"]:::thisModule

 DisplayName --> Keystone
 Description --> Keystone
 WorkspaceId --> Keystone
 FolderId --> Keystone
 Format --> Keystone
 Definition -->|"assigned with ="| Keystone
 DefUpdate --> Keystone
 Tags --> Keystone
 Timeouts -->|"assigned with ="| Keystone

 Keystone -->|"id"| OutId["id output"]
 Keystone -->|"display_name"| OutName["display_name output"]

 classDef thisModule fill:#0F6CBD,color:#FFFFFF,stroke:#0F6CBD

Resource inventory: 1 resource — fabric_kql_queryset.this (single instance, the sole keystone; this is a standalone module with no owned children).

Schema notes that bite (confirmed against the live v1.12.0 schema via the terraform-registry MCP, the live provider schema, provider_doc_id 12766478):

• definition is a Terraform Plugin Framework Attributes Map, not a Block — assigned directly with = in main.tf (definition = { for path, part in var.definition: path => {...} }), never wrapped in a dynamic "definition" block. timeouts is likewise a single nested Attributes object, also assigned with =. Both facts are confirmed directly from the tfplugindocs-generated schema text, which labels each (Attributes Map) / (Attributes) respectively — a dynamic block on either fails terraform validate against this resource.
• The schema currently accepts exactly one definition-part key, "RealTimeQueryset.json", paired with format = "Default" — the only documented format value. This is a de facto single-entry map today, but the module still models definition as a generic map(object(...)) (not a single nested object) to mirror the provider's own Attributes Map shape and to avoid hard-coding an assumption about future format/part additions.
• processing_mode's provider-native default is "GoTemplate"; this module overrides its own default to "None" per this module suite's secure-by-default convention, so no implicit token substitution happens unless the caller explicitly opts in.
• No configuration argument exists on this resource (unlike fabric_lakehouse/fabric_sql_database) — do not add one; there is nothing analogous to lakehouse schema-enablement or SQL Database creation mode here.
• tags is a genuine Set of String on the live schema (tag GUIDs) — confirmed present, wired straight through.

(sourced from this module's SCOPE.md — do not let this drift independently)

• Fabric workspace role: Admin, Member, or Contributor — Microsoft Learn's "Roles in workspaces in Microsoft Fabric" table explicitly lists KQL Querysets under "Write or delete... KQL Querysets...": granted to Admin/Member/Contributor, not Viewer. This matches the Discovery-phase baseline (Workspace Contributor) and is confirmed, not inferred.
• Entra: the calling Service Principal (or Managed Identity) must be included in the tenant's allowed security group under the "Service principals can call Fabric public APIs" Developer setting — the same universal prerequisite every other module in this library carries.
• No KQL-Queryset-specific Entra app-role or additional API permission beyond the standard Fabric workspace role above was found in the provider docs or Microsoft Learn.

• The target capacity backing the workspace must be in Active state (not paused) for KQL Queryset create/read operations — Fabric write operations against a paused capacity fail or return stale state.
• The tenant's "Service principals can call Fabric public APIs" Developer setting must already be enabled in the Fabric Admin Portal before any SPN/MSI auth call succeeds at all, independent of this module's correctness.
• A KQL Queryset is generally created against an existing KQL database/Eventhouse with editing permissions and data (Microsoft Learn, "Create a KQL queryset" prerequisites) — that database is out of this module's scope; the binding is expressed inside definition's JSON payload, not a Terraform argument.
• No Fabric trial/license prerequisite beyond an active (non-trial, per the provider's own "Known limitations" — Fabric trial capacity is unsupported by this provider) capacity being available.

terraform-fabric-kql-queryset/
├── providers.tf # required_providers (fabric ~> 1.12.0), no provider {} block
├── variables.tf # display_name, workspace_id, description, folder_id, format, definition,
│ # definition_update_enabled, tags, timeouts
├── main.tf # fabric_kql_queryset.this — the sole keystone
├── outputs.tf # id, display_name
├── README.md # this file
├── SCOPE.md # lightweight cross-module contract (standalone)
└── examples/
 ├── basic/ # empty Queryset, no definition, workspace-root placement
 └── complete/ # Queryset with a token-substituted definition, folder_id, tags

# Caller's root module configures the provider — never this module.
provider "fabric" {
  tenant_id     = var.tenant_id
  client_id     = var.client_id
  client_secret = var.client_secret # sourced from Key Vault / pipeline secret, never literal
}

module "kql_queryset" {
  source = "git::https://github.com/microsoftexpert/terraform-fabric-kql-queryset.git?ref=v1.0.0"

  display_name = "kqs-telemetry-ops-prod"
  description  = "Curated telemetry queryset — prod. Owner: Observability."
  workspace_id = module.workspace.id
}

Consumes

Emits

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-sandbox-explore-dev"
  workspace_id = module.workspace.id
}

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-claims-triage-prod"
  description  = "Triage queries against claims Eventhouse. Owner: Claims Analytics."
  workspace_id = module.workspace.id
}

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-telemetry-ops-prod"
  workspace_id = module.workspace.id
  folder_id    = module.folder_analysis.id
}

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-telemetry-ops-prod"
  workspace_id = module.workspace.id
  tags         = [fabric_tag.this["observability"].id]
}

module "kql_queryset" {
  source = "../../"

  display_name              = "kqs-telemetry-ops-dev"
  workspace_id              = module.workspace.id
  definition_update_enabled = false
  format                    = "Default"

  definition = {
    "RealTimeQueryset.json" = {
      source = "${path.module}/files/RealTimeQueryset.json"
    }
  }
}

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-telemetry-ops-prod"
  workspace_id = module.workspace.id
  format       = "Default"

  definition = {
    "RealTimeQueryset.json" = {
      source = "${path.module}/files/RealTimeQueryset.json"
    }
  }
}

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-telemetry-ops-prod"
  workspace_id = module.workspace.id
  format       = "Default"

  definition = {
    "RealTimeQueryset.json" = {
      source           = "${path.module}/files/RealTimeQueryset.json.tmpl"
      tokens_delimiter = "<<>>"
      processing_mode  = "GoTemplate"
      tokens = {
        DefaultDatabaseId = "11111111-1111-1111-1111-111111111111"
      }
    }
  }
}

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-telemetry-ops-prod"
  workspace_id = module.workspace.id
  format       = "Default"

  definition = {
    "RealTimeQueryset.json" = {
      source          = "${path.module}/files/RealTimeQueryset.json.tmpl"
      processing_mode = "Parameters"
      parameters = [
        {
          type  = "JsonPathReplace"
          find  = "$.properties.defaultDatabaseId"
          value = "22222222-2222-2222-2222-222222222222"
        }
      ]
    }
  }
}

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-telemetry-ops-prod"
  workspace_id = module.workspace.id
  format       = "Default"

  definition = {
    "RealTimeQueryset.json" = {
      source          = "${path.module}/files/RealTimeQueryset.json.tmpl"
      processing_mode = "Parameters"
      parameters = [
        {
          type  = "TextReplace"
          find  = "__ENVIRONMENT__"
          value = "prod"
        }
      ]
    }
  }
}

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-telemetry-ops-prod"
  workspace_id = module.workspace.id

  timeouts = {
    create = "20m"
    update = "10m"
  }
}

locals {
  querysets = {
    ops     = "kqs-ops-metrics-prod"
    claims  = "kqs-claims-triage-prod"
    finance = "kqs-finance-recon-prod"
  }
}

module "kql_queryset" {
  source   = "../../"
  for_each = local.querysets

  display_name = each.value
  workspace_id = module.workspace.id
}

# NOT a working example — illustrates the failure mode described above.
# module "kql_queryset" {
# source = "../../"
# display_name = "kqs-readonly-attempt"
# workspace_id = module.workspace.id # workspace where caller only holds Viewer
# }

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-curated-metrics-prod"
  workspace_id = module.workspace.id
  folder_id    = module.folder_curated.id
}

module "kql_queryset" {
  source = "../../"

  display_name = "kqs-placeholder-dev"
  workspace_id = module.workspace.id
  format       = "Default"
}

module "workspace" {
  source = "git::https://github.com/microsoftexpert/terraform-fabric-workspace.git?ref=v1.0.0"

  display_name = "ws-observability-core-prod"
  description  = "Core observability workspace — prod. Owner: Observability."
}

module "folder_curated" {
  source = "git::https://github.com/microsoftexpert/terraform-fabric-folder.git?ref=v1.0.0"

  workspace_id = module.workspace.id
  display_name = "curated"
}

resource "fabric_tag" "observability" {
  display_name = "observability"
}

module "kql_queryset" {
  source = "git::https://github.com/microsoftexpert/terraform-fabric-kql-queryset.git?ref=v1.0.0"

  display_name = "kqs-telemetry-ops-prod"
  description  = "Curated telemetry queryset — prod. Owner: Observability."
  workspace_id = module.workspace.id
  folder_id    = module.folder_curated.id
  format       = "Default"

  definition = {
    "RealTimeQueryset.json" = {
      source          = "${path.module}/files/RealTimeQueryset.json.tmpl"
      processing_mode = "GoTemplate"
      tokens = {
        DefaultDatabaseId = "33333333-3333-3333-3333-333333333333"
      }
    }
  }

  tags = [fabric_tag.observability.id]
}

variable "definition" {
  type = map(object({
    source           = string
    tokens_delimiter = optional(string, "{{}}")
    tokens           = optional(map(string), {})
    processing_mode  = optional(string, "None")
    parameters = optional(set(object({
      find  = string
      type  = string
      value = string
    })), [])
  }))
  default = {}
}

variable "timeouts" {
  type = object({
    create = optional(string)
    read   = optional(string)
    update = optional(string)
    delete = optional(string)
  })
  default = null
}

• definition and timeouts are assigned directly with = in main.tf — never a dynamic block — since the live v1.12.0 schema documents both as Terraform Plugin Framework Attributes types, not classic SDKv2 Blocks. This mirrors the resolution already established by terraform-fabric-lakehouse, terraform-fabric-sql-database, and terraform-fabric-workspace elsewhere in this library.
• The live schema does not expose a top-level reference to a target KQL database/Eventhouse. A Queryset's default database context lives inside the definition JSON payload itself (e.g. a defaultDatabaseId field), typically injected via parameters (JsonPathReplace against $.properties.defaultDatabaseId) rather than as a separate Terraform argument. Do not add a kql_database_id-shaped variable to this module — it would map to nothing in the schema.
• definition currently accepts exactly one part key ("RealTimeQueryset.json", paired with format = "Default") — still modeled as a generic map(object(...)) rather than a single nested object, so the module doesn't hard-code an assumption that the provider will never add a second accepted format.
• processing_mode's module-level default ("None") deliberately overrides the provider's own "GoTemplate" default per this module suite's conventions § Secure-by-default — no implicit token substitution without an explicit caller opt-in.

cd C:\GitHubCode\newfabricmodules\terraform-fabric-kql-queryset
terraform init -backend=false
terraform validate
terraform fmt -check

Pin consumers to ?ref=v1.0.0 — never a branch. This module is plan-only; a human applies from a reviewed, approved CI pipeline.

• terraform validate catches: a malformed definition entry (missing source, illegal tokens_delimiter/processing_mode/parameters[].type value), an illegal format value, an empty display_name/workspace_id.
• terraform fmt -check catches formatting drift without silently rewriting files.
• Not caught offline: whether the calling principal actually holds a workspace role permitting KQL Queryset writes, whether the target capacity is Active, whether the tenant's "Service principals can call Fabric public APIs" setting is enabled, or whether a definition payload's embedded database reference actually resolves to a real KQL database. These require a live plan/apply against a real tenant.

module.kql_queryset.id = "4a7b2c1d-9e3f-4a8b-b2f1-6c5d8e9f0a1b"
module.kql_queryset.display_name = "kqs-telemetry-ops-prod"

• fabric_kql_queryset provider resource docs
• Microsoft Learn — Create a KQL queryset
• Microsoft Learn — Roles in workspaces in Microsoft Fabric
• Sibling modules: terraform-fabric-workspace, terraform-fabric-folder, terraform-fabric-tag, terraform-fabric-kql-database, terraform-fabric-kql-dashboard
• This module's SCOPE.md