[Feature] Add key argument to databricks_jobs data source to support duplicate job names (#4796)

## Changes
Added support for handling jobs with duplicate names in the
`databricks_jobs` data source by introducing a new `key` parameter that
allows users to choose between using job names (default) or job IDs as
the mapping keys. This maintains backward compatibility while providing
flexibility for workspaces with duplicate job names.

Key changes:
- Added `key` parameter with options "name" (default) or "id"
- When `key = "id"`, the data source uses job IDs as keys, allowing
duplicate job names
- When `key = "name"` (default), maintains existing behavior of erroring
on duplicate names
- Added test coverage for new functionality

Close #4266 

## Tests
<!-- 
How is this tested? Please see the checklist below and also describe any
other relevant tests
-->

- [X] `make test` run locally
- [X] relevant change in `docs/` folder

---------

Co-authored-by: Zach King <[email protected]>

Author: zcking

NEXT_CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Breaking Changes
 
 ### New Features and Improvements
+* Added `key` argument to `databricks_jobs` data source to enable mapping by job ID and allow duplicate job names ([#4796](https://github.com/databricks/terraform-provider-databricks/pull/4796)).
 
 ### Bug Fixes
 

docs/data-sources/jobs.md

@@ -7,7 +7,7 @@ Retrieves a list of [databricks_job](../resources/job.md) ids, that were created
 
 -> This data source can only be used with a workspace-level provider!
 
-~> Data resource will error in case of jobs with duplicate names.
+~> By default, this data resource will error in case of jobs with duplicate names. To support duplicate names, set `key = "id"` to map jobs by ID.
 
 ## Example Usage
 
@@ -16,10 +16,6 @@ Granting view [databricks_permissions](../resources/permissions.md) to all [data
 ```hcl
 data "databricks_jobs" "this" {}
 
-data "databricks_jobs" "tests" {
-  job_name_contains = "test"
-}
-
 resource "databricks_permissions" "everyone_can_view_all_jobs" {
   for_each = data.databricks_jobs.this.ids
   job_id   = each.value
@@ -34,17 +30,38 @@ resource "databricks_permissions" "everyone_can_view_all_jobs" {
 Getting ID of specific [databricks_job](../resources/job.md) by name:
 
 ```hcl
-data "databricks_jobs" "this" {}
+data "databricks_jobs" "this" {
+  job_name_contains = "test"
+}
 
 output "x" {
   value     = "ID of `x` job is ${data.databricks_jobs.this.ids["x"]}"
   sensitive = false
 }
 ```
 
+Getting IDs of [databricks_job](../resources/job.md) mapped by ID, allowing duplicate job names:
+
+```hcl
+data "databricks_jobs" "this" {
+  key = "id"
+}
+
+resource "databricks_permissions" "everyone_can_view_all_jobs" {
+  for_each = data.databricks_jobs.this.ids
+  job_id   = each.value
+
+  access_control {
+    group_name       = "users"
+    permission_level = "CAN_VIEW"
+  }
+}
+```
+
 ## Argument Reference
 
 * `job_name_contains` - (Optional) Only return [databricks_job](../resources/job.md#) ids that match the given name string (case-insensitive).
+* `key` - (Optional) Attribute to use for keys in the returned map of [databricks_job](../resources/job.md#) ids by. Possible values are `name` (default) or `id`. Setting to `id` uses the job ID as the map key, allowing duplicate job names.
 
 ## Attribute Reference
 

jobs/data_jobs.go

@@ -11,14 +11,21 @@ import (
 	"github.com/databricks/terraform-provider-databricks/common"
 )
 
+const (
+	JobsGroupByName = "name"
+	JobsGroupByID   = "id"
+)
+
 func DataSourceJobs() common.Resource {
 	return common.WorkspaceData(func(ctx context.Context, data *struct {
 		Ids        map[string]string `json:"ids,omitempty" tf:"computed"`
 		NameFilter string            `json:"job_name_contains,omitempty"`
+		Key        string            `json:"key,omitempty" tf:"default:name"`
 	}, w *databricks.WorkspaceClient) error {
 		iter := w.Jobs.List(ctx, jobs.ListJobsRequest{ExpandTasks: false, Limit: 100})
 		data.Ids = map[string]string{}
 		nameFilter := strings.ToLower(data.NameFilter)
+		keyAttribute := strings.ToLower(data.Key)
 		for iter.HasNext(ctx) {
 			job, err := iter.Next(ctx)
 			if err != nil {
@@ -28,11 +35,22 @@ func DataSourceJobs() common.Resource {
 			if nameFilter != "" && !strings.Contains(strings.ToLower(name), nameFilter) {
 				continue
 			}
-			_, duplicateName := data.Ids[name]
-			if duplicateName {
-				return fmt.Errorf("duplicate job name detected: %s", name)
+			jobId := strconv.FormatInt(job.JobId, 10)
+
+			key := name
+			if strings.EqualFold(keyAttribute, JobsGroupByName) {
+				key = name
+			} else if strings.EqualFold(keyAttribute, JobsGroupByID) {
+				key = jobId
+			} else {
+				return fmt.Errorf("unsupported key %s, must be one of %s or %s", keyAttribute, JobsGroupByName, JobsGroupByID)
+			}
+
+			_, duplicateKey := data.Ids[key]
+			if duplicateKey {
+				return fmt.Errorf("duplicate job %s detected: %s", keyAttribute, key)
 			}
-			data.Ids[name] = strconv.FormatInt(job.JobId, 10)
+			data.Ids[key] = jobId
 		}
 		return nil
 	})

jobs/data_jobs_test.go

@@ -75,3 +75,88 @@ func TestJobsDataWithFilter(t *testing.T) {
 		},
 	})
 }
+
+func TestJobsDataWithKeyID(t *testing.T) {
+	qa.ResourceFixture{
+		MockWorkspaceClientFunc: func(w *mocks.MockWorkspaceClient) {
+			iterator := listing.SliceIterator[jobs.BaseJob]{
+				{
+					JobId: 123,
+					Settings: &jobs.JobSettings{
+						Name: "First",
+					},
+				},
+				{
+					JobId: 234,
+					Settings: &jobs.JobSettings{
+						Name: "Second",
+					},
+				},
+			}
+			w.GetMockJobsAPI().EXPECT().
+				List(mock.Anything, jobs.ListJobsRequest{ExpandTasks: false, Limit: 100}).
+				Return(&iterator)
+		},
+		Resource:    DataSourceJobs(),
+		Read:        true,
+		NonWritable: true,
+		ID:          "_",
+		HCL:         `key = "id"`,
+	}.ApplyAndExpectData(t, map[string]any{
+		"ids": map[string]any{
+			"123": "123",
+			"234": "234",
+		},
+	})
+}
+
+func TestJobsDataWithDuplicateNames(t *testing.T) {
+	qa.ResourceFixture{
+		MockWorkspaceClientFunc: func(w *mocks.MockWorkspaceClient) {
+			iterator := listing.SliceIterator[jobs.BaseJob]{
+				{
+					JobId: 123,
+					Settings: &jobs.JobSettings{
+						Name: "Duplicate",
+					},
+				},
+				{
+					JobId: 234,
+					Settings: &jobs.JobSettings{
+						Name: "Duplicate",
+					},
+				},
+			}
+			w.GetMockJobsAPI().EXPECT().
+				List(mock.Anything, jobs.ListJobsRequest{ExpandTasks: false, Limit: 100}).
+				Return(&iterator)
+		},
+		Resource:    DataSourceJobs(),
+		Read:        true,
+		NonWritable: true,
+		ID:          "_",
+	}.ExpectError(t, "duplicate job name detected: Duplicate")
+}
+
+func TestJobsDataWithInvalidKey(t *testing.T) {
+	qa.ResourceFixture{
+		MockWorkspaceClientFunc: func(w *mocks.MockWorkspaceClient) {
+			iterator := listing.SliceIterator[jobs.BaseJob]{
+				{
+					JobId: 123,
+					Settings: &jobs.JobSettings{
+						Name: "First",
+					},
+				},
+			}
+			w.GetMockJobsAPI().EXPECT().
+				List(mock.Anything, jobs.ListJobsRequest{ExpandTasks: false, Limit: 100}).
+				Return(&iterator)
+		},
+		Resource:    DataSourceJobs(),
+		Read:        true,
+		NonWritable: true,
+		ID:          "_",
+		HCL:         `key = "invalid"`,
+	}.ExpectError(t, "unsupported key invalid, must be one of name or id")
+}