@kyuda/n8n-nodes-databricks 1.0.3 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/README.md +119 -417
  2. package/dist/credentials/Databricks.credentials.d.ts +1 -1
  3. package/dist/credentials/Databricks.credentials.js +40 -3
  4. package/dist/credentials/Databricks.credentials.js.map +1 -1
  5. package/dist/nodes/Databricks/Databricks.node.d.ts +2 -1
  6. package/dist/nodes/Databricks/Databricks.node.js +223 -1699
  7. package/dist/nodes/Databricks/Databricks.node.js.map +1 -1
  8. package/dist/nodes/Databricks/helpers.d.ts +27 -0
  9. package/dist/nodes/Databricks/helpers.js +169 -0
  10. package/dist/nodes/Databricks/helpers.js.map +1 -0
  11. package/dist/nodes/Databricks/resources/clusters/handler.d.ts +2 -0
  12. package/dist/nodes/Databricks/resources/clusters/handler.js +38 -0
  13. package/dist/nodes/Databricks/resources/clusters/handler.js.map +1 -0
  14. package/dist/nodes/Databricks/resources/clusters/operations.d.ts +2 -0
  15. package/dist/nodes/Databricks/resources/clusters/operations.js +24 -0
  16. package/dist/nodes/Databricks/resources/clusters/operations.js.map +1 -0
  17. package/dist/nodes/Databricks/resources/clusters/parameters.d.ts +2 -0
  18. package/dist/nodes/Databricks/resources/clusters/parameters.js +49 -0
  19. package/dist/nodes/Databricks/resources/clusters/parameters.js.map +1 -0
  20. package/dist/nodes/Databricks/resources/databricksSql/handler.d.ts +2 -0
  21. package/dist/nodes/Databricks/resources/databricksSql/handler.js +59 -0
  22. package/dist/nodes/Databricks/resources/databricksSql/handler.js.map +1 -0
  23. package/dist/nodes/Databricks/resources/files/handler.d.ts +2 -0
  24. package/dist/nodes/Databricks/resources/files/handler.js +157 -0
  25. package/dist/nodes/Databricks/resources/files/handler.js.map +1 -0
  26. package/dist/nodes/Databricks/resources/genie/handler.d.ts +2 -0
  27. package/dist/nodes/Databricks/resources/genie/handler.js +54 -0
  28. package/dist/nodes/Databricks/resources/genie/handler.js.map +1 -0
  29. package/dist/nodes/Databricks/resources/index.d.ts +10 -0
  30. package/dist/nodes/Databricks/resources/index.js +19 -0
  31. package/dist/nodes/Databricks/resources/index.js.map +1 -1
  32. package/dist/nodes/Databricks/resources/jobs/handler.d.ts +2 -0
  33. package/dist/nodes/Databricks/resources/jobs/handler.js +84 -0
  34. package/dist/nodes/Databricks/resources/jobs/handler.js.map +1 -0
  35. package/dist/nodes/Databricks/resources/jobs/operations.js +7 -18
  36. package/dist/nodes/Databricks/resources/jobs/operations.js.map +1 -1
  37. package/dist/nodes/Databricks/resources/jobs/parameters.js +49 -0
  38. package/dist/nodes/Databricks/resources/jobs/parameters.js.map +1 -1
  39. package/dist/nodes/Databricks/resources/modelServing/handler.d.ts +2 -0
  40. package/dist/nodes/Databricks/resources/modelServing/handler.js +75 -0
  41. package/dist/nodes/Databricks/resources/modelServing/handler.js.map +1 -0
  42. package/dist/nodes/Databricks/resources/unityCatalog/handler.d.ts +2 -0
  43. package/dist/nodes/Databricks/resources/unityCatalog/handler.js +146 -0
  44. package/dist/nodes/Databricks/resources/unityCatalog/handler.js.map +1 -0
  45. package/dist/nodes/Databricks/resources/unityCatalog/operations.js +5 -0
  46. package/dist/nodes/Databricks/resources/unityCatalog/operations.js.map +1 -1
  47. package/dist/nodes/Databricks/resources/unityCatalog/parameters.js +41 -0
  48. package/dist/nodes/Databricks/resources/unityCatalog/parameters.js.map +1 -1
  49. package/dist/nodes/Databricks/resources/vectorSearch/handler.d.ts +2 -0
  50. package/dist/nodes/Databricks/resources/vectorSearch/handler.js +50 -0
  51. package/dist/nodes/Databricks/resources/vectorSearch/handler.js.map +1 -0
  52. package/dist/nodes/vector_store/shared/createVectorStoreNode/methods/listSearch.js +1 -1
  53. package/dist/nodes/vector_store/shared/createVectorStoreNode/methods/listSearch.js.map +1 -1
  54. package/dist/package.json +19 -14
  55. package/dist/tsconfig.tsbuildinfo +1 -1
  56. package/dist/utils/DatabricksVectorStoreLangChain.js +11 -9
  57. package/dist/utils/DatabricksVectorStoreLangChain.js.map +1 -1
  58. package/package.json +19 -14
  59. package/dist/nodes/Databricks/resources/databricksSql.d.ts +0 -3
  60. package/dist/nodes/Databricks/resources/databricksSql.js +0 -130
  61. package/dist/nodes/Databricks/resources/databricksSql.js.map +0 -1
  62. package/dist/nodes/Databricks/resources/files.d.ts +0 -3
  63. package/dist/nodes/Databricks/resources/files.js +0 -183
  64. package/dist/nodes/Databricks/resources/files.js.map +0 -1
  65. package/dist/nodes/Databricks/resources/modelServing.d.ts +0 -3
  66. package/dist/nodes/Databricks/resources/modelServing.js +0 -176
  67. package/dist/nodes/Databricks/resources/modelServing.js.map +0 -1
  68. package/dist/nodes/Databricks/resources/unityCatalog.d.ts +0 -3
  69. package/dist/nodes/Databricks/resources/unityCatalog.js +0 -239
  70. package/dist/nodes/Databricks/resources/unityCatalog.js.map +0 -1
package/README.md CHANGED
@@ -1,471 +1,173 @@
1
- # n8n-nodes-databricks
1
+ # @kyuda/n8n-nodes-databricks
2
2
 
3
- This is an n8n community node that provides comprehensive integration with Databricks APIs, including Genie AI, SQL, Unity Catalog, Model Serving, Files, and Vector Search capabilities.
4
-
5
- ![n8n.io - Workflow Automation](https://raw.githubusercontent.com/n8n-io/n8n/master/assets/n8n-logo.png)
3
+ Comprehensive Databricks integration for n8n. Provides nodes for SQL, Unity Catalog, Jobs, Clusters, Files, Genie AI, Vector Search, Model Serving, and LangChain AI Agent / Chat / Embedding / Vector Store nodes.
6
4
 
7
5
  ## Features
8
6
 
9
- - 🤖 **Genie AI Assistant**: Start conversations, send messages, and execute SQL queries through Databricks' AI assistant
10
- - 🤖 **AI Agent with MLflow Tracking**: Full-featured AI agent with optional MLflow observability for comprehensive tracing
11
- - 📂 **File Operations**: Upload, download, list, and manage files in Databricks volumes (up to 5 GiB)
12
- - 🗄️ **Databricks SQL**: Execute SQL queries and manage statements
13
- - 📚 **Unity Catalog**: Manage catalogs, schemas, tables, and volumes
14
- - 🤖 **Model Serving**: Query AI models and manage endpoints
15
- - 🔍 **Vector Search**: Perform vector similarity searches
7
+ - **Genie AI Assistant** -- Start conversations, send messages, and execute SQL queries through Databricks' AI assistant
8
+ - **Databricks SQL** -- Execute SQL queries with automatic chunked result retrieval
9
+ - **Unity Catalog** -- Manage catalogs, schemas, tables, volumes, and functions
10
+ - **Model Serving** -- Query deployed ML/LLM endpoints with auto-detected input format
11
+ - **Files** -- Upload, download, list, and manage files in Unity Catalog volumes (up to 5 GiB)
12
+ - **Vector Search** -- Semantic similarity search with reranking support
13
+ - **Jobs** -- Run, create, list, cancel, and monitor Databricks job runs
14
+ - **Clusters** -- List, create, start, stop, and delete Databricks compute clusters
15
+ - **LmChatDatabricks** -- LangChain Chat Model node for Databricks Foundation Model endpoints
16
+ - **EmbeddingsDatabricks** -- LangChain Embeddings node for Databricks embedding endpoints
17
+ - **VectorStoreDatabricks** -- LangChain Vector Store node backed by Databricks Vector Search
18
+ - **DatabricksAiAgent** -- Full AI Agent node with optional MLflow tracing
16
19
 
17
20
  ## Prerequisites
18
21
 
19
- You need the following installed on your development machine:
20
-
21
- * [git](https://git-scm.com/downloads)
22
- * Node.js and pnpm. Minimum version Node 18. You can find instructions on how to install both using nvm (Node Version Manager) for Linux, Mac, and WSL [here](https://github.com/nvm-sh/nvm). For Windows users, refer to Microsoft's guide to [Install NodeJS on Windows](https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows).
23
- * Install n8n with:
24
- ```
25
- pnpm install n8n -g
26
- ```
27
- * A Databricks workspace with a personal access token
22
+ - Node.js 18+
23
+ - pnpm
24
+ - A Databricks workspace with credentials (PAT or OAuth Service Principal)
28
25
 
29
26
  ## Installation
30
27
 
31
28
  ### For Development
32
29
 
33
- 1. Clone this repository:
34
- ```bash
35
- git clone https://github.com/<your-org>/n8n-nodes-databricks.git
36
- cd n8n-nodes-databricks
37
- ```
38
-
39
- 2. Install dependencies:
40
- ```bash
41
- pnpm install
42
- ```
30
+ ```bash
31
+ git clone https://github.com/kyudahq/n8n.git
32
+ cd n8n/@kyuda/n8n-nodes-databricks
33
+ pnpm install
34
+ pnpm build
35
+ ```
43
36
 
44
- 3. Build the node:
45
- ```bash
46
- pnpm build
47
- ```
37
+ Link to your n8n installation:
48
38
 
49
- 4. Link to your n8n installation:
50
- ```bash
51
- npm link
52
- cd ~/.n8n/custom
53
- npm link n8n-nodes-databricks
54
- ```
39
+ ```bash
40
+ npm link
41
+ cd ~/.n8n/custom
42
+ npm link @kyuda/n8n-nodes-databricks
43
+ ```
55
44
 
56
- ### From npm (Coming Soon)
45
+ ### From npm
57
46
 
58
47
  ```bash
59
- npm install n8n-nodes-databricks
48
+ npm install @kyuda/n8n-nodes-databricks
60
49
  ```
61
50
 
62
51
  ## Credentials
63
52
 
64
- ![Credential Setup](./docs/images/credential-setup.png)
65
-
66
- To use this node, you need to configure Databricks credentials:
67
-
68
- 1. **Host**: Your Databricks workspace URL (e.g., `https://adb-1234567890123456.7.azuredatabricks.net`)
69
- 2. **Token**: Your Databricks personal access token
70
-
71
- To generate a token:
53
+ Two authentication methods are supported:
72
54
 
73
- ![Databricks Token Generation](./docs/images/databricks-token-generation.png)
55
+ ### Personal Access Token (default)
74
56
 
75
- 1. Log into your Databricks workspace
76
- 2. Go to User Settings Access Tokens
77
- 3. Click "Generate New Token"
78
- 4. Copy and save the token securely
57
+ 1. **Host** -- Your Databricks workspace URL (e.g. `https://adb-1234567890123456.7.azuredatabricks.net`)
58
+ 2. **Token** -- A Databricks personal access token (generate at User Settings > Access Tokens)
79
59
 
80
- ## Architecture
60
+ ### OAuth M2M (Service Principal)
81
61
 
82
- ### 📊 Project Structure
62
+ 1. **Host** -- Your Databricks workspace URL
63
+ 2. **Client ID** -- The application (client) ID of a Databricks service principal
64
+ 3. **Client Secret** -- The secret associated with the service principal
83
65
 
84
- ```
85
- n8n-nodes-databricks/
86
-
87
- ├── 🎯 Main Node Entry Point
88
- │ └── nodes/Databricks/Databricks.node.ts
89
- │ ├── Class: Databricks (implements INodeType)
90
- │ ├── Properties:
91
- │ │ ├── displayName: 'Databricks'
92
- │ │ ├── version: 1
93
- │ │ ├── usableAsTool: true (can be used as an AI agent tool)
94
- │ │ └── requestDefaults: { baseURL, Authorization }
95
- │ │
96
- │ ├── Node Configuration:
97
- │ │ ├── Resource selector (dropdown):
98
- │ │ │ ├── Genie (AI Assistant)
99
- │ │ │ ├── Databricks SQL
100
- │ │ │ ├── Unity Catalog
101
- │ │ │ ├── Model Serving
102
- │ │ │ ├── Files
103
- │ │ │ └── Vector Search
104
- │ │ │
105
- │ │ ├── Operations (per resource)
106
- │ │ └── Parameters (per resource)
107
- │ │
108
- │ └── Execute Method:
109
- │ ├── Process each input item
110
- │ ├── Handle special cases (custom logic)
111
- │ └── Error handling with continueOnFail support
112
-
113
- ├── 📁 Resource Definitions
114
- │ └── nodes/Databricks/resources/
115
- │ ├── index.ts (exports all operations & parameters)
116
- │ │
117
- │ ├── 🤖 genie/
118
- │ │ ├── operations.ts
119
- │ │ │ └── Operations: [6 operations]
120
- │ │ │ ├── startConversation
121
- │ │ │ ├── createMessage
122
- │ │ │ ├── getMessage
123
- │ │ │ ├── executeMessageQuery
124
- │ │ │ ├── getQueryResults
125
- │ │ │ └── getSpace
126
- │ │ │
127
- │ │ └── parameters.ts
128
- │ │ └── Parameters: spaceId, conversationId, messageId, etc.
129
- │ │
130
- │ ├── 📂 files/
131
- │ │ ├── operations.ts
132
- │ │ │ └── Operations: [7 operations]
133
- │ │ │ ├── uploadFile (PUT binary data)
134
- │ │ │ ├── downloadFile (GET file content)
135
- │ │ │ ├── deleteFile (DELETE)
136
- │ │ │ ├── getFileInfo (HEAD metadata)
137
- │ │ │ ├── listDirectory (GET directory contents)
138
- │ │ │ ├── createDirectory (PUT)
139
- │ │ │ └── deleteDirectory (DELETE)
140
- │ │ │
141
- │ │ └── parameters.ts
142
- │ │
143
- │ ├── 🗄️ databricksSql/
144
- │ ├── 📚 unityCatalog/
145
- │ ├── 🤖 modelServing/
146
- │ └── 🔍 vectorSearch/
147
-
148
- ├── 🤖 AI Agent Node
149
- │ └── nodes/agents/DatabricksAiAgent/
150
- │ ├── DatabricksAiAgent.node.ts (node definition)
151
- │ ├── execute.ts (agent execution with MLflow)
152
- │ ├── CallbackHandler.ts (MLflow tracing)
153
- │ ├── description.ts (node properties)
154
- │ ├── utils.ts (input configuration)
155
- │ └── src/
156
- │ ├── constants.ts (MLflow constants)
157
- │ ├── types/ (TypeScript types)
158
- │ └── utils/ (helper functions)
159
-
160
- ├── 🔐 Credentials
161
- │ └── credentials/Databricks.credentials.ts
162
- │ └── DatabricksCredentials interface:
163
- │ ├── host: string (Databricks workspace URL)
164
- │ └── token: string (Personal access token)
165
-
166
- └── 🎨 Assets
167
- ├── databricks.svg (light mode icon)
168
- └── databricks.dark.svg (dark mode icon)
169
- ```
66
+ The OAuth flow uses `grant_type=client_credentials` against your workspace's `/oidc/v1/token` endpoint. Tokens are cached and refreshed automatically.
170
67
 
171
- ### 🔄 Execution Flow
68
+ ## Resources and Operations
172
69
 
173
- ```
174
- User Input (n8n workflow)
175
-
176
- 1. User selects RESOURCE (e.g., "Genie")
177
-
178
- 2. User selects OPERATION (e.g., "Start Conversation")
179
-
180
- 3. UI displays relevant PARAMETERS (using displayOptions.show)
181
-
182
- 4. User fills in parameters (spaceId, initialMessage, etc.)
183
-
184
- 5. Execute method is called
185
-
186
- 6. Two execution paths:
187
-
188
- ├─→ Path A: Declarative Routing (most operations)
189
- │ ├── n8n uses 'routing' config from operations.ts
190
- │ ├── Automatically builds HTTP request
191
- │ ├── Substitutes parameters using {{$parameter.xxx}}
192
- │ └── Sends request with credentials from requestDefaults
193
-
194
- └─→ Path B: Custom Logic (special cases)
195
- ├── Files.uploadFile → Custom binary data handling
196
- └── Genie operations → Custom switch statement
197
- ├── Build URL dynamically
198
- ├── Create request body
199
- ├── Call this.helpers.httpRequest()
200
- └── Return response
201
-
202
- 7. Return INodeExecutionData[][]
203
- ```
70
+ ### Databricks (main node)
204
71
 
205
- ### 🧩 Key Architectural Patterns
206
-
207
- #### 1. Resource-Based Organization
208
- Each Databricks API category is a separate "resource" with its own operations and parameters.
209
-
210
- #### 2. Declarative Routing
211
- Most operations use n8n's declarative `routing` configuration:
212
- ```typescript
213
- routing: {
214
- request: {
215
- method: 'POST',
216
- url: '=/api/2.0/genie/spaces/{{$parameter.spaceId}}/conversations',
217
- body: {
218
- initial_message: '={{$parameter.initialMessage}}'
219
- }
220
- }
221
- }
222
- ```
72
+ | Resource | Operations |
73
+ |---|---|
74
+ | **Genie** | Start Conversation, Create Message, Get Message, Execute Message Query, Get Query Results, Get Space |
75
+ | **Databricks SQL** | Execute Query |
76
+ | **Unity Catalog** | Create/Get/Update/Delete Catalog, List Catalogs, Create/Get/Update/Delete Schema, List Schemas, Create/Get/Delete Volume, List Volumes, Get/List Tables, Create/Get/Delete Function, List Functions |
77
+ | **Model Serving** | Query Endpoint (auto-detects chat/completions/embeddings/dataframe formats) |
78
+ | **Files** | Upload File, Download File, Delete File, Get File Info, List Directory, Create Directory, Delete Directory |
79
+ | **Vector Search** | Query Index, Get Index, List Indexes |
80
+ | **Jobs** | Run Job, Get Run Status, Get Run Output, Create Job, List Jobs, Cancel Run, List Runs |
81
+ | **Clusters** | List Clusters, Get Cluster, Create Cluster, Start Cluster, Stop Cluster, Delete Cluster |
223
82
 
224
- #### 3. Conditional Parameter Display
225
- Parameters appear/hide based on selected resource and operation:
226
- ```typescript
227
- displayOptions: {
228
- show: {
229
- resource: ['genie'],
230
- operation: ['startConversation']
231
- }
232
- }
233
- ```
234
-
235
- #### 4. Two Execution Modes
236
- - **Declarative**: n8n handles HTTP requests automatically (most operations)
237
- - **Imperative**: Custom logic in execute() method (files upload, genie operations)
238
-
239
- #### 5. Error Handling
240
- Comprehensive error handling with three types:
241
- - **API Errors**: Status code + error details
242
- - **Network Errors**: Connection failures
243
- - **Other Errors**: General exceptions
83
+ ### LangChain Nodes
244
84
 
245
- All support `continueOnFail` mode for resilient workflows.
85
+ | Node | Description |
86
+ |---|---|
87
+ | **LmChatDatabricks** | Chat model for Databricks Foundation Model APIs or external model endpoints |
88
+ | **EmbeddingsDatabricks** | Text embeddings via Databricks serving endpoints |
89
+ | **VectorStoreDatabricks** | Vector store backed by Databricks Vector Search indexes |
90
+ | **DatabricksAiAgent** | AI agent with tool calling, memory, structured output, streaming, and optional MLflow tracing |
246
91
 
247
- ### 🤖 AI Agent Execution Flow
92
+ ## Architecture
248
93
 
249
94
  ```
250
- User Input → Databricks AI Agent Node
251
-
252
- 1. Load Configuration
253
- ├─ Get Chat Model (required)
254
- ├─ Get Tools (optional)
255
- ├─ Get Memory (optional)
256
- ├─ Get Output Parser (optional)
257
- └─ Check MLflow enabled
258
-
259
- 2. MLflow Setup (if enabled)
260
- ├─ Validate Databricks credentials
261
- ├─ Get/Create experiment: /Shared/n8n-workflows-{workflow-id}
262
- └─ Initialize MLflow CallbackHandler
263
-
264
- 3. Agent Execution
265
- ├─ Create LangChain ToolCallingAgent
266
- ├─ Setup fallback model (if configured)
267
- └─ Execute with streaming or standard mode
268
-
269
- 4. Processing Loop (for each iteration)
270
- ├─ LLM Call MLflow CHAT_MODEL span
271
- ├─ Tool Calls → MLflow TOOL spans
272
- └─ Continue until final answer
273
-
274
- 5. MLflow Tracing (if enabled)
275
- ├─ Log AGENT span with full execution
276
- ├─ Record token usage and latency
277
- └─ Capture all intermediate steps
278
-
279
- 6. Return Result
280
- └─ Output text/structured data to n8n workflow
95
+ @kyuda/n8n-nodes-databricks/
96
+ ├── credentials/
97
+ │ └── Databricks.credentials.ts # PAT + OAuth M2M
98
+ ├── nodes/
99
+ │ ├── Databricks/
100
+ │ │ ├── Databricks.node.ts # Main node (slim dispatcher)
101
+ │ │ ├── helpers.ts # Shared HTTP helper, cache, security utils
102
+ │ │ └── resources/
103
+ │ │ ├── index.ts # Barrel exports
104
+ │ │ ├── files/ # operations, parameters, handler
105
+ │ │ ├── genie/ # operations, parameters, handler
106
+ │ │ ├── databricksSql/ # operations, parameters, handler
107
+ │ │ ├── modelServing/ # operations, parameters, handler
108
+ │ │ ├── unityCatalog/ # operations, parameters, handler
109
+ │ │ ├── vectorSearch/ # operations, parameters, handler
110
+ │ │ ├── jobs/ # operations, parameters, handler
111
+ │ │ └── clusters/ # operations, parameters, handler
112
+ │ ├── agents/DatabricksAiAgent/ # AI Agent with MLflow
113
+ │ ├── llms/LmChatDatabricks/ # LangChain Chat Model
114
+ │ ├── embeddings/EmbeddingsDatabricks/# LangChain Embeddings
115
+ │ └── vector_store/VectorStoreDatabricks/ # LangChain Vector Store
116
+ └── utils/
117
+ ├── DatabricksVectorStoreLangChain.ts
118
+ ├── N8nTool.ts
119
+ ├── N8nBinaryLoader.ts
120
+ └── descriptions.ts
281
121
  ```
282
122
 
283
- ## Development
284
-
285
- ### Building the Node
123
+ ### Execution Flow
286
124
 
287
- ```bash
288
- pnpm build
289
125
  ```
290
-
291
- ### Linting
292
-
293
- ```bash
294
- pnpm lint
295
- # or auto-fix
296
- pnpm lintfix
126
+ User selects Resource → Operation → fills Parameters
127
+
128
+ execute() dispatcher (Databricks.node.ts)
129
+
130
+ handlers[resource](ctx, operation, itemIndex)
131
+
132
+ Per-resource handler file (e.g. resources/jobs/handler.ts)
133
+
134
+ databricksApiRequest() (shared helper with auth, host normalization)
135
+
136
+ Databricks REST API
297
137
  ```
298
138
 
299
- ### Testing
139
+ ### Security
300
140
 
301
- ```bash
302
- pnpm test
303
- ```
141
+ - **Token masking** -- Bearer tokens and PAT values are scrubbed from all error messages and logs
142
+ - **URL encoding** -- All user-provided path segments are passed through `encodeURIComponent`
143
+ - **Path traversal protection** -- File operations reject paths containing `..`
144
+ - **Cache isolation** -- Cache keys include a hash of the credential token, preventing cross-user cache leaks
304
145
 
305
146
  ## Databricks AI Agent
306
147
 
307
- ![Databricks AI Agent](./docs/images/node-example.png)
308
-
309
- The **Databricks AI Agent** node provides a full-featured AI agent built on LangChain's ToolCallingAgent with optional **MLflow observability** for comprehensive tracing of your agent's reasoning, tool usage, and LLM interactions.
310
-
311
- ### Key Features
312
-
313
- #### AI Agent Capabilities
314
- - **Tool Calling** - Supports any LangChain tool or MCP toolkit
315
- - **Memory** - Conversation history with BaseChatMemory
316
- - **Structured Output** - Optional output parser for validated JSON responses
317
- - **Streaming** - Real-time token streaming support
318
- - **Fallback Models** - Automatic failover to secondary model
319
- - **Binary Images** - Automatic passthrough of images to vision models
148
+ The **Databricks AI Agent** node provides a LangChain-based agent with:
320
149
 
321
- #### MLflow Observability (Optional)
322
- - **Toggle On/Off** - Enable MLflow logging with a simple checkbox
323
- - **Automatic Tracing** - Creates MLflow spans for every step when enabled
324
- - **Span Types**:
325
- - `AGENT` - Overall agent execution
326
- - `CHAT_MODEL` - LLM calls with token usage
327
- - `TOOL` - Tool invocations with arguments and results
328
- - `RETRIEVER` - Vector store retrievals (if used)
329
- - **Metrics** - Latency, token counts, model info
330
- - **Tags & Metadata** - Full context for filtering and analysis
150
+ - **Tool Calling** -- Supports any LangChain tool or MCP toolkit
151
+ - **Memory** -- Conversation history via BaseChatMemory
152
+ - **Structured Output** -- Optional output parser for validated JSON
153
+ - **Streaming** -- Real-time token streaming support
154
+ - **Fallback Models** -- Automatic failover to a secondary model
155
+ - **MLflow Tracing** -- Optional observability with automatic experiment management
331
156
 
332
- ### Configuration
157
+ When MLflow is enabled, traces appear under `/Shared/n8n-workflows-{workflow-id}` with spans for agent execution, LLM calls, and tool invocations.
333
158
 
334
- #### Enabling MLflow (Optional)
335
-
336
- MLflow logging is **disabled by default**. To enable it:
337
-
338
- 1. Add the **Databricks AI Agent** node to your workflow
339
- 2. Toggle **"Enable MLflow Tracking"** to ON
340
- 3. Configure Databricks credentials (credential selector appears when enabled)
341
- 4. The node will **automatically** use your workflow ID as the experiment name
342
-
343
- #### MLflow Experiment Management (Automatic)
344
-
345
- When MLflow tracking is enabled, the node **automatically manages experiments**:
346
-
347
- - **Experiment Name**: Automatically set to `/Shared/n8n-workflows-{workflow-id}`
348
- - **Auto-Creation**: If the experiment doesn't exist, it's created automatically
349
- - **Auto-Reuse**: If the experiment exists, it's reused automatically
350
- - **One Workflow = One Experiment**: Each n8n workflow gets its own dedicated MLflow experiment
351
- - **Shared Workspace**: Experiments are created in `/Shared/` for team accessibility
352
-
353
- ### Usage
354
-
355
- #### Basic Agent Setup
356
-
357
- ![Basic Setup Steps](./docs/images/basic-setup-steps.png)
358
-
359
- 1. **Add Agent Node** - Drag "Databricks AI Agent" to your workflow
360
- 2. **Connect Chat Model** - Add OpenAI, Databricks, or compatible model
361
- 3. **Connect Tools** (optional) - Add n8n tools or MCP clients
362
- 4. **Connect Memory** (optional) - Add chat memory for conversations
363
- 5. **Configure Input** - Map user message to the agent
364
-
365
- #### Node Inputs
366
-
367
- The node requires these **connections**:
368
-
369
- - **Chat Model** (required) - The LLM to use
370
- - **Tools** (optional) - Zero or more tools the agent can call
371
- - **Memory** (optional) - For conversation history
372
- - **Output Parser** (optional) - For structured JSON validation
373
-
374
- ### MLflow Traces
375
-
376
- ![MLflow Trace Structure](./docs/images/mlflow-trace-structure.gif)
377
-
378
- Every agent execution creates a trace in Databricks MLflow with:
379
-
380
- - **Agent Span** - Overall execution with messages and system prompt
381
- - **Chat Model Spans** - Each LLM call with:
382
- - Input messages
383
- - Model parameters (temperature, max_tokens, etc.)
384
- - Response with token usage
385
- - Latency metrics
386
- - **Tool Spans** - Each tool invocation with:
387
- - Tool name and description
388
- - Input arguments
389
- - Output results
390
- - Execution time
391
-
392
- **Metrics captured per trace:**
393
- - Total latency
394
- - Total cost
395
- - Total tokens (input + output)
396
- - LLM calls count
397
- - Tool calls count
398
-
399
- ## Usage Examples
400
-
401
- ### Example 1: AI Agent with MLflow Tracking
402
-
403
- 1. Add the **Databricks AI Agent** node to your workflow
404
- 2. Connect a **Chat Model** node (e.g., OpenAI or Databricks Chat Model)
405
- 3. (Optional) Connect **Tools** - Add any n8n tools you want the agent to use
406
- 4. (Optional) Connect **Memory** - Add chat memory for conversation history
407
- 5. Toggle **"Enable MLflow Tracking"** to ON
408
- 6. Select your **Databricks credentials**
409
- 7. Configure the input prompt
410
- 8. Run the workflow - traces will appear in MLflow under `/Shared/n8n-workflows-{workflow-id}`
411
-
412
- ### Example 2: Start a Genie Conversation
413
-
414
- 1. Add the Databricks node to your workflow
415
- 2. Select Resource: **Genie**
416
- 3. Select Operation: **Start Conversation**
417
- 4. Enter your **Space ID**
418
- 5. Enter your **Initial Message**: "Show me sales data for last quarter"
419
-
420
- ### Example 3: Upload a File to Databricks Volume
421
-
422
- 1. Add the Databricks node after a node that provides binary data
423
- 2. Select Resource: **Files**
424
- 3. Select Operation: **Upload File**
425
- 4. Configure:
426
- - Data Field Name: `data`
427
- - Catalog: `main`
428
- - Schema: `default`
429
- - Volume: `my_volume`
430
- - Path: `reports/report.pdf`
159
+ ## Development
431
160
 
432
- ### Example 4: Query Vector Search
433
-
434
- 1. Add the Databricks node to your workflow
435
- 2. Select Resource: **Vector Search**
436
- 3. Select Operation: **Query Index**
437
- 4. Configure your query parameters
438
-
439
- ## Adding New Operations
440
-
441
- To extend this node with new operations:
442
-
443
- 1. Navigate to the appropriate resource folder in `nodes/Databricks/resources/`
444
- 2. Add the new operation to `operations.ts`:
445
- ```typescript
446
- {
447
- name: 'My New Operation',
448
- value: 'myNewOperation',
449
- description: 'Description of what it does',
450
- action: 'Perform my new operation',
451
- routing: {
452
- request: {
453
- method: 'GET',
454
- url: '=/api/2.0/path/{{$parameter.id}}'
455
- }
456
- }
457
- }
458
- ```
459
- 3. Add required parameters to `parameters.ts`
460
- 4. Rebuild and test
161
+ ```bash
162
+ pnpm build # Build the node
163
+ pnpm test # Run tests
164
+ pnpm lint # Lint
165
+ pnpm lintfix # Auto-fix lint issues
166
+ ```
461
167
 
462
168
  ## Contributing
463
169
 
464
- Contributions are welcome! Please feel free to submit a Pull Request.
465
-
466
- ## Support
467
-
468
- For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/<your-org>/n8n-nodes-databricks).
170
+ Contributions are welcome. Please submit a Pull Request at [github.com/kyudahq/n8n](https://github.com/kyudahq/n8n).
469
171
 
470
172
  ## Resources
471
173
 
@@ -1,4 +1,4 @@
1
- import { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
1
+ import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
2
2
  export declare class Databricks implements ICredentialType {
3
3
  name: string;
4
4
  displayName: string;
@@ -8,6 +8,24 @@ class Databricks {
8
8
  this.documentationUrl = 'https://docs.databricks.com/dev-tools/api/latest/authentication.html';
9
9
  this.icon = 'file:databricks.svg';
10
10
  this.properties = [
11
+ {
12
+ displayName: 'Authentication Type',
13
+ name: 'authType',
14
+ type: 'options',
15
+ options: [
16
+ {
17
+ name: 'Personal Access Token',
18
+ value: 'pat',
19
+ description: 'Authenticate with a Databricks personal access token',
20
+ },
21
+ {
22
+ name: 'OAuth M2M (Service Principal)',
23
+ value: 'oauthM2M',
24
+ description: 'Authenticate with a service principal using OAuth client credentials',
25
+ },
26
+ ],
27
+ default: 'pat',
28
+ },
11
29
  {
12
30
  displayName: 'Host',
13
31
  name: 'host',
@@ -21,13 +39,32 @@ class Databricks {
21
39
  displayName: 'Personal Access Token',
22
40
  name: 'token',
23
41
  type: 'string',
24
- typeOptions: {
25
- password: true,
26
- },
42
+ typeOptions: { password: true },
27
43
  default: '',
28
44
  placeholder: 'dapixxxxxxxxxxxxxxxxxxxxxx',
29
45
  required: true,
30
46
  description: 'Databricks personal access token',
47
+ displayOptions: { show: { authType: ['pat'] } },
48
+ },
49
+ {
50
+ displayName: 'Client ID',
51
+ name: 'clientId',
52
+ type: 'string',
53
+ default: '',
54
+ required: true,
55
+ placeholder: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
56
+ description: 'Application (client) ID of the Databricks service principal',
57
+ displayOptions: { show: { authType: ['oauthM2M'] } },
58
+ },
59
+ {
60
+ displayName: 'Client Secret',
61
+ name: 'clientSecret',
62
+ type: 'string',
63
+ typeOptions: { password: true },
64
+ default: '',
65
+ required: true,
66
+ description: 'Client secret of the Databricks service principal',
67
+ displayOptions: { show: { authType: ['oauthM2M'] } },
31
68
  },
32
69
  ];
33
70
  this.authenticate = {
@@ -1 +1 @@
1
- {"version":3,"file":"Databricks.credentials.js","sourceRoot":"","sources":["../../credentials/Databricks.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,UAAU;IAAvB;QACI,SAAI,GAAG,YAAY,CAAC;QACpB,gBAAW,GAAG,YAAY,CAAC;QAC3B,qBAAgB,GAAG,sEAAsE,CAAC;QAC1F,SAAI,GAAG,qBAA8B,CAAC;QACtC,eAAU,GAAsB;YAC5B;gBACI,WAAW,EAAE,MAAM;gBACnB,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,2CAA2C;gBACxD,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,qCAAqC;aACrD;YACD;gBACI,WAAW,EAAE,uBAAuB;gBACpC,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE;oBACT,QAAQ,EAAE,IAAI;iBACjB;gBACD,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,4BAA4B;gBACzC,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,kCAAkC;aAClD;SACJ,CAAC;QAEF,iBAAY,GAAyB;YACjC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACR,OAAO,EAAE;oBACL,aAAa,EAAE,gCAAgC;iBAClD;aACJ;SACJ,CAAC;QAEF,SAAI,GAA2B;YAC3B,OAAO,EAAE;gBACL,OAAO,EAAE,wBAAwB;gBACjC,GAAG,EAAE,4BAA4B;gBACjC,MAAM,EAAE,KAAK;aAChB;SACJ,CAAC;IACN,CAAC;CAAA;AA7CD,gCA6CC"}
1
+ {"version":3,"file":"Databricks.credentials.js","sourceRoot":"","sources":["../../credentials/Databricks.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,UAAU;IAAvB;QACI,SAAI,GAAG,YAAY,CAAC;QACpB,gBAAW,GAAG,YAAY,CAAC;QAC3B,qBAAgB,GAAG,sEAAsE,CAAC;QAC1F,SAAI,GAAG,qBAA8B,CAAC;QACtC,eAAU,GAAsB;YAC5B;gBACI,WAAW,EAAE,qBAAqB;gBAClC,IAAI,EAAE,UAAU;gBAChB,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE;oBACL;wBACI,IAAI,EAAE,uBAAuB;wBAC7B,KAAK,EAAE,KAAK;wBACZ,WAAW,EAAE,sDAAsD;qBACtE;oBACD;wBACI,IAAI,EAAE,+BAA+B;wBACrC,KAAK,EAAE,UAAU;wBACjB,WAAW,EACP,sEAAsE;qBAC7E;iBACJ;gBACD,OAAO,EAAE,KAAK;aACjB;YACD;gBACI,WAAW,EAAE,MAAM;gBACnB,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,2CAA2C;gBACxD,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,qCAAqC;aACrD;YAGD;gBACI,WAAW,EAAE,uBAAuB;gBACpC,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,4BAA4B;gBACzC,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,kCAAkC;gBAC/C,cAAc,EAAE,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE;aAClD;YAGD;gBACI,WAAW,EAAE,WAAW;gBACxB,IAAI,EAAE,UAAU;gBAChB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,sCAAsC;gBACnD,WAAW,EACP,6DAA6D;gBACjE,cAAc,EAAE,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE;aACvD;YACD;gBACI,WAAW,EAAE,eAAe;gBAC5B,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,mDAAmD;gBAChE,cAAc,EAAE,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE;aACvD;SACJ,CAAC;QAEF,iBAAY,GAAyB;YACjC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACR,OAAO,EAAE;oBACL,aAAa,EAAE,gCAAgC;iBAClD;aACJ;SACJ,CAAC;QAEF,SAAI,GAA2B;YAC3B,OAAO,EAAE;gBACL,OAAO,EAAE,wBAAwB;gBACjC,GAAG,EAAE,4BAA4B;gBACjC,MAAM,EAAE,KAAK;aAChB;SACJ,CAAC;IACN,CAAC;CAAA;AAxFD,gCAwFC"}