@kyuda/n8n-nodes-databricks 2.0.0

package/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright 2022 n8n
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# @kyuda/n8n-nodes-databricks
+
+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.
+
+## Features
+
+- **Genie AI Assistant** -- Start conversations, send messages, and execute SQL queries through Databricks' AI assistant
+- **Databricks SQL** -- Execute SQL queries with automatic chunked result retrieval
+- **Unity Catalog** -- Manage catalogs, schemas, tables, volumes, and functions
+- **Model Serving** -- Query deployed ML/LLM endpoints with auto-detected input format
+- **Files** -- Upload, download, list, and manage files in Unity Catalog volumes (up to 5 GiB)
+- **Vector Search** -- Semantic similarity search with reranking support
+- **Jobs** -- Run, create, list, cancel, and monitor Databricks job runs
+- **Clusters** -- List, create, start, stop, and delete Databricks compute clusters
+- **LmChatDatabricks** -- LangChain Chat Model node for Databricks Foundation Model endpoints
+- **EmbeddingsDatabricks** -- LangChain Embeddings node for Databricks embedding endpoints
+- **VectorStoreDatabricks** -- LangChain Vector Store node backed by Databricks Vector Search
+- **DatabricksAiAgent** -- Full AI Agent node with optional MLflow tracing
+
+## Prerequisites
+
+- Node.js 18+
+- pnpm
+- A Databricks workspace with credentials (PAT or OAuth Service Principal)
+
+## Installation
+
+### For Development
+
+```bash
+git clone https://github.com/kyudahq/n8n.git
+cd n8n/@kyuda/n8n-nodes-databricks
+pnpm install
+pnpm build
+```
+
+Link to your n8n installation:
+
+```bash
+npm link
+cd ~/.n8n/custom
+npm link @kyuda/n8n-nodes-databricks
+```
+
+### From npm
+
+```bash
+npm install @kyuda/n8n-nodes-databricks
+```
+
+## Credentials
+
+Two authentication methods are supported:
+
+### Personal Access Token (default)
+
+1. **Host** -- Your Databricks workspace URL (e.g. `https://adb-1234567890123456.7.azuredatabricks.net`)
+2. **Token** -- A Databricks personal access token (generate at User Settings > Access Tokens)
+
+### OAuth M2M (Service Principal)
+
+1. **Host** -- Your Databricks workspace URL
+2. **Client ID** -- The application (client) ID of a Databricks service principal
+3. **Client Secret** -- The secret associated with the service principal
+
+The OAuth flow uses `grant_type=client_credentials` against your workspace's `/oidc/v1/token` endpoint. Tokens are cached and refreshed automatically.
+
+## Resources and Operations
+
+### Databricks (main node)
+
+| Resource | Operations |
+|---|---|
+| **Genie** | Start Conversation, Create Message, Get Message, Execute Message Query, Get Query Results, Get Space |
+| **Databricks SQL** | Execute Query |
+| **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 |
+| **Model Serving** | Query Endpoint (auto-detects chat/completions/embeddings/dataframe formats) |
+| **Files** | Upload File, Download File, Delete File, Get File Info, List Directory, Create Directory, Delete Directory |
+| **Vector Search** | Query Index, Get Index, List Indexes |
+| **Jobs** | Run Job, Get Run Status, Get Run Output, Create Job, List Jobs, Cancel Run, List Runs |
+| **Clusters** | List Clusters, Get Cluster, Create Cluster, Start Cluster, Stop Cluster, Delete Cluster |
+
+### LangChain Nodes
+
+| Node | Description |
+|---|---|
+| **LmChatDatabricks** | Chat model for Databricks Foundation Model APIs or external model endpoints |
+| **EmbeddingsDatabricks** | Text embeddings via Databricks serving endpoints |
+| **VectorStoreDatabricks** | Vector store backed by Databricks Vector Search indexes |
+| **DatabricksAiAgent** | AI agent with tool calling, memory, structured output, streaming, and optional MLflow tracing |
+
+## Architecture
+
+```
+@kyuda/n8n-nodes-databricks/
+├── credentials/
+│   └── Databricks.credentials.ts      # PAT + OAuth M2M
+├── nodes/
+│   ├── Databricks/
+│   │   ├── Databricks.node.ts          # Main node (slim dispatcher)
+│   │   ├── helpers.ts                  # Shared HTTP helper, cache, security utils
+│   │   └── resources/
+│   │       ├── index.ts                # Barrel exports
+│   │       ├── files/                  # operations, parameters, handler
+│   │       ├── genie/                  # operations, parameters, handler
+│   │       ├── databricksSql/          # operations, parameters, handler
+│   │       ├── modelServing/           # operations, parameters, handler
+│   │       ├── unityCatalog/           # operations, parameters, handler
+│   │       ├── vectorSearch/           # operations, parameters, handler
+│   │       ├── jobs/                   # operations, parameters, handler
+│   │       └── clusters/              # operations, parameters, handler
+│   ├── agents/DatabricksAiAgent/       # AI Agent with MLflow
+│   ├── llms/LmChatDatabricks/          # LangChain Chat Model
+│   ├── embeddings/EmbeddingsDatabricks/# LangChain Embeddings
+│   └── vector_store/VectorStoreDatabricks/ # LangChain Vector Store
+└── utils/
+    ├── DatabricksVectorStoreLangChain.ts
+    ├── N8nTool.ts
+    ├── N8nBinaryLoader.ts
+    └── descriptions.ts
+```
+
+### Execution Flow
+
+```
+User selects Resource → Operation → fills Parameters
+        ↓
+    execute() dispatcher (Databricks.node.ts)
+        ↓
+    handlers[resource](ctx, operation, itemIndex)
+        ↓
+    Per-resource handler file (e.g. resources/jobs/handler.ts)
+        ↓
+    databricksApiRequest() (shared helper with auth, host normalization)
+        ↓
+    Databricks REST API
+```
+
+### Security
+
+- **Token masking** -- Bearer tokens and PAT values are scrubbed from all error messages and logs
+- **URL encoding** -- All user-provided path segments are passed through `encodeURIComponent`
+- **Path traversal protection** -- File operations reject paths containing `..`
+- **Cache isolation** -- Cache keys include a hash of the credential token, preventing cross-user cache leaks
+
+## Databricks AI Agent
+
+The **Databricks AI Agent** node provides a LangChain-based agent with:
+
+- **Tool Calling** -- Supports any LangChain tool or MCP toolkit
+- **Memory** -- Conversation history via BaseChatMemory
+- **Structured Output** -- Optional output parser for validated JSON
+- **Streaming** -- Real-time token streaming support
+- **Fallback Models** -- Automatic failover to a secondary model
+- **MLflow Tracing** -- Optional observability with automatic experiment management
+
+When MLflow is enabled, traces appear under `/Shared/n8n-workflows-{workflow-id}` with spans for agent execution, LLM calls, and tool invocations.
+
+## Development
+
+```bash
+pnpm build      # Build the node
+pnpm test       # Run tests
+pnpm lint       # Lint
+pnpm lintfix    # Auto-fix lint issues
+```
+
+## Contributing
+
+Contributions are welcome. Please submit a Pull Request at [github.com/kyudahq/n8n](https://github.com/kyudahq/n8n).
+
+## Resources
+
+- [n8n Documentation](https://docs.n8n.io/)
+- [Databricks API Documentation](https://docs.databricks.com/api/)
+- [n8n Community](https://community.n8n.io/)
+
+## License
+
+[MIT](LICENSE.md)

package/dist/credentials/Databricks.credentials.d.ts

@@ -0,0 +1,10 @@
+import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class Databricks implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    icon: "file:databricks.svg";
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/Databricks.credentials.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Databricks = void 0;
+class Databricks {
+    constructor() {
+        this.name = 'databricks';
+        this.displayName = 'Databricks';
+        this.documentationUrl = 'https://docs.databricks.com/dev-tools/api/latest/authentication.html';
+        this.icon = 'file:databricks.svg';
+        this.properties = [
+            {
+                displayName: 'Authentication Type',
+                name: 'authType',
+                type: 'options',
+                options: [
+                    {
+                        name: 'Personal Access Token',
+                        value: 'pat',
+                        description: 'Authenticate with a Databricks personal access token',
+                    },
+                    {
+                        name: 'OAuth M2M (Service Principal)',
+                        value: 'oauthM2M',
+                        description: 'Authenticate with a service principal using OAuth client credentials',
+                    },
+                ],
+                default: 'pat',
+            },
+            {
+                displayName: 'Host',
+                name: 'host',
+                type: 'string',
+                default: '',
+                placeholder: 'https://adb-xxxxx.xx.azure.databricks.com',
+                required: true,
+                description: 'Domain of your Databricks workspace',
+            },
+            {
+                displayName: 'Personal Access Token',
+                name: 'token',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                placeholder: 'dapixxxxxxxxxxxxxxxxxxxxxx',
+                required: true,
+                description: 'Databricks personal access token',
+                displayOptions: { show: { authType: ['pat'] } },
+            },
+            {
+                displayName: 'Client ID',
+                name: 'clientId',
+                type: 'string',
+                default: '',
+                required: true,
+                placeholder: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+                description: 'Application (client) ID of the Databricks service principal',
+                displayOptions: { show: { authType: ['oauthM2M'] } },
+            },
+            {
+                displayName: 'Client Secret',
+                name: 'clientSecret',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Client secret of the Databricks service principal',
+                displayOptions: { show: { authType: ['oauthM2M'] } },
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.token}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.host}}',
+                url: '/api/2.0/serving-endpoints',
+                method: 'GET',
+            },
+        };
+    }
+}
+exports.Databricks = Databricks;
+//# sourceMappingURL=Databricks.credentials.js.map

package/dist/credentials/Databricks.credentials.js.map

@@ -0,0 +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"}

package/dist/credentials/databricks.svg

@@ -0,0 +1,19 @@
+<svg version="1.1" id="Layer_1" xmlns:x="ns_extend;" xmlns:i="ns_ai;" xmlns:graph="ns_graphs;" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 40.1 42" style="enable-background:new 0 0 40.1 42;" xml:space="preserve">
+ <style type="text/css">
+  .st0{fill:#FF3621;}
+ </style>
+ <metadata>
+  <sfw xmlns="ns_sfw;">
+   <slices>
+   </slices>
+   <sliceSourceBounds bottomLeftOrigin="true" height="42" width="40.1" x="-69.1" y="-10.5">
+   </sliceSourceBounds>
+  </sfw>
+ </metadata>
+ <g>
+  <path class="st0" d="M40.1,31.1v-7.4l-0.8-0.5L20.1,33.7l-18.2-10l0-4.3l18.2,9.9l20.1-10.9v-7.3l-0.8-0.5L20.1,21.2L2.6,11.6
+		L20.1,2l14.1,7.7l1.1-0.6V8.3L20.1,0L0,10.9V12L20.1,23l18.2-10v4.4l-18.2,10L0.8,16.8L0,17.3v7.4l20.1,10.9l18.2-9.9v4.3l-18.2,10
+		L0.8,29.5L0,30v1.1L20.1,42L40.1,31.1z">
+  </path>
+ </g>
+</svg>

package/dist/nodes/Databricks/Databricks.node.d.ts

@@ -0,0 +1,18 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription, ILoadOptionsFunctions, INodeListSearchResult } from 'n8n-workflow';
+export declare class Databricks implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        listSearch: {
+            getWarehouses(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
+            getEndpoints(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
+            getCatalogs(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
+            getSchemas(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
+            getVolumes(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
+            getTables(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
+            getFunctions(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
+            getJobs(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
+            getClusters(this: ILoadOptionsFunctions, filter?: string): Promise<INodeListSearchResult>;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}